正如讨论的那样，模板文件是模块化、可重用的文件，用于生成您的 WordPress 网站上的网页。某些模板文件（如头部和页脚模板）在所有站点页面上使用，而其他文件仅在特定条件下使用。

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

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

模板文件层级结构

概述

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

简单来说，WordPress 会向下搜索模板层级结构，直到找到匹配的模板文件。为了确定要使用哪个模板文件，WordPress：

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

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

在这些示例中，使用的是 PHP 文件扩展名。在块主题（Block themes）中，使用 HTML 文件代替，但模板层级结构是相同的。

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

当您使用子主题（Child theme）时，您添加到子主题的任何一个文件都会覆盖父主题中的同名文件。例如，两个主题都包含相同的模板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. 在当前主题目录中查找匹配分类 slugs（别名）的模板文件。如果分类 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）模板 archive.php。
  5. 如果archive.php也不存在，WordPress 将回退到主主题模板文件 index.php。

视觉概览

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

模板层级结构详解

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

首页显示

默认情况下，WordPress 将您的站点的主页设置为显示最新的博客文章。此页面称为博客文章索引（index）。您也可以设置让博客文章在单独的静态页面上显示。home.php模板文件用于渲染博客文章索引，无论其是作为首页还是单独静态页面使用。如果home.php不存在，WordPress 将使用 index.php。

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

前台页面显示

front-page.php 模板文件用于渲染您的站点的前台页面（Front page），无论前台页面是显示博客文章索引（如上所述）还是静态页面。前台页面模板优先于博客文章索引 (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模板文件用于渲染您的站点的隐私政策（Privacy Policy）页面。隐私政策页面模板优先于静态页面 (page.php) 模板。如果privacy-policy.php 文件不存在，WordPress 将根据可用的模板使用 page.php或 singular.php 文件。如果这两个文件都不存在，它将使用 index.php 文件。

  1. privacy-policy.php – 用于“设置 → 隐私”的更改您的隐私政策页面部分中设置的隐私政策页面。
  2. custom template file – 分配给页面的页面模板。参见 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 查找特定帖子的模板。例如，如果帖子类型（Post type）是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。

单页（Single Page）

用于渲染静态页面 (page 帖子类型)的模板文件。请注意，与其他帖子类型不同，page对 WordPress 来说是特殊的，并使用以下路径：

  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

分类目录（Category）

渲染分类归档索引页面使用 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

标签（Tag）

要显示标签归档索引页面，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

自定义分类法（Custom Taxonomies）

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

  1. taxonomy-{taxonomy}-{term}.php – 如果分类法是sometax，且分类法的术语是 someterm，WordPress 将查找 taxonomy-sometax-someterm.php.在帖子格式（Post formats）的情况下，分类法是'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

自定义帖子类型（Custom Post Types）

自定义帖子类型使用以下路径来渲染适当的归档索引页面。

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

(要渲染单个帖子类型的模板，请参见上面的单篇帖子显示部分。)

作者（Author）显示

基于上述示例，渲染作者归档索引页面相当直观：

  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

日期（Date）

基于日期的归档索引页面按预期渲染：

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

搜索结果（Search Result）

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

  1. search.php
  2. index.php

404 (未找到)

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

  1. 404.php
  2. index.php

附件（Attachment）

渲染附件页面 (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

自 WordPress 6.4 起，附件页面在新安装中不再默认启用。用户可以通过插件启用它们，因此仍然建议测试您的主题，并确保在查看附件页面时正确显示内容。

嵌入（Embeds）

嵌入模板文件用于渲染正在被嵌入的帖子。自 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 😀”且 ID 为 6的页面的页面模板层级结构：

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

相同的行为适用于帖子 slugs、术语名称和作者昵称。

过滤器层级结构（Filter Hierarchy）

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' );

更新日志：

  • 已更新 2022-02-15。添加了说明，指出模板层级结构对于经典主题和块主题是相同的，但示例使用 .php 文件而块主题使用.html 文件。