WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

zh-cn:模板层次

简介

WordPress模板像拼图一样拼在一起,来生成你网站的页面。有些模板,比如页眉和页脚,是所有页面公用的;也有的只在一些特定页面/情况中使用。

这篇文章是关于:

这篇文章回答了下面这些问题:

WordPress生成特定页面的时候调用了什么模板文件?

这篇文章可能对谁有用:

自从WordPress引入主题以来,模板的可配置性越来越高,为了开发WordPress主题,你有必要了解WordPress是如何为不同页面选择模板文件的。如果你希望自定义一个现有的主题,这篇文章将告诉你需要修改那些模板文件。

使用条件标签函数判断

Wordpress 提供多种将查询匹配到模板的方式。主题开发者也可以使用条件标签来控制特定页面的模板使用。有些Wordpress主题可能并未实现这里提到的所有功能。有些主题则使用条件标签来载入其他模板文件。参见条件标签页面和"基于查询"的主题开发

模版文件的分层结构

基本理念

Wordpress使用查询字符串——你网站中每个链接所包含的信息,来决定使用哪个或哪些模板文件。

First, WordPress matches every Query String to query types — i.e. it decides what type of page (a search page, a category page, the home page etc.) is being requested.

Templates are then chosen — and web page content is generated — in the order suggested by the WordPress Template hierarchy, depending upon what templates are available in a particular WordPress Theme.

WordPress looks for template files with specific names in the current Theme's directory and uses the first matching template file listed under the appropriate query section below.

With the exception of the basic index.php template file, Theme developers can choose whether they want to implement a particular template file or not. If WordPress cannot find a template file with a matching name, it skips down to the next file name in the hierarchy. If WordPress cannot find any matching template file, index.php (the Theme's home page template file) will be used.

举例

如果你的博客网址是 http://example.com/blog/ ,有一个访客点击了其中一个分类的链接: http://example.com/blog/category/your-cat/: WordPress将按照如下方式寻找模板文件并生成页面。

WordPress在当前主题目录下寻找一个匹配当前文章分类ID的模板文件。

  1. 如果文章分类ID是4, WordPress会找这样一个文件: category-4.php.
  2. 如果没有这个文件, WordPress再找通用的文章分类模板, category.php.
  3. 如果这也没有, WordPress再找通用文章归档模板, archive.php.
  4. 如果还没有, WordPress回到主题主模板文件, index.php.

如果访客访问了你的首页: http://example.com/blog/:

  1. WordPress首先看是否有 静态首页. 如果有,则根据 模板层次载入那个页面.
  2. 如果没有静态首页,则去到 home.php ,用它来生成请求的页面。
  3. 如果 home.php 也没有, 再回到当前主题目录下的index.php 文件,用它来生成页面。

Visual Overview

The following diagram shows which template files are called to generate a WordPress page based on the WordPress Template hierarchy.

Graphic Example of the WordPress Template Hierarchy Structure Full-Size Image (png)

A more in depth hierarchy diagram, including template-related conditional tags and body CSS classes, can be found here.

模板层次细节

The following sections describe the order in which template files are being called by WordPress for each query type.

首页显示

Template file used to render the Blog Posts Index, whether on the site front page or on a static page. Note: on the Site Front Page, the Front Page template takes precedence over the Blog Posts Index (Home) template.

  1. home.php
  2. index.php

Front Page display

Template file used to render the Site Front Page, whether the front page displays the Blog Posts Index or a static page. The Front Page template takes precedence over the Blog Posts Index (Home) template.

  1. front-page.php - Used for both Your latest posts or A static page as set in the Front page displays section of Settings -> Reading
  2. Page display rules - When Front page is set in the Front page displays section of Settings -> Reading
  3. Home Page display rules - When Posts page is set in the Front page displays section of Settings -> Reading

Single Post display

Template file used to render a single post page.

  1. single-{post_type}.php - If the post type were product, WordPress would look for single-product.php.
  2. single.php
  3. index.php

Page display

Template file used to render a static page (page post-type)

  1. custom template file - The Page Template assigned to the Page. See get_page_templates().
  2. page-{slug}.php - If the page slug is recent-news, WordPress will look to use page-recent-news.php
  3. page-{id}.php - If the page ID is 6, WordPress will look to use page-6.php
  4. page.php
  5. index.php

Category display

Template file used to render a Category Archive Index page

  1. category-{slug}.php - If the category's slug were news, WordPress would look for category-news.php
  2. category-{id}.php - If the category's ID were 6, WordPress would look for category-6.php
  3. category.php
  4. archive.php
  5. index.php

Tag display

Template file used to render a Tag Archive Index page

  1. tag-{slug}.php - If the tag's slug were sometag, WordPress would look for tag-sometag.php
  2. tag-{id}.php - If the tag's ID were 6, WordPress would look for tag-6.php
  3. tag.php
  4. archive.php
  5. index.php

Custom Taxonomies display

Template file used to render the Archive Index page for a Custom Taxonomy

  1. taxonomy-{taxonomy}-{term}.php - If the taxonomy were sometax, and taxonomy's term were someterm WordPress would look for taxonomy-sometax-someterm.php. In the case of Post Formats, the taxonomy is 'post_format' and the terms are 'post-format-{format}. i.e. taxonomy-post_format-post-format-link.php
  2. taxonomy-{taxonomy}.php - If the taxonomy were sometax, WordPress would look for taxonomy-sometax.php
  3. taxonomy.php
  4. archive.php
  5. index.php

Custom Post Types display

Template file used to render the Archive Index page for a Custom Post Type

  1. archive-{post_type}.php - If the post type were product, WordPress would look for archive-product.php.
  2. archive.php
  3. index.php

(For rendering a single custom post type, refer to the Single Post display section above.)

Author display

Template file used to render an Author Archive Index page

  1. author-{nicename}.php - If the author's nice name were rami, WordPress would look for author-rami.php.
  2. author-{id}.php - If the author's ID were 6, WordPress would look for author-6.php.
  3. author.php
  4. archive.php
  5. index.php

Date display

Template file used to render a Date-Based Archive Index page

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

Search Result display

Template file used to render a Search Results Index page

  1. search.php
  2. index.php

404 (Not Found) display

Template file used to render a Server 404 error page

  1. 404.php
  2. index.php

Attachment display

Template file used to render a single attachment (attachment post-type) page

  1. MIME_type.php - it can be any MIME type (image.php, video.php, application.php). For text/plain, in order:
    1. text.php
    2. plain.php
    3. text_plain.php
  2. attachment.php
  3. single-attachment.php
  4. single.php
  5. index.php

Filter Hierarchy

The WordPress templates system allow you to filter the hierarchy. The filter (located in the get_query_template() function) uses this filter name: "{$type}_template" where $type is the a file name in the hierarchy without the .php extension.

Full list:

  • index_template
  • 404_template
  • archive_template
  • author_template
  • category_template
  • tag_template
  • taxonomy_template
  • date_template
  • home_template
  • front_page_template
  • page_template
  • paged_template
  • search_template
  • single_template
  • text_template, plain_template, text_plain_template (all mime types)
  • attachment_template
  • comments_popup


举例

For example, let's take the default author hierarchy:

  • author-{nicename}.php
  • author-{id}.php
  • author.php

To add author-{role}.php before author.php we can manipulate the actual hierarchy using the 'author_template' hook. This allows a request for /author/username where username has the role of editor to display using author-editor.php if present in the current themes directory.

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

更新日志

  • 1.5 :
    • Introduction of the theme system.

源文件

相关阅读

Template Hierarchy: Category Templates, Tag Templates, Taxonomy Templates, Page Templates, Post Type Templates, Author Templates, Date Templates, Search Templates, 404 Templates, Attachment Templates, Loop Templates