云策 WordPress 开发者社区

钩子文档

{$type}_template

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

概述

{$type}_template 是一个 WordPress 过滤器钩子，用于根据类型过滤查询到的模板路径。它允许开发者在模板层级系统中动态修改特定类型模板的加载路径，例如自定义分类法或文章类型的模板。

关键要点

  • 钩子名称由动态部分 $type 构成，如 taxonomy_template、single_template 等，对应模板文件名（去除扩展名和非字母数字字符）。
  • 参数包括 $template（模板路径字符串）、$type（无扩展名的净化文件名）和 $templates（模板候选列表数组）。
  • 适用于各种模板层级文件，如 404、归档、页面等，提供对模板选择的细粒度控制。
  • 从 WordPress 4.8.0 版本开始，添加了 $type 和 $templates 参数。
  • 如果需要更全面的模板控制，建议使用 template_include 钩子。

代码示例

// 示例：为自定义分类法加载特定模板
add_filter( "taxonomy_template", 'load_our_custom_tax_template');
function load_our_custom_tax_template ($tax_template) {
  if (is_tax('custom-tax-name')) {
    $tax_template = dirname( __FILE__ ) . '/templates/custom-taxonomy-template.php';
  }
  return $tax_template;
}

注意事项

  • 确保钩子名称正确匹配模板类型，如 archive_template 用于归档页面。
  • 在函数中检查条件（如 is_tax() 或 is_post_type_archive()）以避免影响其他模板。
  • 使用 locate_template() 函数可以安全地定位主题中的模板文件。
📄 原文内容

Filters the path of the queried template by type.

Description

The dynamic portion of the hook name, $type, refers to the filename — minus the file extension and any non-alphanumeric characters delimiting words — of the file to load.
This hook also applies to various types of files loaded as part of the Template Hierarchy.

Possible hook names include:

  • 404_template
  • archive_template
  • attachment_template
  • author_template
  • category_template
  • date_template
  • embed_template
  • frontpage_template
  • home_template
  • index_template
  • page_template
  • paged_template
  • privacypolicy_template
  • search_template
  • single_template
  • singular_template
  • tag_template
  • taxonomy_template

Parameters

$templatestring
Path to the template. See locate_template() .

More Arguments from locate_template( … $args )

Additional arguments passed to the template.

$typestring
Sanitized filename without extension.
$templatesstring[]
A list of template candidates, in descending order of priority.

More Information

If you need more granular control over the template selection and loading system of WordPress, consider using template_include instead.

Source

return apply_filters( "{$type}_template", $template, $type, $templates );

View all references View on Trac View on GitHub

Used by Description
get_query_template()wp-includes/template.php

Retrieves path to a template.

Changelog

Version Description
4.8.0 The $type and $templates parameters were added.
1.5.0 Introduced.

User Contributed Notes

  1. Skip to note 6 content


    alordiel


    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

    We can use this filter in case that we want to add and archive page for our custom taxonomy that we have created from a plugin. In this case the filter we will need is “taxonomy_template”.

    add_filter( "taxonomy_template", 'load_our_custom_tax_template');
function load_our_custom_tax_template ($tax_template) {
  if (is_tax('custom-tax-name')) {
    $tax_template = dirname(  __FILE__  ) . '/templates/custom-taxonomy-template.php';
  }
  return $tax_template;
}

  2. Skip to note 7 content


    Steven Lin


    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

    Example Migrated from Codex:

    The example code will load the template file “post-type-template.php” located in your plugins folder for any posts or pages that have the type of ‘my_post_type‘ else uses default template.

    post_type ) {
		$single_template = dirname( __FILE__ ) . '/post-type-template.php';
	}

	return $single_template;
}
?>

  3. Skip to note 8 content


    Steven Lin


    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

    Example Migrated from Codex:

    This example loads the template file single-{post_type}-{slug}.php (e.g. single-event-wordcamp.php) only if the file exists, otherwise loads default template.

    post_type}-{$object->post_name}.php" );

	if ( file_exists( $single_posttype_postname_template ) ) {
		return $single_posttype_postname_template;
	} else {
		return $single_template;
	}
}
?>

  4. Skip to note 9 content


    Steven Lin


    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

    Example Migrated from Codex:

    This example loads a custom category template for categories 62, 65, and 59.

    add_filter( 'category_template', 'filter_category_template', 99 );

function filter_category_template( $template ) {

	 if ( is_category(array( 64,65,59 )  )  ) {
		$new_template = locate_template( array( 'category-template.php' ) );
		if ( '' != $new_template ) {
			return $new_template;
		}
	}

	return $template;
}

  5. Skip to note 10 content


    Steven Lin


    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

    Example Migrated from Codex:

    The example below will load the template file “post-type-template.php” located in your plugins folder for any archive page that has the type of “my_post_type“; otherwise, uses default template.

    add_filter( 'archive_template', 'get_custom_post_type_template' );

function get_custom_post_type_template( $archive_template ) {
     global $post;

     if ( is_post_type_archive ( 'my_post_type' ) ) {
          $archive_template = dirname( __FILE__ ) . '/post-type-template.php';
     }
     return $archive_template;
}