如模板文档中所述，模板是可重复使用的文件，用于生成WordPress站点中各页面的文档结构。WordPress的模板加载器会决定在特定URL下应加载哪个模板文件。

本文档将解释WordPress的模板加载器如何利用页面的查询信息来构建模板层级结构，同时也会介绍该层级结构中有效的模板有哪些。

概述

当访问者进入WordPress站点的任意页面时，WordPress会使用查询字符串来确定应使用哪个模板来显示该页面。查询字符串中包含来自URL的数据，这些数据有助于做出这一判断。

有了这些数据后，WordPress会遍历模板层级结构，直到找到匹配的模板文件。通常情况下，WordPress会在层级结构中按优先级从以下三个地方查找块模板：

  • 存储在数据库中wp_template文章类型下的用户自定义模板。
  • （如果启用了子主题）位于子主题的/templates文件夹中的模板。
  • 位于主题的/templates文件夹中的模板。

您的主题可以根据设计需求包含任意数量或数量的模板。index.html模板是块主题中唯一必需的模板文件。

可视化概览

该图展示了根据模板层级结构，生成WordPress页面时会调用哪些模板文件：

WordPress模板层级结构的可视化图示。

按查询类型划分的模板层级结构

从技术层面来看，WordPress实际上并不存在单一的模板层级结构。更好的理解方式是按照被查询页面的类型来划分层级结构。例如，如果查询的是首页，那么就会使用首页的模板层级结构。

下文中，我们会按查询类型（以及部分子类型）对各类模板层级结构进行说明，这有助于您确定应在主题中包含哪些模板文件。

首页层级结构

首页模板层级结构在所有模板中是独一无二的，它会根据用户在后台“设置 > 阅读”选项中为首页显示内容所选择的设置而发生显著变化。

如果为首页显示内容选择最新文章，则层级结构为：

  • front-page.html
  • 回退到首页模板层级结构

如果为首页显示内容选择静态页面，则层级结构为：

  • front-page.html
  • 回退到页面模板层级结构

请注意，无论首页显示内容如何设置，front-page.html模板始终具有最高优先级，只有层级结构中位置较低的模板才会受到其影响。

首页模板层级结构

尽管名为“首页模板”，但它并不总是用于站点的首页。从技术上讲，它指的是显示最新博客文章的页面（即博客文章列表页）。

与首页模板层级结构类似，首页模板也会根据后台“设置 > 阅读”选项中为首页显示内容所设置的值而变化。

如果为首页显示内容选择最新文章，则该层级结构将应用于站点的首页：

  • front-page.html
  • home.html
  • index.html

如果为首页显示内容选择静态页面，并且为文章页面设置了特定页面，那么首页模板层级结构将应用于所选的该文章页面（此时不会应用于首页）。这种情况下的层级结构为：

  • home.html
  • index.html

一些历史背景：“首页”这一术语可以追溯到WordPress早期，当时它还只是个博客系统，站点首页上仅显示博客文章。虽然WordPress后来发展到允许在首页上展示任何内容，但“首页”这一术语仍被保留下来，用来指代博客文章列表页，而“首页模板”则用来指代站点的首页。

单篇内容层级结构

当访问者进入某篇单篇文章、页面、附件页面或自定义文章类型下的某条记录时，WordPress会尝试根据该视图所对应的文章来查找对应的模板。

所有的单篇内容模板都可以使用自定义模板，这类模板在下面的子部分中会以{custom_template}.html的形式列出。它们几乎总是位于层级结构的最顶部。如需了解关于创建自定义模板的更多信息，请查看模板主文档中的“自定义模板”部分。

单篇内容模板层级结构

当访问者进入某篇单篇文章或自定义文章类型下的某条记录时，就会触发单篇内容模板层级结构。以下层级结构用于确定对应的模板：

  • {custom-template}.html
  • single-{post_type}-{post_name}.html
  • single-{post_type}.html
  • single.html
  • singular.html
  • index.html

如果是一个名为blue-shirt的product类型自定义文章类型，那么就会使用以下层级结构：

  • {custom-template}.html
  • single-product-blue-shirt.html
  • single-product.html
  • single.html
  • singular.html
  • index.html

WordPress核心的page和attachment文章类型属于特殊情况，其处理方式与默认的单篇内容模板层级结构不同。更多详情请参见下面的“页面”和“附件”部分。

页面模板层级结构

当有人访问您网站上的某个单独页面时，就会触发页面模板层级结构。以下层级结构用于确定对应的模板：

  • {custom-template}.html
  • page-{post_name}.html
  • page-{post_id}.html
  • page.html
  • index.html

如果一个页面的标题（即slug）为about-me，ID为200，那么就会使用以下层级结构：

  • {custom-template}.html
  • page-about-me.html
  • page-200.html
  • page.html
  • index.html

附件（媒体文件）模板层级结构

当访问附件（媒体文件页面）的单篇内容视图时，WordPress会在默认的单篇内容模板层级结构基础上添加一些额外的模板。这就是附件模板层级结构：

  • {mime_type}-{sub_type}.html
  • {sub_type}.html
  • {mime_type}.html
  • attachment.html
  • 回退到默认的单篇内容模板层级结构

如果某个附件的mime类型为image/jpeg，那么image部分将被视为mime_type，而jpeg部分则被视为sub_type。

假设有一个mime类型为image/jpeg、标题（即slug）为red-bird的附件，那么完整的附件模板层级结构将为：

  • image-jpeg.html
  • jpeg.html
  • image.html
  • attachment.html
  • {custom-template}.html
  • single-attachment-red-bird.html
  • single-attachment.html
  • single.html
  • singular.html
  • index.html

从WordPress 6.4版本开始，新安装的站点默认不再启用附件页面功能。用户可以通过插件来启用该功能，因此仍然建议测试您的主题，确保在查看附件页面时能够正确显示内容。

隐私政策页面层级结构

与其它页面相比，WordPress中的隐私政策页面属于特殊情况。WordPress会在查看常规页面模板层级结构之前，先查找名为privacy-policy.html的模板。对于隐私政策页面，其模板层级结构为：

  • privacy-policy.html
  • 回退到页面模板层级结构

归档页面层级结构

WordPress中的归档页面用于展示按某种元数据（如日期、作者、文章类型）或分类法术语（类别、标签）分组的文章。

分类法术语层级结构

在处理公开显示的分类法时，分类法中的每个术语都会有属于自己的归档页面。分类法术语的模板层级结构为：

  • taxonomy-{taxonomy_slug}-{term_slug}.html
  • taxonomy-{taxonomy_slug}.html
  • taxonomy.html
  • archive.html
  • index.html

如果有一个slug为location的分类法，而该分类法下有一个slug为alabama的术语，那么模板层级结构将为：

  • taxonomy-location-alabama.html
  • taxonomy-location.html
  • taxonomy.html
  • archive.html
  • index.html

WordPress核心的category和post_tag分类法并不使用分类法术语模板。更多详情请参见下面的“类别”和“标签”部分。

类别层级结构

当访问者点击某个类别链接并查看该类别的归档页面时，会使用以下模板层级结构：

  • category-{slug}.html
  • category-{id}.html
  • category.html
  • archive.html
  • index.html

当查看的类别slug为news，类别ID为123的类别归档页面时，模板层级结构将为：

  • category-news.html
  • category-123.html
  • category.html
  • archive.html
  • index.html

标签层级结构

当访问者点击某个标签链接并查看该标签的归档页面时，会使用以下模板层级结构：

  • tag-{slug}.html
  • tag-{id}.html
  • tag.html
  • archive.html
  • index.html

当查看的标签slug为flowers，标签ID为456的标签归档页面时，模板层级结构将为：

  • tag-flowers.html
  • tag-456.html
  • tag.html
  • archive.html
  • index.html

文章类型归档页面层级结构

自定义文章类型可以拥有一个面向公众的归档页面，该页面本质上相当于该文章类型的索引页，通常会列出该类型下的最新文章（不过这一列表也可以被过滤或修改）。当访问者查看该文章类型的归档页面时，会使用以下模板层级结构：

  • archive-{post_type}.html
  • archive.html
  • index.html

如果有一个slug为portfolio_project的文章类型，那么它的层级结构将为：

  • archive-portfolio_project.html
  • archive.html
  • index.html

WordPress核心的post文章类型使用首页模板层级结构，而默认的page和attachment文章类型则没有归档视图功能。

作者层级结构

尽管使用了“作者”这一术语，但作者归档页面实际上是由用户个人资料部分和文章作者归档部分组成的。无论用户是否发表过文章，WordPress站点上的所有用户都会生成一个归档页面地址。不过，作者模板的用途通常是展示关于该用户的某些元数据，并列出其发布的文章。

当在站点前端访问作者归档页面时，会使用以下模板层级结构：

  • author-{user_nicename}.html
  • author-{user_id}.html
  • author.html
  • archive.html
  • index.html

当访问昵称为matt、ID为333的用户的作者归档页面时，作者归档页面的模板层级结构将为：

  • author-matt.html
  • author-333.html
  • author.html
  • archive.html
  • index.html

日期层级结构

当查看基于日期或时间范围的归档页面（如年度、月度、周度归档）时，其模板层级结构为：

  • date.html
  • archive.html
  • index.html

搜索结果层级结构

在查看网站上的搜索结果时，会使用搜索结果模板层级结构。它与归档页面类似，也会列出多篇文章，但从技术上来说它并非归档页面。搜索结果的模板层级结构为：

  • search.html
  • index.html

404（未找到）页面层级结构

当访问网站上不存在的URL时，WordPress会查找404模板，该模板的作用是提供有关该页面不存在的一些有用信息。404页面的模板层级结构为：

  • 404.html
  • index.html

嵌入内容层级结构

当某个站点嵌入来自您WordPress站点的文章时，会使用嵌入模板。WordPress会将嵌入内容包裹在<iframe>中，然后根据该模板来显示嵌入的内容。

块模板系统不支持嵌入模板。如果要创建并使用自定义嵌入模板，它们必须位于主题的根文件夹中，并且文件扩展名必须为PHP格式。

嵌入内容的模板层级结构为：

  • embed-{post_type}-{post_format}.php
  • embed-{post_type}.php
  • embed.php

如果主题中没有包含自定义嵌入模板，WordPress将会使用核心系统中自带的/wp-includes/theme-compat/embed.php模板。它不会像其他类型的模板那样回退到index模板。

如果要嵌入的文章类型为post，文章格式为image，那么层级结构将为：

  • embed-post-image.php
  • embed-post.php
  • embed.php