模板层次结构

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

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

 

模板文件的层次结构

概述

WordPress使用查询字符串来决定应该使用哪个或哪一组模板来显示页面。查询字符串是指向网站每个部分的链接中包含的信息。

简单地说，WordPress通过模板层次结构向下搜索，直到找到一个匹配的模板文件。为了确定使用哪个模板文件，WordPress：

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

除了基本的index.php模板文件外，你可以选择是否需要其他模板文件。

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

当你使用一个子主题时，你添加到子主题的任何文件都会覆盖父主题中的相同文件。例如，两个主题都包含相同的模板category.php，那么子主题的模板会被使用。
如果一个子主题包含特定的模板，如category-unicorns.php，而父主题包含优先级较低的模板，如category.php，那么子主题的category-unicorns.php被使用。
相反，如果一个子主题只包含一般的模板，如category.php，而父主题包含特定的模板，如category-unicorns.php，那么父主题的模板category-unicorns.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文件不存在，WordPress将使用home.php或page.php文件，取决于 设置→阅读 中的设置。如果这些文件都不存在，它将使用index.php文件。

1. front-page.php - 用于 设置→阅读："您的主页显示"中设置的"您的最新文章"或"一个静态页面"。
2. home.php - 如果WordPress找不到front-page.php并且在首页显示部分设置为"您的最新文章"，它将寻找home.php。此外，当在首页显示部分设置了文章页时，WordPress会寻找这个文件。
3. page.php - 当在首页显示部分设置了"主页"时
4. index.php - 当首页显示部分被设置为"你的最新文章"，但home.php不存在，或者当"主页"被设置但page.php不存在。

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

 

隐私策略页面显示

privacy-policy.php模板文件用于呈现您网站的隐私政策页面。隐私政策页面模板优先于静态页面（page.php）模板。如果privacy-policy.php文件不存在，WordPress将使用page.php或singular.php文件，这取决于现有的模板。如果这些文件都不存在，它将使用index.php文件。

1. privacy-policy.php – 用于 设置→隐私："更改您的隐私政策页面"中设置的隐私政策页面。
2. 自定义模板文件 – 分配给页面的页面模板，参见get_page_templates()
3. page-{slug}.php - 如果页面的slug是privacy，WordPress将寻找使用page-privacy.php。
4. page-{id}.php - 如果页面ID是6，WordPress将寻找使用page-6.php。
5. page.php
6. singular.php
7. index.php

 

单页文章

单页文章模板文件用于渲染单一文章，WordPress使用以下路径：

1. single-{post-type}-{slug}.php - （从4.4开始）首先，WordPress寻找特定文章的模板。例如，如果文章类型是product，文章的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。

 

单页页面

用来渲染静态页面的模板文件（post-type是page）。注意，与其他类型不同，page是WordPress的特殊类型，它使用以下路径：

1. 自定义模板文件 - 分配给页面的页面模板。参见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 – 如果作者的nice name是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

 

附件

渲染一个附件页（post-type为attachment）使用以下路径

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

 

嵌入

嵌入模板文件是用来渲染被嵌入的文章的。从4.5开始，WordPress使用以下路径：

1. embed-{post-type}-{post_format}.php – 首先，WordPress为特定的文章寻找一个模板。例如，如果它的文章类型是post，并且它有audio格式，WordPress会寻找embed-post-audio.php。
2. embed-{post-type}.php – 如果文章类型是product，WordPress会寻找embed-product.php。
3. embed.php – 然后WordPress又回到了embed.php。
4. 最后，WordPress最终回到了它自己的wp-includes/theme-compat/embed.php模板。

 

非ASCII字符处理

从WordPress 4.7开始，模板名称中任何包括非ASCII字符的动态部分，实际上都支持未编码和编码的形式，按顺序排列。你可以选择使用哪个。

下面是一个ID为6的名为 "Hello World 😀"的页面的页面模板层次结构：

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

同样的行为也适用于文章slug、term名称和作者昵称。

 

过滤器层次结构

WordPress模板系统让你过滤层次结构。这意味着，你可以在层次结构的特定点上插入和改变东西。过滤器（位于get_query_template()函数中）使用这个过滤器名称："{$type}_template"，其中$type是模板类型。

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

• embed_template
• 404_template
• search_template
• frontpage_template
• home_template
• privacypolicy_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.php之前添加author-{role}.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' );