get_query_template()
云策文档标注
概述
get_query_template() 函数用于快速检索模板文件的路径，无需包含文件扩展名。它通过 locate_template() 检查当前主题和父主题，提供更通用的模板定位方式，避免使用其他 get_*_template() 函数。
关键要点
- 函数参数：$type（必需，不带扩展名的文件名），$templates（可选，模板候选列表，默认为空数组）
- 返回完整模板文件路径字符串
- 内部使用 locate_template() 和 locate_block_template() 查找模板
- 提供两个动态过滤器：{$type}_template_hierarchy 和 {$type}_template，用于修改模板候选列表和最终路径
- 支持多种模板类型，如 404、archive、single 等，对应不同的 Hook 名称
代码示例
if ( '' !== get_query_template( '404' ) ) {
include( get_query_template( '404' ) );
}
// 或使用 get_404_template() 实现相同功能
if ( '' != get_404_template() ) {
include( get_404_template() );
}
原文内容
Retrieves path to a template.
Description
Used to quickly retrieve the path of a template without including the file extension. It will also check the parent theme, if the file exists, with the use of locate_template() . Allows for more generic template location without the use of the other get_*_template() functions.
Parameters
$typestringrequired-
Filename without extension.
$templatesstring[]optional-
An optional list of template candidates.
Default:
array()
Source
function get_query_template( $type, $templates = array() ) {
$type = preg_replace( '|[^a-z0-9-]+|', '', $type );
if ( empty( $templates ) ) {
$templates = array( "{$type}.php" );
}
/**
* Filters the list of template filenames that are searched for when retrieving a template to use.
*
* 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.
* The last element in the array should always be the fallback template for this query type.
*
* Possible hook names include:
*
* - `404_template_hierarchy`
* - `archive_template_hierarchy`
* - `attachment_template_hierarchy`
* - `author_template_hierarchy`
* - `category_template_hierarchy`
* - `date_template_hierarchy`
* - `embed_template_hierarchy`
* - `frontpage_template_hierarchy`
* - `home_template_hierarchy`
* - `index_template_hierarchy`
* - `page_template_hierarchy`
* - `paged_template_hierarchy`
* - `privacypolicy_template_hierarchy`
* - `search_template_hierarchy`
* - `single_template_hierarchy`
* - `singular_template_hierarchy`
* - `tag_template_hierarchy`
* - `taxonomy_template_hierarchy`
*
* @since 4.7.0
*
* @param string[] $templates A list of template candidates, in descending order of priority.
*/
$templates = apply_filters( "{$type}_template_hierarchy", $templates );
$template = locate_template( $templates );
$template = locate_block_template( $template, $type, $templates );
/**
* Filters the path of the queried template by type.
*
* 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`
*
* @since 1.5.0
* @since 4.8.0 The `$type` and `$templates` parameters were added.
*
* @param string $template Path to the template. See locate_template().
* @param string $type Sanitized filename without extension.
* @param string[] $templates A list of template candidates, in descending order of priority.
*/
return apply_filters( "{$type}_template", $template, $type, $templates );
}
Hooks
- apply_filters( “{$type}_template”, string $template, string $type, string[] $templates )
-
Filters the path of the queried template by type.
- apply_filters( “{$type}_template_hierarchy”, string[] $templates )
-
Filters the list of template filenames that are searched for when retrieving a template to use.
Changelog
| Version | Description |
|---|---|
| 1.5.0 | Introduced. |
Skip to note 2 content
Codex
Example
Can be used with include() or require() to retrieve path.
if ( '' !== get_query_template( '404' ) ) { include( get_query_template( '404' ) ); }or the same can be accomplished with
if ( '' != get_404_template() ) { include( get_404_template() ); }