WordPress主题模板的层次结构

WordPress站点中的模板文件是用来生成网页的模块化、可重用的文件。有些模板文件(比如头部和页脚模板)会应用在站点的所有页面中,其他的可能只在某些特定的条件下使用。

这篇文章讲解了WordPress是如何选择具体的模板文件的。如果你想定制你现有的WordPress主题,这篇文章会帮助你选择编辑哪一个模板文件。

你也可以使用条件标签在一个指定的页面加载模板文件

模板文件的层次

概要

WordPress通过查询字符串来决定展现页面时要渲染的模板文件。查询字符串是包含在指向网站的链接中的信息。它位于网址“?”后面并且被“&”分隔的多个参数。

简单的说,WordPress搜索整个模板层次结构直到找到一个匹配的模板文件为止。为了决定使用哪个模板文件,WordPress:

  1. 匹配每一个查询字符串获取查询类型来判断正在请求哪一个页面(比如一个搜索页,一个分类页等);
  2. 根据模板的层次结构顺序选择一个模板文件;
  3. 在当前主题目录寻找匹配指定名字的模板并且使用第一个被匹配到的模板文件。

除了最基本的index.php这个模板文件外,你可以选择是否实现一个特殊的模板文件。

如果根据匹配的名称WordPress不能找到这个模板文件,他就会继续在层次结构中寻找下一个文件。如果WordPress找不到任何一个匹配的文件,那么它就会使用index.php。

例子

假如你的博客地址是http://example.com/blog/,当访客点击http://example.com/blog/category/your-cat/进入你的分类页面,WordPress会在当前主题目录中寻找匹配当前分类ID的主题文件。更具体的说,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是如何通过查询类型来按顺序选取模板文件的。

Home Page display

front-page.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并且主页设置为“最新文章”,它将会寻找home.php。此外,当主页设置区域指定了“文章列表页”,WordPress将会寻找这个文件。
  3. page.php - 当主页被设置为独立的页面时。
  4. index.php - 当主页显示区域设置为“最新文章”时,但是home.php不存在或者主页被设置且page.php不存在时。

如上所述,WordPress选取模板的规则非常多。使用上图来查看WordPress是如何展现视图的是最好的方法。

Sing Post

文章模板文件用来渲染单个文章。WordPress会遵循如下规则:

  1. single-{post-type}-{slug}.php - 首先,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。

Single Page

用来展现静态页面(页面文章类型)的模板文件。和其他文章类型不同,页面在WordPress比较特殊并且遵循以下规则:

  1. 自定义模板文件 - 也就是被分配给页面的页面模板。
  2. page-{slug}.php - 如果页面的别名是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

渲染分类归档页面使用以下规则:

  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

Tag

为了显示标签归档页面。WordPress遵循以下规则:

  1. tag-{slug}.php - 如果标签的别名是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_format”并且条目是“post-format-{format}”。例如:“链接”的文章版式会寻找taxonomy-post_format-post-format-link.php。
  2. taxonomy-{taxonomy}.php - 如果分类法是sometax,WrodPress会寻找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

如果是要选取单个文章类型的模板,请参考上面讲的“Single Post”章节。

Author display

基于上面的例子,渲染作者归档页面不言而喻:

  1. autor-{nicename}.php - 如果作者的昵称是matt,WordPress将会寻找author-matt.php。
  2. author-{id}.php - 如果作者的ID是6,WordPress将会寻找author-6.php。
  3. atuhor.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(Not Found)

同样的,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 - 例如,如果附件的别名是holiday,WordPress将会寻找single-attachment-holiday.php。
  4. single-attachment.php
  5. single.php
  6. singular.php
  7. index.php

非ASCII字符的处理

从WordPress4.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()函数)使用这样的过滤器名字:“{$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并且这个用户的角色是“editor”而且author-editor.php文件存在时则使用它。

本文翻译自Template Hierarchy

发表评论