WordPress主题开发（ 七）之—— 模版文件继承规则

概述

WordPress模板文件是用于生成网页的模块化、可重用的文件。不同的模板文件用于不同的页面或页面类型。了解WordPress如何确定使用哪个模板文件对于自定义主题和网站开发非常重要。本文将介绍WordPress的模板文件继承规则，帮助您确定在不同情况下使用哪个模板文件，并控制页面的外观和布局。

模板文件层次结构

WordPress使用查询字符串来决定应该使用哪个模板文件来显示页面。查询字符串包含在网站链接的URL中，出现在初始问号之后，并可能包含多个由“＆”符号分隔的参数。

简而言之，WordPress会按照以下步骤来确定要使用的模板文件：

1. 匹配查询类型：WordPress将根据查询字符串中的信息确定用户请求的页面类型（例如，搜索页面、分类页面等）。

2. 确定模板文件：WordPress会按照模板文件的层次结构来确定要使用的模板文件。

WordPress会在当前主题的目录中查找特定名称的模板文件，并使用层次结构中最先匹配的模板文件。

除了基本的index.php模板文件之外，您可以自定义使用其他模板文件来显示页面。

如果WordPress找不到具有与查询匹配的模板文件，它将继续查找层次结构中的下一个文件。如果WordPress仍然找不到匹配的模板文件，最终将使用index.php模板来显示页面。

示例

让我们通过一个示例来说明这个过程。假设用户访问您的网站上的分类目录存档页面：http://example.com/blog/category/your-cat/。WordPress会按照以下过程来确定要使用的模板文件：

1. 在当前主题的目录中查找与分类别名匹配的模板文件。如果分类别名是“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使用home.php模板文件来显示文章索引，无论您选择最新文章还是静态页面作为首页。如果home.php不存在，WordPress将回退到使用index.php。

• home.php
• index.php

如果存在front-page.php，它将覆盖home.php模板文件的显示。

首页显示

front-page.php模板文件是WordPress首选查找的首页模板文件。该模板文件的优先级高于home.php。如果front-page.php文件不存在，WordPress将根据设置→阅读中的选项决定使用home.php还是page.php文件。如果这两个文件都不存在，WordPress将回退到使用index.php。

• front-page.php：当在设置→阅读中选择“您的最新帖子”或“静态页面”时，这个模板文件优先使用。
• home.php：如果WordPress找不到`front-page.php

，并且在设置→阅读中选择“您的最新文章”，那么WordPress将查找并使用home.php`。此外，当您设置了某个页面作为首页时，WordPress也会查找并使用此文件。

• page.php：当在设置→阅读中选择“首页”时。
• index.php：如果首页设置为“您最新的文章”，但home.php不存在，或者设置了首页，但page.php不存在时，WordPress将使用此模板文件。

如上所述，WordPress会根据您的设置和模板文件的存在性来确定使用哪个模板文件。这些规则构成了一个层次结构，图表是理解的好方式。

单文章页面

单文章页面用于显示单篇文章的内容。WordPress使用以下规则来选择模板文件：

• single-{post-type}-{slug}.php：首先，WordPress会查找特定文章的模板。例如，如果文章的类型是"product"，并且文章的别名是"dmc-12"，WordPress将查找single-product-dmc-12.php。
• single-{post-type}.php：如果文章类型是"product"，WordPress会查找single-product.php。
• single.php：如果以上两者都不存在，WordPress将使用single.php。
• singular.php：如果single.php也不存在，WordPress将回退到singular.php。
• index.php：最后，如果所有模板都找不到，WordPress将使用默认的index.php。

单页

单页用于呈现静态页面的模板文件，这些页面被视为一种特殊的文章类型。WordPress使用以下规则来选择单页模板文件：

• 自定义模板文件：首先，WordPress会查找您在后台选择的页面模板，这些模板可以在页面编辑界面中选择。
• page-{slug}.php：如果页面的别名是"recent-news"，WordPress将查找page-recent-news.php。
• page-{id}.php：如果页面的ID是6，WordPress将查找page-6.php。
• page.php：如果以上模板文件都不存在，WordPress将使用page.php。
• singular.php：如果page.php也不存在，WordPress将回退到singular.php。
• index.php：最后，如果所有模板都找不到，WordPress将使用默认的index.php。

分类目录

WordPress使用以下层次结构来渲染分类目录页面：

• category-{slug}.php：如果分类目录的别名是"news"，WordPress将查找category-news.php。
• category-{id}.php：如果类别的ID是6，WordPress将查找category-6.php。
• category.php：如果以上两者都不存在，WordPress将使用category.php。
• archive.php：如果category.php也不存在，WordPress将回退到archive.php。
• index.php：最后，如果所有模板都找不到，WordPress将使用默认的index.php。

标签

要显示标签存档页面，WordPress使用以下路径：

• tag-{slug}.php：如果标签的别名是"sometag"，WordPress将查找tag-sometag.php。
• tag-{id}.php：如果标签的ID是6，WordPress将查找tag-6.php。
• tag.php：如果以上两者都不存在，WordPress将使用tag.php。
• archive.php：如果tag.php也不存在，WordPress将回退到archive.php。
• index.php：最后，如果所有模板都找不到，WordPress将使用默认的index.php。

自定义分类

WordPress查找自定义分类法的模板文件路径的方法略有不同：

• taxonomy-{taxonomy}-{term}.php：如果分类法是"sometax"，而分类法项目是"someterm"，WordPress将查找taxonomy-sometax-someterm.php。在文章格式的情况下，分类法是"post_format"，分类法项目是"post-format-{format}"。例如，taxonomy-post_format-post-format-link.php用于链接格式。
• taxonomy-{taxonomy}.php：如果分类法是"sometax"，WordPress将查找taxonomy-sometax.php。
• taxonomy.php：如果以上两者都不存在，WordPress将使用taxonomy.php。
• archive.php：如果taxonomy.php也不存在，WordPress将回退到archive.php。
• index.php：最后，如果所有模板都找不到，WordPress将使用默认的index.php。

自定义文章类型

自定义文章类型使用以下路径来呈现相应的存档页面：

• archive-{post_type}.php：如果帖子类型是"product"，WordPress将寻找archive-product.php。
• archive.php：如果archive-product.php不存在，WordPress将使用通用的archive.php。
• index.php：如果以上模板文件都不存在，WordPress将使用默认的index.php。

请注意，对于单个自定义文章类型的模板，请参阅上面的“单个文章页面”部分。

作者显示

基于上述示例，呈现作者存档页面的层次结构显而易见：

• author-{nicename}.php：如果作者的名字是"matt"，WordPress将寻找author-matt.php。
• author-{id}.php：如果作者的ID是6，WordPress将寻找author-6.php。
• author.php：如果以上两者都不存在，WordPress将使用author.php。
• archive.php：如果author.php也不存在，WordPress将回退到archive.php。
• index.php：最后，如果所有模板都找不到，WordPress将使用默认的index.php。

日期

基于日期的存档页面按照以下路径查找模板：

• date.php：首选，WordPress会查找date.php。
• archive.php：如果date.php不存在，WordPress将使用archive.php。
• index.php：最后，如果以上两者都不存在，WordPress将使用默认的index.php。

搜索结果

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

• search.php

：首选，WordPress会查找search.php。

• index.php：最后，如果search.php不存在，WordPress将使用默认的index.php。

404（未找到）

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

• 404.php：首选，WordPress会查找404.php。
• index.php：最后，如果404.php不存在，WordPress将使用默认的index.php。

附件

呈现附件页面（attachment文章类型）使用以下路径：

• {MIME-type}.php：可以是任何MIME类型（例如：image.php，video.php，pdf.php）。对于text/plain，使用以下路径（按顺序）：
  • text-plain.php
  • plain.php
  • text.php
• single-attachment-{slug}.php：例如，如果附件的别名是"holiday"，WordPress会查找single-attachment-holiday.php。
• single-attachment.php：如果以上两者都不存在，WordPress将寻找single-attachment.php。
• single.php：如果single-attachment.php也不存在，WordPress将回退到single.php。
• singular.php：如果single.php也不存在，WordPress将回退到singular.php。
• index.php：最后，如果所有模板都找不到，WordPress将使用默认的index.php。

嵌入功能

嵌入模板文件用于渲染嵌入到其他页面或网站的文章。从WordPress 4.5开始，WordPress使用以下路径：

• embed-{post-type}-{post_format}.php：首选，WordPress会查找特定文章类型的模板。例如，如果一篇文章的文章类型是"post"并且格式是音频格式，WordPress会查找embed-post-audio.php。
• embed-{post-type}.php：如果文章类型是"product"，WordPress会查找embed-product.php。
• embed.php：最后，WordPress将使用embed.php。
• 最后，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

这些规则同样适用于文章别名、术语名称和作者名字。

过滤层次结构

WordPress模板系统允许您使用过滤器来修改模板层次结构。这意味着您可以在层次结构的特定点插入和更改内容。过滤器位于get_query_template()函数中，使用过滤器“{KaTeX parse error: Expected 'EOF', got '}' at position 5: 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.php之前添加一个author-{role}.php模板文件，以针对某个角色设置指定的模板文件，您可以使用author_template模板过滤器来修改作者存档模板的层次结构。

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');
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

这个示例演示了如何使用author_template过滤器来添加一个特定角色的作者存档模板文件。

希望这个详细的目录结构和示例对您理解WordPress模板文件的继承规则有所帮助。这将使您能够更好地控制和自定义您的WordPress主题。关注longm龙哥，祝你开放不迷路