get_block_file_template()
云策文档标注
概述
get_block_file_template() 函数用于基于主题文件或插件注册检索统一的块模板对象。它是 get_block_template() 的回退机制，当数据库中未找到模板时使用，并检查通过模板注册 API 注册的模板。
关键要点
- 函数作为 get_block_template() 的回退，优先从主题文件或插件注册中获取模板对象。
- 接受两个参数：$id（必需，模板唯一标识符，如 'theme_slug//template_slug'）和 $template_type（可选，模板类型，默认为 'wp_template'）。
- 返回 WP_Block_Template 对象或 null，表示未找到模板。
- 包含两个过滤器钩子：pre_get_block_file_template（在主题文件发现前过滤）和 get_block_file_template（在主题文件发现后过滤）。
- 内部处理包括解析 $id、检查模板注册、从主题文件构建模板对象，并应用块钩子到内容。
代码示例
function get_block_file_template( $id, $template_type = 'wp_template' ) {
$block_template = apply_filters( 'pre_get_block_file_template', null, $id, $template_type );
if ( ! is_null( $block_template ) ) {
return $block_template;
}
$parts = explode( '//', $id, 2 );
if ( count( $parts ) < 2 ) {
return null;
}
list( $theme, $slug ) = $parts;
$registry = WP_Block_Templates_Registry::get_instance();
$block_template = $registry->get_by_slug( $slug );
if ( ! $block_template ) {
$block_template = _get_block_template_file( $theme, $slug, $template_type );
if ( $block_template ) {
$block_template = _build_block_template_result_from_file( $block_template, $template_type );
}
}
if ( $block_template ) {
$block_template->content = apply_block_hooks_to_content(
$block_template->content,
$block_template,
'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata'
);
}
return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );
}注意事项
- 函数在 WordPress 5.9.0 版本中引入，是块主题系统的一部分。
- 确保 $id 参数格式正确，使用 '//' 分隔主题和模板 slug，否则可能返回 null。
- 过滤器钩子允许开发者自定义模板检索逻辑，例如通过 pre_get_block_file_template 提前返回模板对象。
- 相关函数包括 get_block_template()、_build_block_template_result_from_file() 等，用于辅助模板处理。
原文内容
Retrieves a unified template object based on a theme file or plugin registration.
Description
This is a fallback of get_block_template() , used when no templates are found in the database.
Also checks for templates registered via the Template Registration API.
Parameters
$idstringrequired-
Template unique identifier (example:
'theme_slug//template_slug'). $template_typestringoptional-
Template type. Either
'wp_template'or'wp_template_part'.
Default'wp_template'.
Source
function get_block_file_template( $id, $template_type = 'wp_template' ) {
/**
* Filters the block template object before the theme file discovery takes place.
*
* Return a non-null value to bypass the WordPress theme file discovery.
*
* @since 5.9.0
*
* @param WP_Block_Template|null $block_template Return block template object to short-circuit the default query,
* or null to allow WP to run its normal queries.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
*/
$block_template = apply_filters( 'pre_get_block_file_template', null, $id, $template_type );
if ( ! is_null( $block_template ) ) {
return $block_template;
}
$parts = explode( '//', $id, 2 );
if ( count( $parts ) < 2 ) {
/** This filter is documented in wp-includes/block-template-utils.php */
return apply_filters( 'get_block_file_template', null, $id, $template_type );
}
list( $theme, $slug ) = $parts;
if ( get_stylesheet() === $theme ) {
$template_file = _get_block_template_file( $template_type, $slug );
if ( null !== $template_file ) {
$block_template = _build_block_template_result_from_file( $template_file, $template_type );
/** This filter is documented in wp-includes/block-template-utils.php */
return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );
}
}
$block_template = WP_Block_Templates_Registry::get_instance()->get_by_slug( $slug );
if ( $block_template ) {
$block_template->content = apply_block_hooks_to_content(
$block_template->content,
$block_template,
'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata'
);
}
/**
* Filters the block template object after it has been (potentially) fetched from the theme file.
*
* @since 5.9.0
*
* @param WP_Block_Template|null $block_template The found block template, or null if there is none.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
*/
return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );
}
Hooks
- apply_filters( ‘get_block_file_template’, WP_Block_Template|null $block_template, string $id, string $template_type )
-
Filters the block template object after it has been (potentially) fetched from the theme file.
- apply_filters( ‘pre_get_block_file_template’, WP_Block_Template|null $block_template, string $id, string $template_type )
-
Filters the block template object before the theme file discovery takes place.
Changelog
| Version | Description |
|---|---|
| 5.9.0 | Introduced. |