云策 WordPress 开发者社区

函数文档

is_page_template()

查看官方原文 ↗
💡 云策文档标注

概述

is_page_template() 是一个 WordPress 条件标签函数，用于检查当前文章是否使用了页面模板。它支持指定单个模板文件名或数组进行精确匹配，并返回布尔值。

关键要点

  • 函数用于判断当前文章是否分配了页面模板，可传入 $template 参数（字符串或数组）来检查特定模板。
  • 不能在 The Loop 内部使用，因为全局变量会被覆盖；如需在 The Loop 后使用，必须先调用 wp_reset_query()。
  • 从 WordPress 4.7.0 开始，支持所有文章类型，而不仅仅是页面。
  • 如果页面模板位于主题子目录中，需在文件名前添加文件夹路径（如 'templates/about.php'）。
  • 内部通过查询 post_meta 实现，可使用 get_page_template_slug() 作为替代方法在任何地方检查模板分配。

代码示例

// 检查特定模板
if ( is_page_template( 'about.php' ) ) {
    // about.php 被使用
} else {
    // about.php 未被使用
}

// 检查子目录中的模板
if ( is_page_template( 'templates/about.php' ) ) {
    // 模板位于子目录
}

// 检查多个模板
if ( is_page_template( array( 'template-full-width.php', 'template-product-offers.php' ) ) ) {
    // 任一模板被使用
}

// 使用 get_page_template_slug() 替代
if ( get_page_template_slug( get_the_ID() ) ) {
    // 页面有模板分配
}

注意事项

  • 传入 $template 参数时，需使用模板文件名（如 about.php），而不是模板名称或 slug。
  • 对于 HTML 模板文件（如 .html 后缀），在参数中应省略后缀（例如 'page-no-title' 对应 templates/page-no-title.html）。
  • 函数依赖于全局查询对象，确保在正确上下文中调用以避免意外结果。
📄 原文内容

Determines whether the current post uses a page template.

Description

This template tag allows you to determine if you are in a page template.
You can optionally provide a template filename or array of template filenames and then the check will be specific to that template.

For more information on this and similar theme functions, check out the Conditional Tags article in the Theme Developer Handbook.

Parameters

$templatestring|string[]required
The specific template filename or array of templates to match.

Return

bool True on success, false on failure.

More Information

Page template in subdirectory

If the page template is located in a subdirectory of the theme (since WP 3.4), prepend the folder name and a slash to the template filename, e.g.:

is_page_template( 'templates/about.php' );

Cannot Be Used Inside The Loop

Due to certain global variables being overwritten during The Loop is_page_template() will not work. In order to use it after The Loop you must call wp_reset_query() after The Loop.

Alternative

Since the page template slug is stored inside the post_meta for any post that has been assigned to a page template, it is possible to directly query the post_meta to see whether any given page has been assigned a page template. This is the method that is_page_template() uses internally.

The function get_page_template_slug( $post_id ) will return the slug of the currently assigned page template (or an empty string if no template has been assigned – or false if the $post_id does not correspond to an actual page). You can easily use this anywhere (in The Loop, or outside) to determine whether any page has been assigned a page template.

// in the loop:
if ( get_page_template_slug( get_the_ID() ) ){
// Yep, this page has a page template
}

// anywhere:
if ( get_page_template_slug( $some_post_ID ) ){
// Uh-huh.
}

Source

function is_page_template( $template = '' ) {
	if ( ! is_singular() ) {
		return false;
	}

	$page_template = get_page_template_slug( get_queried_object_id() );

	if ( empty( $template ) ) {
		return (bool) $page_template;
	}

	if ( $template === $page_template ) {
		return true;
	}

	if ( is_array( $template ) ) {
		if ( ( in_array( 'default', $template, true ) && ! $page_template )
			|| in_array( $page_template, $template, true )
		) {
			return true;
		}
	}

	return ( 'default' === $template && ! $page_template );
}

View all references View on Trac View on GitHub

Uses Description
is_singular()wp-includes/query.php

Determines whether the query is for an existing single post of any post type (post, attachment, page, custom post types).
get_queried_object_id()wp-includes/query.php

Retrieves the ID of the currently queried object.
get_page_template_slug()wp-includes/post-template.php

Gets the specific template filename for a given post.
Used by Description
get_body_class()wp-includes/post-template.php

Retrieves an array of the class names for the body element.

Changelog

Version Description
4.7.0 Now works with any post type, not just pages.
4.2.0 The $template parameter was changed to also accept an array of page templates.
2.5.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

    Is Page Template ‘about’ being used? Note that unlike with other conditionals, if you want to specify a particular Page Template, you need to use the filename, such as about.php or my_page_template.php.

    if ( is_page_template( 'about.php' ) ) {
	// about.php is used
} else {
	// about.php is not used
}

  2. Skip to note 6 content


    Sam Kent


    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

    If your page template resides within a directory, you can use something like this:

    if ( is_page_template( 'directory-name/page-about.php' ) ) {
    // about.php is used
} else {
    // about.php is not used
}

    This can be useful if you’re using multiple page templates and want to keep your files organised.

  3. Skip to note 7 content


    Anthony Hortin


    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    You can also specify multiple templates by passing an array of template names.

    if ( is_page_template( array( 'template-full-width.php', 'template-product-offers.php' ) ) ) {
   // Do Something here if either of the above templates are being used
}
else {
   // Else do this
}

  4. Skip to note 8 content


    Anders Norén


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    If the post is assigned to a HTML template inside the /templates/ folder, the $template parameter should be the template filename without the .html suffix.

     if ( is_page_template( 'page-no-title' ) ) {
	// templates/page-no-title.html is used 
} else {
	// templates/page-no-title.html is not used 
}