官方模板层次结构与加载顺序 - WordPress开发

如上所述，  模板文件  是模块化的，可重用的文件，用于在WordPress网站上生成网页。某些模板文件（例如页眉和页脚模板）用于您网站的所有页面，而其他模板文件仅在特定条件下使用。

本文介绍了WordPress如何确定在各个页面上使用哪些模板文件。如果要自定义现有的WordPress主题，它将帮助您确定需要编辑哪个模板文件。

• 原文来源：wordpress文档

提示：

您还可以使用条件标签来控制在特定页面上加载的模板。

模板文件层次结构

概述

WordPress使用查询字符串来决定应该使用哪个模板或模板集来显示页面。查询字符串是包含在网站每个部分的链接中的信息。它出现在初始问号之后，可能包含许多由＆符号分隔的参数。

简而言之，WordPress向下搜索模板层次结构，直到找到匹配的模板文件。要确定要使用的模板文件，WordPress：

1. 将每个查询字符串与查询类型匹配，以决定请求哪个页面（例如，搜索页面，类别页面等）;
2. 按模板层次结构确定的顺序选择模板;
3. 在当前主题的目录中查找具有特定名称的模板文件，并使用层次结构指定的第一个匹配模板文件。

除基本index.php模板文件外，您可以选择是否要实现特定模板文件。

如果WordPress找不到具有匹配名称的模板文件，它将跳转到层次结构中的下一个文件。如果WordPress找不到任何匹配的模板文件，index.php将使用主题的文件。

示例

如果您的博客位于，http://example.com/blog/并且访问者点击指向类别页面的链接，例如  http://example.com/blog/category/your-cat/，WordPress会在当前主题的目录中查找与该类别的ID匹配的模板文件，以生成正确的页面。更具体地说，WordPress遵循以下过程：

1. 在当前主题的目录中查找与类别的slug匹配的模板文件。如果类别slug是“unicorns”，则WordPress会查找名为的模板文件category-unicorns.php。
2. 如果category-unicorns.php缺少并且类别的ID为4，则WordPress将查找名为的模板文件category-4.php。
3. 如果category-4.php缺少，WordPress将寻找通用类别模板文件，category.php。
4. 如果category.php不存在，WordPress将寻找通用存档模板，archive.php。
5. 如果archive.php还缺少，WordPress将回退到主题模板文件，index.php。

视觉概述

下图显示了调用哪些模板文件以基于WordPress模板层次结构生成WordPress页面。

模板层次结构详细信息

虽然模板层次结构更易于理解为图表，但以下部分描述了WordPress为多种查询类型调用模板文件的顺序。

主页显示

默认情况下，WordPress会设置您网站的主页以显示您最新的博文。此页面称为博客帖子索引。您还可以将博客帖子设置为显示在单独的静态页面上。模板文件home.php用于呈现博客帖子索引，无论是用作首页还是用于单独的静态页面。如果  home.php 不存在，WordPress将使用  index.php。

1. home.php
2. index.php

注意：

如果front-page.php 存在，它将覆盖  home.php 模板。

首页显示

该front-page.php模板文件是用来使您的网站的头版，头版是否显示该博客文章的索引（上述）或静态页面。首页模板优先于博客文章index（home.php）模板。如果该front-page.php文件不存在，WordPress将使用home.php或page.php文件，具体取决于设置→阅读中的设置。如果这两个文件都不存在，它将使用该index.php文件。

1. front-page.php - 用于设置→阅读的首页显示部分中设置的“ 您的最新帖子 ”或“ 静态页面 ” 。
2. home.php - 如果WordPress无法找到，  front-page.php并且在首页显示部分设置了“ 您的最新帖子 ” ，则会查找。此外，当在首页显示部分设置帖子页面时，WordPress将查找此文件。home.php
3. page.php - 在首页显示部分设置“ 首页 ”时。
4. index.php -当“ 你最新的帖子 ”被设置在头版显示部分，但  home.php不存在或  在头版设置，但page.php不存在。

正如您所看到的，WordPress采用的路径有很多规则。使用上面的图表是确定WordPress将显示的最佳方式。

单帖

单个帖子模板文件用于呈现单个帖子。WordPress使用以下路径：

1. single-{post-type}-{slug}.php - （从4.4开始）首先，WordPress会查找特定帖子的模板。例如，如果帖子类型是product和post slug是dmc-12，WordPress会寻找single-product-dmc-12.php。
2. single-{post-type}.php- 如果帖子类型是product，WordPress会寻找single-product.php。
3. single.php- 然后WordPress回归single.php。
4. singular.php- 然后它又回落了singular.php。
5. index.php- 最后，如上所述，WordPress最终会回归index.php。

单页

用于呈现静态页面的模板文件（pagepost-type）。请注意，与其他post-types不同，pageWordPress特殊并使用以下路径：

1. custom template file - 分配给页面的页面模板。见get_page_templates()。
2. page-{slug}.php - 如果页面slug是recent-news，WordPress将使用page-recent-news.php。
3. page-{id}.php - 如果页面ID为6，WordPress将使用page-6.php。
4. page.php
5. singular.php
6. index.php

类别

渲染类别归档索引页面在WordPress中使用以下路径：

1. category-{slug}.php - 如果类别的slug是news，WordPress将寻找category-news.php。
2. category-{id}.php - 如果类别的ID是6，WordPress将寻找category-6.php。
3. category.php
4. archive.php
5. index.php

标签

要显示标记归档索引页，WordPress使用以下路径：

1. tag-{slug}.php - 如果标签的slug是sometag，WordPress将寻找tag-sometag.php。
2. tag-{id}.php - 如果标签的ID是6，WordPress将寻找tag-6.php。
3. tag.php
4. archive.php
5. index.php

自定义分类法

自定义分类法使用稍微不同的模板文件路径：

1. taxonomy-{taxonomy}-{term}.php - 如果分类法是sometax，而分类学的术语是someterm，WordPress将寻找taxonomy-sometax-someterm.php.在帖子格式的情况下，分类法是'post_format'，术语是'post-format- {format}。即taxonomy-post_format-post-format-link.php 链接格式。
2. taxonomy-{taxonomy}.php - 如果分类法是sometax，WordPress会寻找taxonomy-sometax.php。
3. taxonomy.php
4. archive.php
5. index.php

自定义帖子类型

自定义帖子类型使用以下路径来呈现相应的存档索引页面。

1. archive-{post_type}.php - 如果帖子类型是product，WordPress将寻找archive-product.php。
2. archive.php
3. index.php

（要渲染单个帖子类型模板，请参阅上面的单个帖子显示部分。）

作者显示

基于以上示例，呈现作者归档索引页面是相当明确的：

1. author-{nicename}.php - 如果作者的名字很好matt，WordPress会寻找author-matt.php。
2. author-{id}.php - 如果作者的ID是6，WordPress将寻找author-6.php。
3. author.php
4. archive.php
5. index.php

日期

基于日期的归档索引页面将按预期呈现：

1. date.php
2. archive.php
3. index.php

搜索结果

搜索结果遵循与其他模板类型相同的模式：

1. search.php
2. index.php

404（未找到）

同样，按以下顺序调用404模板文件：

1. 404.php
2. index.php

附件

呈现附件页面（attachmentpost-type）使用以下路径：

1. {MIME-type}.php-可以是任何的MIME类型（例如：  image.php，video.php，pdf.php）。对于text/plain，使用以下路径（按顺序）：
2. text-plain.php
3. plain.php
4. text.php
5. attachment.php
6. single-attachment-{slug}.php - 例如，如果附件slug是holiday，WordPress会寻找single-attachment-holiday.php。
7. single-attachment.php
8. single.php
9. singular.php
10. index.php

内嵌

嵌入模板文件用于呈现正在嵌入的帖子。从4.5开始，WordPress使用以下路径：

1. embed-{post-type}-{post_format}.php - 首先，WordPress寻找特定帖子的模板。例如，如果它的帖子类型是，post并且它具有音频格式，WordPress会寻找embed-post-audio.php。
2. embed-{post-type}.php- 如果帖子类型是product，WordPress会寻找embed-product.php。
3. embed.php- 然后WordPress回归嵌入.php。
4. 最后，WordPress最终回归到自己的wp-includes/theme-compat/embed.php模板。

非ASCII字符处理

从WordPress 4.7开始，模板名称的任何动态部分（其名称中包含非ASCII字符）实际上都支持未编码形式和编码形式。您可以选择使用哪个。

这是名为“Hello World ” 的页面的页面模板层次结构，其ID为6：

• page-hello-world-.php
• page-hello-world-%f0%9f%98%80.php
• page-6.php
• page.php
• singular.php

相同的行为适用于post slugs，term names和author nicenames。

过滤层次结构

WordPress模板系统允许您过滤层次结构。这意味着您可以在层次结构的特定点插入和更改内容。过滤器（位于get_query_template()函数中）使用此过滤器名称："{$type}_template"其中$type是模板类型。

以下是模板层次结构中所有可用过滤器的列表：

• embed_template
• 404_template
• search_template
• frontpage_template
• home_template
• taxonomy_template
• attachment_template
• single_template
• page_template
• singular_template
• category_template
• tag_template
• author_template
• date_template
• archive_template
• index_template

示例

例如，让我们采用默认的作者层次结构：

• author-{nicename}.php
• author-{id}.php
• author.php

要添加author-{role}.php之前author.php，我们可以使用'author_template'模板类型操纵实际层次结构。这允许对/ author / username的请求，其中username具有编辑器的角色，使用author-editor.php显示（如果存在于当前主题目录中）。

function author_role_template( $templates = '' ) { 
    $author = get_queried_object(); 
    $role = $author->roles[0]; 
    if ( ! is_array( $templates ) && ! empty( $templates ) ) { 
        $templates = locate_template( array( "author-$role.php", $templates ), false ); 
    } elseif ( empty( $templates ) ) { 
        $templates = locate_template( "author-$role.php", false ); 
    } else { 
        $new_template = locate_template( array( "author-$role.php" ) ); 
        if ( ! empty( $new_template ) ) { 
            array_unshift( $templates, $new_template ); 
        } 
    } 
    return $templates; 
} 
add_filter( 'author_template', 'author_role_template' );