WordPress主题开发手册：页面模板文件

页面模板是可以应用于特定页面或页面组的特定类型的模板文件。

注意：从WordPress 4.7开始，页面模板支持所有文章类型。要了解如何将页面模板设置为特定文章类型，请参见下面的示例。

由于页面模板是特定类型的模板文件，因此页面模板的一些区别特征如下：

页面模板用于更改页面的外观。
页面模板可以应用于单个页面，页面部分或一类页面。
页面模板通常具有针对单个页面或页面组的高度特异性。例如，名为 page-about.php 的页面模板，比模板文件（ page.php或者index.php ）更具体，它只会影响带有“about”字样的页面。
如果页面模板具有模板名称，则编辑页面的WordPress用户可以控制将使用什么模板来呈现页面。

文章目录

页面模板的用途

页面模板在页面上显示站点的动态内容，例如文章、新闻更新、日历事件、媒体文件等。您可以决定主页以特定的方式显示，这与站点的其他部分完全不同。或者，您可能想要显示一个特色图片，该图片链接到页面的某个部分，在其他位置具有最新文章列表，并使用自定义导航。您可以使用页面模板来实现这些目的。

本节向您展示如何构建页面模板，用户可以通过其管理界面来选择页面模板。

例如，您可以根据下面的需求构建页面模板：

1列全宽
2列+右侧边栏
2列+左侧边栏
3列

模板层次结构中的页面模板

当一个人浏览您的网站时，WordPress将选择用于渲染该页面的模板。正如我们先前在“ 模板层次结构”中了解的那样，WordPress按以下顺序查找模板文件：

页面模板— 如果页面分配有自定义模板，则WordPress将查找该文件，并在找到该文件时使用它。
page-{slug}.php — 如果未分配自定义模板，则WordPress会查找并使用包含页面别名的专业模板。
page-{id}.php — 如果未找到包含页面别名的专业模板，则WordPress会查找并使用以页面ID命名的专业模板。
page.php — 如果找不到包含页面ID的专用模板，则WordPress会查找并使用主题的默认页面模板。
singular.php—如果page.php未找到，则WordPress会查找并使用用于单个文章的主题模板，而与文章类型无关。
index.php — 如果未分配或找到特定的页面模板，则WordPress默认返回使用主题的索引文件来呈现页面。

还有一个WordPress定义的模板，名为 paged.php。它不是用于页面文章类型，而是用于显示存档的多个页面。

页面模板的目的和用户控制

如果您打算为主题制作自定义页面模板，则应在进行操作之前确定以下几点：

页面模板是用于一个特定页面还是用于任何页面；
您希望模板可使用哪种类型的用户控制。

具有模板名称的每个页面模板都可以由用户在创建或编辑页面时选择。可用模板的列表可在 页面>新建页面>页面属性>模板中找到。因此，WordPress用户可以选择带有模板名称的任何页面模板，而这并不是您的意图。

例如，如果您要为“关于”页面使用特定的模板，则不宜将该页面模板命名为“关于模板”，因为该模板可在所有页面上全局使用（即用户可以将其应用于任何页面）。取而代之的是，创建一个一次性使用的模板，当用户访问“关于”页面时，WordPress将使用适当的模板呈现该页面。

相反，许多主题都具有选择页面将具有多少列的功能。每个选项都是一个全局可用的页面模板。为了给您的WordPress用户这个全局选项，您将需要为每个选项创建页面模板并给每个模板命名。

通过命名文件的方式以及是否有特定的注释来确定模板是供全局使用还是用于单个用途。

有时，使模板在全局范围内可用是可行的，即使它看起来只有一个用途。在开发主题时，很难预测用户将为其页面命名的名称。作品集页面是一个很好的例子，因为并非每个WordPress用户都会为他们的作品集命名相同的名称或具有相同的页面ID，但是他们可能想要使用该模板。

组织页面模板文件

如组织主题文件所述，WordPress可识别子文件夹内的页面模板。因此，最好将全局页面模板存储在此文件夹中，以使它们看起来井井有条。

需要注意的是，那些特定的（仅一次使用的，比如包含id或别名命名的）页面模板文件，不能放在子文件夹中，如果要在子主题中使用的，也应该放在父主题根目录中。

创建全局用途的页面模板

有时，您需要一个可以在任何页面或多个页面上全局使用的模板。一些开发人员会将其模板与文件名前缀分组，例如 page_two-columns.php

注意：不要使用page-作为前缀，否则WordPress会解释文件作为一个专门的模板，意味着只适用于网站上的一个页面。

有关无法使用的主题文件命名约定和文件名的信息，请参见保留的主题文件名。

快速、安全地创建新页面模板的方法，是复制 page.php 然后命名为其他文件名。这样，您就可以从其他页面的HTML结构开始，根据需要去编辑这个新文件。

要创建全局模板，请在文件顶部添加PHP注释，指出模板的名称。

<?php /* Template Name: Example Template */ ?>

最好为模板取一个包含具体含义的名称，因为该名称对于WordPress用户在编辑页面时可见。例如，您可以将模板命名为Homepage、Blog或Portfolio。

下面是来自Twenty Fourteen主题的示例，它创建了一个名为Full Width Page的页面模板：

<?php
/**
* Template Name: Full Width Page
*
* @package WordPress
* @subpackage Twenty_Fourteen
* @since Twenty Fourteen 1.0
*/

一旦您将这个页面模板文件上传到主题文件夹中（例如 page-templates 子文件夹），访问后台任何页面的编辑界面，就可以在 页面属性-模板 中看到您创建的模板了。用户可以在此处访问您的全局页面模板。

注意：模板列表的宽度为 250px，如果您的模板名称太长，可能会被裁剪而无法完全显示。

为特定页面创建页面模板

如“ 模板层次结构” 页面中所述，您可以为特定页面创建模板。要为一个特定页面创建模板，请复制您现有的page.php文件，并使用页面的slug别名或ID重命名该文件：

page-{slug}.php
page-{ID}.php

例如：您的“关于”页面上有一个“about”别名，ID为6。如果激活的主题的文件夹中有一个名为page-about.php 或 page-6.php 的文件，则WordPress将自动查找并使用该文件来呈现“关于”页面。

这种特定的页面模板必须在主题的文件夹中（即 / wp-content/themes/my-theme-name/），不能放在子文件夹中。

为特定文章类型创建页面模板

默认情况下，“页面”文章类型可以使用自定义页面模板。

要为特定文章类型创建页面模板，请在模板名称下添加一行，包含您希望模板支持的文章类型即可。例如：

<?php
/*
Template Name: Full-width layout
Template Post Type: post, page, event
*/
// Page code here...

注：仅有WordPress 4.7及以上版本，才支持将页面模板添加到除“页面”文章类型之外的其他文章类型

如果至少有一个用于文章类型的模板，则“文章属性”元数据框将在后台显示，而无需为“page-attributes”或其他对方添加文章类型支持。注册文章类型时，可以使用“attributes”标签为每个文章类型自定义“文章属性”标签。

向后兼容性：

假设您要公开发布支持文章类型模板的主题。4.7之前的WordPress版本将忽略Template Post Type标头，并在页面模板列表中显示该模板，即使它仅适用于其他文章类型。为了防止这种情况，您可以加入theme_page_templates过滤器以将其从列表中排除。这是一个例子：

/**
* 为 WordPress 4.6 及以下版本隐藏自定义文章类型的页面模板
*
* @param array $post_templates Array of page templates. Keys are filenames, values are translated names.
* @return array Filtered array of page templates.
*/
function makewp_exclude_page_templates( $post_templates ) {
if ( version_compare( $GLOBALS['wp_version'], '4.7', '<' ) ) {
unset( $post_templates['templates/my-full-width-post-template.php'] );
}
return $post_templates;
}
add_filter( 'theme_page_templates', 'makewp_exclude_page_templates' );

这样，您可以在WordPress 4.7及更高版本中支持自定义文章类型模板，同时保持向后兼容性。

请注意，theme_page_templates实际上是一个动态 theme_{$post_type}_templates 过滤器。挂钩名称的$post_type动态部分是指模板支持的文章类型。例如，您可以使用theme_product_templates来过滤产品发布类型的模板列表。

在页面模板中使用条件标签

您可以在 page.php 文件中使用“条件标签”来进行较小的、特定于页面的修改。例如，下面的示例代码为您的首页加载了 header-home.php 文件，但为“关于”页面加载了另一个文件 header-about.php ，然后为所有其他页面应用了默认文件 header.php 。

if ( is_front_page() ) :
    get_header( 'home' );
elseif ( is_page( 'About' ) ) :
    get_header( 'about' );
else:
    get_header();
endif;

您可以在此处了解有关条件标签的更多信息。

识别页面模板

如果您的模板使用了 body_class() 函数，则WordPress将在body标签中为文章类型添加类名（page），页面ID（page-id-{ID}）和所使用的页面模板文件名。对于默认值 page.php，生成的类名为 page-template-default：

<body class="page page-id-6 page-template-default">

一个特定的模板（page-{slug}.php 或 page-{ID}.php），也生成了 page-template-default 类，而不是自己的body类。

使用自定义页面模板时，page-template 将会输出，然后还会根据特定模板名称输出一个类名。例如，如果您的自定义页面模板文件命名如下：

<?php
/* Template Name: My Custom Page */
?>

然后生成的渲染HTML将如下所示：

<body class="page page-id-6 page-template page-template-my-custom-page-php">

请注意page-template-my-custom-page-php 这个类名是应用到body标签中的。

页面模板函数

这些内置的WordPress函数和方法可以帮助您使用页面模板：

get_page_template() 返回用于呈现页面的页面模板的路径。
wp_get_theme()->get_page_templates() 返回当前激活主题可用的所有自定义页面模板（get_page_templates()是WP_Theme类的方法）。
is_page_template() 根据是否使用了自定义页面模板渲染页面，来返回true或false。
get_page_template_slug()返回自定义字段 _wp_page_template 的值（当值为空或“default”时，返回 null ）。如果已为页面分配了自定义模板，则该模板的文件名将存储为自定义字段 _wp_page_template 的值，该数据保存在 wp_postmeta 表中。（以下划线开头的自定义字段不会显示在编辑界面的“自定义字段”模块中。）

这篇文章对您有用吗？是 5 否 1

{{userData.name}}已认证