locate_block_template()
云策文档标注
概述
locate_block_template() 函数用于在块主题中查找与给定 PHP 模板文件具有相同或更高特异性的块模板。它通过全局变量传递块内容到模板画布，并返回模板画布文件路径或回退的 PHP 模板。
关键要点
- 函数定位块模板，优先于 PHP 模板，支持块主题功能。
- 参数包括模板路径、类型和模板候选列表，返回模板画布文件路径或回退 PHP 模板。
- 内部使用 resolve_block_template() 解析块模板，并设置全局变量 $_wp_current_template_content 和 $_wp_current_template_id。
- 处理空模板内容时，根据用户登录状态显示警告或主题文件内容。
- 添加钩子以支持模板画布的视口元标签和标题标签渲染。
代码示例
function locate_block_template( $template, $type, array $templates ) {
global $_wp_current_template_content, $_wp_current_template_id;
if ( ! current_theme_supports( 'block-templates' ) ) {
return $template;
}
if ( $template ) {
$relative_template_path = str_replace(
array( get_stylesheet_directory() . '/', get_template_directory() . '/' ),
'',
$template
);
$index = array_search( $relative_template_path, $templates, true );
$templates = array_slice( $templates, 0, $index + 1 );
}
$block_template = resolve_block_template( $type, $templates, $template );
if ( $block_template ) {
$_wp_current_template_id = $block_template->id;
// 处理模板内容逻辑
if ( isset( $_GET['_wp-find-template'] ) ) {
wp_send_json_success( $block_template );
}
} else {
if ( $template ) {
return $template;
}
if ( 'index' === $type ) {
if ( isset( $_GET['_wp-find-template'] ) ) {
wp_send_json_error( array( 'message' => __( 'No matching template found.' ) ) );
}
} else {
return '';
}
}
add_action( 'wp_head', '_block_template_viewport_meta_tag', 0 );
remove_action( 'wp_head', '_wp_render_title_tag', 1 );
add_action( 'wp_head', '_block_template_render_title_tag', 1 );
return ABSPATH . WPINC . '/template-canvas.php';
}注意事项
- 函数仅在主题支持 'block-templates' 时生效，否则直接返回 PHP 模板。
- 使用全局变量 $_wp_current_template_content 和 $_wp_current_template_id 传递模板内容，需注意其作用域。
- 在 AJAX 请求中，通过 $_GET['_wp-find-template'] 参数返回 JSON 响应。
- 返回路径指向模板画布文件，用于替代主题模板文件。
原文内容
Finds a block template with equal or higher specificity than a given PHP template file.
Description
Internally, this communicates the block content that needs to be used by the template canvas through a global variable.
Parameters
$templatestringrequired-
Path to the template. See locate_template() .
More Arguments from locate_template( … $args )
Additional arguments passed to the template.
$typestringrequired-
Sanitized filename without extension.
$templatesstring[]required-
A list of template candidates, in descending order of priority.
Source
function locate_block_template( $template, $type, array $templates ) {
global $_wp_current_template_content, $_wp_current_template_id;
if ( ! current_theme_supports( 'block-templates' ) ) {
return $template;
}
if ( $template ) {
/*
* locate_template() has found a PHP template at the path specified by $template.
* That means that we have a fallback candidate if we cannot find a block template
* with higher specificity.
*
* Thus, before looking for matching block themes, we shorten our list of candidate
* templates accordingly.
*/
// Locate the index of $template (without the theme directory path) in $templates.
$relative_template_path = str_replace(
array( get_stylesheet_directory() . '/', get_template_directory() . '/' ),
'',
$template
);
$index = array_search( $relative_template_path, $templates, true );
// If the template hierarchy algorithm has successfully located a PHP template file,
// we will only consider block templates with higher or equal specificity.
$templates = array_slice( $templates, 0, $index + 1 );
}
$block_template = resolve_block_template( $type, $templates, $template );
if ( $block_template ) {
$_wp_current_template_id = $block_template->id;
if ( empty( $block_template->content ) ) {
if ( is_user_logged_in() ) {
$_wp_current_template_content = wp_render_empty_block_template_warning( $block_template );
} else {
if ( $block_template->has_theme_file ) {
// Show contents from theme template if user is not logged in.
$theme_template = _get_block_template_file( 'wp_template', $block_template->slug );
$_wp_current_template_content = file_get_contents( $theme_template['path'] );
} else {
$_wp_current_template_content = $block_template->content;
}
}
} elseif ( ! empty( $block_template->content ) ) {
$_wp_current_template_content = $block_template->content;
}
if ( isset( $_GET['_wp-find-template'] ) ) {
wp_send_json_success( $block_template );
}
} else {
if ( $template ) {
return $template;
}
if ( 'index' === $type ) {
if ( isset( $_GET['_wp-find-template'] ) ) {
wp_send_json_error( array( 'message' => __( 'No matching template found.' ) ) );
}
} else {
return ''; // So that the template loader keeps looking for templates.
}
}
// Add hooks for template canvas.
// Add viewport meta tag.
add_action( 'wp_head', '_block_template_viewport_meta_tag', 0 );
// Render title tag with content, regardless of whether theme has title-tag support.
remove_action( 'wp_head', '_wp_render_title_tag', 1 ); // Remove conditional title tag rendering...
add_action( 'wp_head', '_block_template_render_title_tag', 1 ); // ...and make it unconditional.
// This file will be included instead of the theme's template file.
return ABSPATH . WPINC . '/template-canvas.php';
}