云策 WordPress 开发者社区

钩子文档

render_block

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

概述

render_block 是一个 WordPress 过滤器，用于修改单个块的内容输出。它允许开发者在块渲染过程中介入，自定义或调整块的 HTML 内容。

关键要点

  • render_block 过滤器接收三个参数：$block_content（块内容字符串）、$block（包含块名称和属性的数组）、$instance（WP_Block 实例）。
  • 该过滤器可用于包装块内容（如添加 div 元素）、基于块属性动态修改输出，或处理特定块类型。
  • 使用时需注意 $block['attrs'] 可能不包含 block.json 中 source 设置为 'attribute' 的属性，且 $block_content 和 $block 可能为 null，应进行空值检查。

代码示例

// 示例：为特定块添加包装器
div>
    $content = '<div class="wrapper">';
    $content .= $block_content;
    $content .= '</div>';
    return $content;
}
return $block_content;
}
add_filter( 'render_block', 'wporg_block_wrapper', 10, 2 );

注意事项

  • 在 WordPress 5.9.0 中引入了 $instance 参数，早期版本仅有两个参数。
  • 用户贡献笔记指出，某些情况下 core 块的 blockName 可能为 null，建议使用 isset() 进行检查。
  • 调试时可通过 print_r( $block ) 查看可用属性，以正确访问 $block['attrs']。
📄 原文内容

Filters the content of a single block.

Parameters

$block_contentstring
The block content.
$blockarray
The full block, including name and attributes.
$instanceWP_Block
The block instance.

Source

$block_content = apply_filters( 'render_block', $block_content, $this->parsed_block, $this );

View all references View on Trac View on GitHub

Used by Description
WP_Block::render()wp-includes/class-wp-block.php

Generates the render output for the block.

Changelog

Version Description
5.9.0 The $instance parameter was added.
5.0.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Khoi Pro


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

    To add a div wrapper outside of some blocks (like core/paragraph or core/heading), you can add filter to render_block:

    // functions.php
function wporg_block_wrapper( $block_content, $block ) {
	if ( $block['blockName'] === 'core/paragraph' ) {
		$content = '<div class="wp-block-paragraph">';
		$content .= $block_content;
		$content .= '</div>';
		return $content;
	} elseif ( $block['blockName'] === 'core/heading' ) {
		$content = '<div class="wp-block-heading">';
		$content .= $block_content;
		$content .= '</div>';
		return $content;
	}
	return $block_content;
}

add_filter( 'render_block', 'wporg_block_wrapper', 10, 2 );

  2. Skip to note 6 content


    Marie Comet


    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

    $block<br />
    (array) The full block, including name and attributes.

    Good to know that $block['attrs'] do not include attributes declared in block.json with “source” set to “attribute”.

    For example, in a block.json :

    "attributes": {
    "url": {
        "type": "string",
        "source": "attribute",
        "selector": "a",
        "attribute": "href"
    },
    "width": {
        "type": "number"
    }
}

    $block['attrs'] only include width, not url.

  3. Skip to note 7 content


    Phil Johnston


    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

    Here’s a quick/rough example of how you can render any block in any way with this filter. Note that the example uses an attribute called `name_of_attribute_here`. You’ll want to use an actual attribute that belongs to that block.

    A quick/easy way to discover what’s available to you is to `print_r( $block );` inside the function, refresh the frontend page where the block sits, and see what’s available in the `attrs`. 

    /**
 * Modify the rendered output of any block.
 *
 * @param string $block_content The normal block HTML that would be sent to the screen.
 * @param array  $block An array of data about the block, and the way the user configured it.
 */
function my_custom_render( $block_content, $block ) {

	// For the block in question, render whatever you want, and pull any attrinute you need from $block['attrs'].
	if ( $block['blockName'] === 'core/image' ) {
		return 'Anything I want with any attribute value here: ' . $block['attrs']['name_of_attribute_here'] . '.';
	}

	// For any other block, just return normal block output.
	return $block_content;

}
add_filter( 'render_block', 'my_custom_render', 10, 2 );

  4. Skip to note 8 content


    Benjamin Intal


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

    $block_content and $block can become null, so be sure to handle these cases.

    function wpdocs_render_block( $block_content, $block ) {
	if ( is_null( $block_content ) ) {
		// Handle null
	}

	if ( isset( $block['blockName'] ) && 'wpdocs/block' === $block['blockName'] ) {
		// Do something
	}

	return $block_content;
}
add_filter( 'render_block', 'wpdocs_render_block', 10, 2 );