get_the_block_template_html()
云策文档标注
概述
get_the_block_template_html() 函数用于返回当前模板的 HTML 标记。它处理块模板内容,包括短码、嵌入和块渲染,并针对单数模板提供特殊循环逻辑以确保兼容性。
关键要点
- 函数返回当前块模板的 HTML 标记字符串。
- 如果未找到模板内容,对已登录用户显示“No matching template found”消息,否则返回空字符串。
- 处理内容时,依次执行短码运行、自动嵌入、短码去自动段落化和短码处理。
- 对于来自当前主题的单数模板,确保进入主查询循环以调用 do_blocks(),避免核心和插件生态中的错误。
- 最终内容经过文本格式化、表情符号转换、标签过滤和安全处理,并包装在 .wp-site-blocks div 中返回。
代码示例
if ( ! $_wp_current_template_content ) {
if ( is_user_logged_in() ) {
return '<div class="notice notice-warning">' . esc_html__( 'No matching template found' ) . '</div>';
}
return '';
}注意事项
- 特殊循环逻辑仅适用于来自当前主题的单数模板,插件注入的模板应跳过此处理以避免不可预测行为。
- 函数依赖于全局变量如 $_wp_current_template_content 和 $wp_query,确保它们在调用前已正确设置。
原文内容
Returns the markup for the current template.
Source
function get_the_block_template_html() {
global $_wp_current_template_id, $_wp_current_template_content, $wp_embed, $wp_query;
if ( ! $_wp_current_template_content ) {
if ( is_user_logged_in() ) {
return '<h1>' . esc_html__( 'No matching template found' ) . '</h1>';
}
return '';
}
$content = $wp_embed->run_shortcode( $_wp_current_template_content );
$content = $wp_embed->autoembed( $content );
$content = shortcode_unautop( $content );
$content = do_shortcode( $content );
/*
* Most block themes omit the `core/query` and `core/post-template` blocks in their singular content templates.
* While this technically still works since singular content templates are always for only one post, it results in
* the main query loop never being entered which causes bugs in core and the plugin ecosystem.
*
* The workaround below ensures that the loop is started even for those singular templates. The while loop will by
* definition only go through a single iteration, i.e. `do_blocks()` is only called once. Additional safeguard
* checks are included to ensure the main query loop has not been tampered with and really only encompasses a
* single post.
*
* Even if the block template contained a `core/query` and `core/post-template` block referencing the main query
* loop, it would not cause errors since it would use a cloned instance and go through the same loop of a single
* post, within the actual main query loop.
*
* This special logic should be skipped if the current template does not come from the current theme, in which case
* it has been injected by a plugin by hijacking the block template loader mechanism. In that case, entirely custom
* logic may be applied which is unpredictable and therefore safer to omit this special handling on.
*/
if (
$_wp_current_template_id &&
str_starts_with( $_wp_current_template_id, get_stylesheet() . '//' ) &&
is_singular() &&
1 === $wp_query->post_count &&
have_posts()
) {
while ( have_posts() ) {
the_post();
$content = do_blocks( $content );
}
} else {
$content = do_blocks( $content );
}
$content = wptexturize( $content );
$content = convert_smilies( $content );
$content = wp_filter_content_tags( $content, 'template' );
$content = str_replace( ']]>', ']]>', $content );
// Wrap block template in .wp-site-blocks to allow for specific descendant styles
// (e.g. `.wp-site-blocks > *`).
return '<div class="wp-site-blocks">' . $content . '</div>';
}
Changelog
| Version | Description |
|---|---|
| 5.8.0 | Introduced. |