WordPress主题开发教程—模版文件继承规则

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

本文介绍 了 WordPress 如何确定在各个页面上使用的模板文件 。如果要自定义现有的WordPress主题，这将帮助我们确定需要编辑哪个模板文件。我们还可以使用条件标签来控制在页面上加载的模板。

模板文件层次结构

摘要

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

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

1. 将每个查询字符串与查询类型匹配，来确定用户请求的是哪种类型的页面（例如，搜索页面，类别页面等）;


2. 按模板层次结构确定使用哪个模板文件来显示这个页面。


3. 在当前主题的目录中查找具有特定名称的模板文件，并使用层次结构指定的 第一个匹配模板文件 。

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

如果 WordPress 找不到名称匹配的具体模板文件，它将跳转到层次结构中的下一个文件。如果 WordPress 还是找不到任何匹配的模板文件，最终将使用index.php 模板来显示页面。

示例

举个例子，用户在你的网站上打开了分类目录存档页面：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 会在我们的网站首页显示网站的最新文章，这个页面称为文章索引。除此之外，选择一个静态页面作为网站首页。模板文件 home.php 用于显示文章索引，无论我们选择最新文章还是静态页面作为我们的首页。如果 home.php 不存在，WordPress 将使用 index.php。

1. home.php


2. index.php

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

首页显示

front-page.php 模版文件是 WordPress 优先查找的首页模版文件，。该模版优先于 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。此外，当在首页显示部分设置文章页面时，WordPress 将查找此文件。 


3. 
   page.php– 在 首页显示 部分 设置“ 首页 ”时 。


4. 
   index.php– 首页显示 设置为“ 你最新的文章 ”，但 home.php不存在，或者设置了首页，但 page.php不存在时，使用此模版文件。

如我们上面看到的，WordPress 确定模板的路径有很多，使用上面的图表是确定WordPress 将采用哪个模板文件的最佳方式。

单文章页面

单文章模板用来显示某一篇文章。

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

单页

用于呈现静态页面的模板文件（ 页面文章类型）。 页面在 WordPress 中是一个特殊的文章类型，使用以下路径来查找模版文件：

1. 
   自定义模版文件– 在 WordPress 后台选择的 页面模板 。见 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– 如果分类目录的别名是 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

自定义分类

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

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

附件

呈现附件页面（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并且格式为音频格式，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 字符）实际上都支持未编码和已编码的形式。我们可以选择使用任意一个。

下面是名为 “Hello World&＃x1f600;” 的页面的页面模板层次结构，其 ID 为 6 ：

• page-hello-world-&＃x1f600;.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.php 之前添加一个 author-{role}.php ，来针对某个角色设置指定的模版文件，我们可以使用 ‘author_template’ 模板过滤器来修改作者存档模版的层次结构。当用户打开 /author/username 页面时，WordPress 会自动调用角色存档模版，其中 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' );