模板层次结构

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

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

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

模板文件层次结构

概述

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

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

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

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

提示：在这些示例中，使用了 PHP 文件扩展名。在块主题中，使用 HTML 文件代替，但模板层次结构是相同的。

如果 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文件用于呈现您网站的首页，无论首页显示博客帖子索引（如上所述）还是静态页面。首页模板优先于博客文章索引 ( 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 将显示什么的最佳方式。

隐私政策页面展示

该privacy-policy.php模板文件用于呈现您网站的隐私政策页面。隐私政策页面模板优先于静态页面 ( 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 会为特定帖子寻找模板。例如，如果帖子类型是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.

单页

用于呈现静态页面（pagepost-type）的模板文件。请注意，与其他帖子类型不同，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

类别

呈现类别存档索引页面在 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

自定义分类法

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

  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，使用以下路径（按顺序）：
    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 然后退回到嵌入.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
  • 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-{role}.phpbefore author.php，我们可以使用“author_template”模板类型来操纵实际的层次结构。这允许对 /author/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 文件。