云策 WordPress 开发者社区

函数文档

render_block()

查看官方原文 ↗
💡 云策文档标注

概述

render_block() 函数用于将单个块渲染为 HTML 字符串。它接受一个解析后的块数组作为参数，并返回渲染后的 HTML 输出。

关键要点

  • 参数 $parsed_block 是一个必需数组，包含块名称、属性、内部块等信息，结构参考 WP_Block_Parser_Block。
  • 函数通过 WP_Block 类进行渲染，并支持多个过滤器钩子（如 pre_render_block、render_block_data、render_block_context）以允许自定义渲染过程。
  • 返回值为字符串类型的渲染后 HTML。
  • 函数内部处理上下文信息，如当前文章的 ID 和类型，并可通过过滤器调整。

代码示例

$youtube_video_url = 'https://www.youtube.com/watch?v=...';

$youtube_embed_block = '
<!-- wp:embed {"url":"' . $youtube_video_url . '","type":"video","providerNameSlug":"youtube","responsive":true} -->
<figure class="wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube">
    <div class="wp-block-embed__wrapper">
        ' . $youtube_video_url . '
    </div>
</figure>
<!-- /wp:embed -->';

$parsed_blocks = parse_blocks( $youtube_embed_block );

if ( $parsed_blocks ) {
    foreach ( $parsed_blocks as $block ) {
        echo apply_filters( 'the_content', render_block( $block ) );
    }
}

注意事项

使用 render_block() 时，通常需要先使用 parse_blocks() 解析块内容，然后对每个块调用此函数。渲染结果可能需要通过 apply_filters( 'the_content', ... ) 进行进一步处理以获取最终输出。

📄 原文内容

Renders a single block into a HTML string.

Parameters

$parsed_blockarrayrequired
An associative array of the block being rendered. See WP_Block_Parser_Block.

  • blockName string|null
    Name of block.
  • attrs array
    Attributes from block comment delimiters.
  • innerBlocks array[]
    List of inner blocks. An array of arrays that have the same structure as this one.
  • innerHTML string
    HTML from inside block comment delimiters.
  • innerContent array
    List of string fragments and null markers where inner blocks were found.

Return

string String of rendered HTML.

Source

function render_block( $parsed_block ) {
	global $post;
	$parent_block = null;

	/**
	 * Allows render_block() to be short-circuited, by returning a non-null value.
	 *
	 * @since 5.1.0
	 * @since 5.9.0 The `$parent_block` parameter was added.
	 *
	 * @param string|null   $pre_render   The pre-rendered content. Default null.
	 * @param array         $parsed_block {
	 *     An associative array of the block being rendered. See WP_Block_Parser_Block.
	 *
	 *     @type string|null $blockName    Name of block.
	 *     @type array       $attrs        Attributes from block comment delimiters.
	 *     @type array[]     $innerBlocks  List of inner blocks. An array of arrays that
	 *                                     have the same structure as this one.
	 *     @type string      $innerHTML    HTML from inside block comment delimiters.
	 *     @type array       $innerContent List of string fragments and null markers where
	 *                                     inner blocks were found.
	 * }
	 * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block.
	 */
	$pre_render = apply_filters( 'pre_render_block', null, $parsed_block, $parent_block );
	if ( ! is_null( $pre_render ) ) {
		return $pre_render;
	}

	$source_block = $parsed_block;

	/**
	 * Filters the block being rendered in render_block(), before it's processed.
	 *
	 * @since 5.1.0
	 * @since 5.9.0 The `$parent_block` parameter was added.
	 *
	 * @param array         $parsed_block {
	 *     An associative array of the block being rendered. See WP_Block_Parser_Block.
	 *
	 *     @type string|null $blockName    Name of block.
	 *     @type array       $attrs        Attributes from block comment delimiters.
	 *     @type array[]     $innerBlocks  List of inner blocks. An array of arrays that
	 *                                     have the same structure as this one.
	 *     @type string      $innerHTML    HTML from inside block comment delimiters.
	 *     @type array       $innerContent List of string fragments and null markers where
	 *                                     inner blocks were found.
	 * }
	 * @param array         $source_block {
	 *     An un-modified copy of `$parsed_block`, as it appeared in the source content.
	 *     See WP_Block_Parser_Block.
	 *
	 *     @type string|null $blockName    Name of block.
	 *     @type array       $attrs        Attributes from block comment delimiters.
	 *     @type array[]     $innerBlocks  List of inner blocks. An array of arrays that
	 *                                     have the same structure as this one.
	 *     @type string      $innerHTML    HTML from inside block comment delimiters.
	 *     @type array       $innerContent List of string fragments and null markers where
	 *                                     inner blocks were found.
	 * }
	 * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block.
	 */
	$parsed_block = apply_filters( 'render_block_data', $parsed_block, $source_block, $parent_block );

	$context = array();

	if ( $post instanceof WP_Post ) {
		$context['postId'] = $post->ID;

		/*
		 * The `postType` context is largely unnecessary server-side, since the ID
		 * is usually sufficient on its own. That being said, since a block's
		 * manifest is expected to be shared between the server and the client,
		 * it should be included to consistently fulfill the expectation.
		 */
		$context['postType'] = $post->post_type;
	}

	/**
	 * Filters the default context provided to a rendered block.
	 *
	 * @since 5.5.0
	 * @since 5.9.0 The `$parent_block` parameter was added.
	 *
	 * @param array         $context      Default context.
	 * @param array         $parsed_block {
	 *     An associative array of the block being rendered. See WP_Block_Parser_Block.
	 *
	 *     @type string|null $blockName    Name of block.
	 *     @type array       $attrs        Attributes from block comment delimiters.
	 *     @type array[]     $innerBlocks  List of inner blocks. An array of arrays that
	 *                                     have the same structure as this one.
	 *     @type string      $innerHTML    HTML from inside block comment delimiters.
	 *     @type array       $innerContent List of string fragments and null markers where
	 *                                     inner blocks were found.
	 * }
	 * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block.
	 */
	$context = apply_filters( 'render_block_context', $context, $parsed_block, $parent_block );

	$block = new WP_Block( $parsed_block, $context );

	return $block->render();
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘pre_render_block’, string|null $pre_render, array $parsed_block, WP_Block|null $parent_block )

Allows render_block() to be short-circuited, by returning a non-null value.

apply_filters( ‘render_block_context’, array $context, array $parsed_block, WP_Block|null $parent_block )

Filters the default context provided to a rendered block.

apply_filters( ‘render_block_data’, array $parsed_block, array $source_block, WP_Block|null $parent_block )

Filters the block being rendered in render_block() , before it’s processed.

Uses Description
WP_Block::__construct()wp-includes/class-wp-block.php

Constructor.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
Used by Description
_excerpt_render_inner_blocks()wp-includes/blocks.php

Renders inner blocks from the allowed wrapper blocks for generating an excerpt.
WP_REST_Block_Renderer_Controller::get_item()wp-includes/rest-api/endpoints/class-wp-rest-block-renderer-controller.php

Returns block output from block’s registered render_callback.
do_blocks()wp-includes/blocks.php

Parses dynamic blocks out of post_content and re-renders them.
excerpt_remove_blocks()wp-includes/blocks.php

Parses blocks out of a content string, and renders those appropriate for the excerpt.

Changelog

Version Description
5.0.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    shanemac10


    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    If you are trying to render Gutenberg block code, you will need to use parse_blocks, then render_block on each result in the returned array, then use apply_filters( 'the_content', ... ) on the result, to then get the final block code.

    Here’s a generic example of what you might do to convert a YouTube URL into a wp-block-embed-youtube

    $youtube_video_url = 'https://www.youtube.com/watch?v=...';

$youtube_embed_block = '<!-- wp:embed {"url":"'.$youtube_video_url.'","type":"video","providerNameSlug":"youtube","responsive":true,"className":"wp-embed-aspect-16-9 wp-has-aspect-ratio"} -->
<figure class="wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio">
<div class="wp-block-embed__wrapper">'.$youtube_video_url.'</div>
</figure><!-- /wp:embed -->';

$parsed_blocks = parse_blocks( $youtube_embed_block );

if ( $parsed_blocks ) {
	foreach ( $parsed_blocks as $block ) {
		echo apply_filters( 'the_content', render_block( $block ) );
	}
}