云策 WordPress 开发者社区

钩子文档

theme_page_templates

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

概述

theme_page_templates 是一个 WordPress 过滤器，用于修改主题的页面模板列表。它允许开发者动态控制哪些模板文件在页面编辑器中可用，常用于移除或添加特定模板。

关键要点

  • 过滤器名称：theme_page_templates，用于过滤页面模板数组。
  • 参数：$page_templates（数组，键为文件名，值为翻译后的名称）、$this（WP_Theme 对象）、$post（WP_Post 对象或 null）。
  • 用途：可移除或添加模板，例如在子主题中移除父主题模板，或基于博客 ID 条件过滤模板。
  • 版本历史：WordPress 4.4.0 起允许完全控制 $page_templates 数组，3.9.0 引入。

代码示例

/* 移除父主题页面模板 */
function child_remove_page_templates( $page_templates ) {
  unset( $page_templates['template-cover.php'] );
  unset( $page_templates['template-full-width-cover.php'] );
  unset( $page_templates['template-full-width-only-content.php'] );
  unset( $page_templates['template-full-width.php'] );
  unset( $page_templates['template-only-content.php'] );

  return $page_templates;
}
add_filter( 'theme_page_templates', 'child_remove_page_templates' );
add_filter( 'theme_post_templates', 'child_remove_page_templates' );
/**
 * 过滤主题页面模板。
 *
 * @param array    $page_templates 页面模板。
 * @param WP_Theme $this           WP_Theme 实例。
 * @param WP_Post  $post           正在编辑的文章，提供上下文，或 null。
 * @return array (可能) 修改后的页面模板数组。
 */
function wpdocs_filter_theme_page_templates( $page_templates, $this, $post ) {
	$current_blog_id = get_current_blog_id();
	$food_blog_id    = 2;

	if ( $current_blog_id != $food_blog_id ) {
		if ( isset( $page_templates['page-food.php'] ) ) {
			unset( $page_templates['page-food.php'] );
		}
	}
	return $page_templates;
}
add_filter( 'theme_page_templates', 'wpdocs_filter_theme_page_templates', 20, 3 );

注意事项

  • 如需同时从页面和文章中移除模板，需同时使用 theme_page_templates 和 theme_post_templates 过滤器。
  • 过滤“默认模板”选项应使用 default_page_template_title 过滤器。
📄 原文内容

Filters list of page templates for a theme.

Parameters

$page_templatesarray
Array of page templates. Keys are filenames, values are translated names.
$thisWP_Theme
The theme object.
$postWP_Post|null
The post being edited, provided for context, or null.

Source

View all references View on Trac View on GitHub

Changelog

Version Description
4.4.0 Converted to allow complete control over the $page_templates array.
3.9.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Julie Kuehl


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

    If you want to remove templates from both Pages and Posts, you will need to also use the `theme_post_templates` in addition to the `theme_page_templates` filter.

    /* Remove parent theme page templates */

function child_remove_page_templates( $page_templates ) {
  unset( $page_templates['template-cover.php'] );
  unset( $page_templates['template-full-width-cover.php'] );
  unset( $page_templates['template-full-width-only-content.php'] );
  unset( $page_templates['template-full-width.php'] );
  unset( $page_templates['template-only-content.php'] );

  return $page_templates;
}
add_filter( 'theme_page_templates', 'child_remove_page_templates' );
add_filter( 'theme_post_templates', 'child_remove_page_templates' );

  2. Skip to note 5 content


    SpartakusMd


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

    Filter page templates by blog id

    Suppose you have the blog `Food` with the id 2 and the template `page-food.php` which should only be used for this blog. The example below removes the page template from dropdowns of other blogs:

    /**
 * Filter the theme page templates.
 *
 * @param array    $page_templates Page templates.
 * @param WP_Theme $this           WP_Theme instance.
 * @param WP_Post  $post           The post being edited, provided for context, or null.
 * @return array (Maybe) modified page templates array.
 */
function wpdocs_filter_theme_page_templates( $page_templates, $this, $post ) {
	$current_blog_id = get_current_blog_id();
	$food_blog_id    = 2;

	if ( $current_blog_id != $food_blog_id ) {
		if ( isset( $page_templates['page-food.php'] ) ) {
			unset( $page_templates['page-food.php'] );
		}
	}
	return $page_templates;
}
add_filter( 'theme_page_templates', 'wpdocs_filter_theme_page_templates', 20, 3 );