函数文档

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.

Return

string Block template markup.

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.