详解 WordPress `WP_Block` 类的源码：它如何封装区块数据、属性和内容。

各位同学，晚上好！今天咱们来聊聊 WordPress 的一个核心概念，也是现代 WordPress 开发的基石：WP_Block 类。这玩意儿可不是砖头，而是 WordPress 用来封装区块数据、属性和内容的“容器”。用好了它，你会感觉写代码像搭积木一样轻松愉快。

一、啥是 WP_Block？为什么要用它？

想象一下，你写一个复杂的 WordPress 页面，里面有标题、段落、图片、按钮、自定义的图文混排…… 如果把这些元素都当成一大坨 HTML 代码塞进去，代码会变得臃肿不堪，难以维护。

WP_Block 就像一个乐高积木块，把这些元素拆解成一个个独立的、可复用的组件。每个 WP_Block 对象都包含了这个区块的所有信息：

• blockName: 区块的名称，比如 'core/paragraph' 或 'my-plugin/fancy-button'。
• attrs: 区块的属性，比如段落的字体大小、按钮的颜色等。这些属性定义了区块的行为和外观。
• innerBlocks: 嵌套的子区块，比如一个列区块里面可以包含多个文本区块和图片区块。
• innerHTML: 渲染后的 HTML 内容，或者说，区块最终呈现给用户的样子。
• innerContent: 一个数组，包含了区块内容的占位符和动态值，用于动态渲染。

使用 WP_Block 的好处显而易见：

• 代码结构更清晰: 将页面分解成一个个独立的区块，易于理解和维护。
• 可复用性高: 相同的区块可以在不同的页面中重复使用。
• 易于扩展: 可以自定义区块，添加新的功能和样式。
• 更安全: WordPress 会自动处理区块属性的转义，防止 XSS 攻击。

二、WP_Block 类的源码剖析

咱们直接上代码，深入 WP_Block 的内部，看看它到底是怎么运作的。

<?php

/**
 * Core class used to implement the concept of blocks.
 *
 * @since 5.0.0
 */
final class WP_Block {

    /**
     * Block name including namespace.
     *
     * @since 5.0.0
     * @access public
     * @var string
     */
    public $blockName;

    /**
     * Block attributes.
     *
     * @since 5.0.0
     * @access public
     * @var array
     */
    public $attrs;

    /**
     * List of inner blocks.
     *
     * @since 5.0.0
     * @access public
     * @var WP_Block[]
     */
    public $innerBlocks;

    /**
     * Raw HTML content of block.
     *
     * @since 5.0.0
     * @access public
     * @var string
     */
    public $innerHTML;

    /**
     * List of inner content placeholders and dynamic values.
     *
     * @since 5.0.0
     * @access public
     * @var array
     */
    public $innerContent;

    /**
     * Constructor.
     *
     * @since 5.0.0
     * @access public
     *
     * @param string    $block_name   Block name including namespace.
     * @param array     $attrs        Block attributes.
     * @param WP_Block[] $inner_blocks List of inner blocks.
     * @param string    $innerHTML    Raw HTML content of block.
     * @param array     $innerContent List of inner content placeholders and dynamic values.
     */
    public function __construct( $block_name, array $attrs = array(), array $inner_blocks = array(), $innerHTML = '', array $innerContent = array() ) {
        $this->blockName  = $block_name;
        $this->attrs        = $attrs;
        $this->innerBlocks  = $inner_blocks;
        $this->innerHTML    = $innerHTML;
        $this->innerContent = $innerContent;
    }
}

代码很简单，就是一个 final 类，意味着不能被继承。里面定义了几个公共属性，对应了我们前面说的区块的各个组成部分。构造函数也很直白，就是用来初始化这些属性的。

关键点：

• final class WP_Block: final 关键字确保了 WP_Block 类不能被继承。这是为了保证区块结构的稳定性和一致性。
• 公共属性: $blockName, $attrs, $innerBlocks, $innerHTML, $innerContent 这些属性都是 public 的，意味着可以在类的外部直接访问和修改它们。 虽然可以直接访问，但通常不建议直接修改，而是应该通过 WordPress 提供的 API 来操作区块数据。
• 构造函数: __construct() 方法用于创建 WP_Block 对象。 你需要传入区块的名称、属性、子区块、HTML 内容和内部内容数组。

三、WP_Block 对象从哪里来？

WP_Block 对象通常不是你直接 new WP_Block() 创建的。 它们通常是由 WordPress 的区块解析器自动生成的。

WordPress 使用 parse_blocks() 函数来解析文章内容中的区块代码。 这个函数会将文章内容分解成一个个 WP_Block 对象，形成一个区块树。

$post_content = get_post_field( 'post_content', get_the_ID() );
$blocks = parse_blocks( $post_content );

if ( ! empty( $blocks ) ) {
    foreach ( $blocks as $block ) {
        // $block 现在是一个 WP_Block 对象
        echo '<pre>';
        print_r( $block );
        echo '</pre>';
    }
}

这段代码会获取当前文章的内容，然后使用 parse_blocks() 函数将其解析成一个 WP_Block 对象数组。 你可以通过 print_r() 函数来查看每个 WP_Block 对象的内容。

四、如何访问和操作 WP_Block 对象的属性？

一旦你有了 WP_Block 对象，就可以访问和操作它的属性了。

$post_content = get_post_field( 'post_content', get_the_ID() );
$blocks = parse_blocks( $post_content );

if ( ! empty( $blocks ) ) {
    foreach ( $blocks as $block ) {
        // 获取区块名称
        $block_name = $block->blockName;
        echo '区块名称: ' . $block_name . '<br>';

        // 获取区块属性
        $block_attributes = $block->attrs;
        echo '区块属性: <pre>';
        print_r( $block_attributes );
        echo '</pre>';

        // 获取子区块
        $inner_blocks = $block->innerBlocks;
        echo '子区块: <pre>';
        print_r( $inner_blocks );
        echo '</pre>';

        // 获取 HTML 内容
        $inner_html = $block->innerHTML;
        echo 'HTML 内容: ' . $inner_html . '<br>';

        // 获取内部内容
        $inner_content = $block->innerContent;
        echo '内部内容: <pre>';
        print_r( $inner_content );
        echo '</pre>';

        //判断是否是核心段落区块,并修改段落颜色
        if($block_name === 'core/paragraph'){
            // 假设 'color' 是段落区块的一个自定义属性
            if ( isset( $block_attributes['style']['color']['text'] ) ) {
                echo "原始颜色： " . $block_attributes['style']['color']['text'] . "<br>";
                $block->attrs['style']['color']['text'] = 'red';//修改颜色
                echo "修改后的颜色： " . $block->attrs['style']['color']['text'] . "<br>";
            }else{
                echo "段落没有设置颜色属性n";
            }
        }

        echo '<hr>';
    }
}

这段代码演示了如何访问 WP_Block 对象的各个属性。 你可以根据需要修改这些属性。 注意，直接修改 WP_Block 对象的属性可能不会生效，因为 WordPress 可能会缓存区块数据。 更推荐的方式是使用 render_block 过滤器来修改区块的渲染结果（后面会讲到）。

五、深入理解 innerContent

innerContent 是一个比较特殊的属性，它是一个数组，包含了区块内容的占位符和动态值。 它的结构比较复杂，需要深入理解。

例如，对于一个包含文本和链接的区块，innerContent 可能是这样的：

array(
    0 => '<p>',
    1 => '这是一个',
    2 => '<a href="%1$s">链接</a>',
    3 => '。</p>',
)

其中，%1$s 是一个占位符，表示链接的 URL。 动态值会存储在 attrs 属性中。

innerContent 的主要作用是支持动态区块的渲染。 动态区块是指那些内容不是静态的，而是根据某些条件动态生成的区块。

六、使用 render_block 过滤器修改区块渲染

render_block 过滤器允许你在区块渲染之前修改区块的数据或 HTML 内容。 这是修改区块渲染最安全、最推荐的方式。

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

function my_custom_render_block( $block_content, $block ) {
    // 修改核心段落区块的渲染结果
    if ( $block['blockName'] === 'core/paragraph' ) {
        // 获取段落的文本内容
        $text = strip_tags( $block_content );

        // 在文本内容前后添加一些文字
        $block_content = '<div>Customized: ' . $text . '</div>';
    }

    return $block_content;
}

这段代码会在渲染 core/paragraph 区块之前，获取段落的文本内容，并在文本内容前后添加一些文字。

参数解释:

• $block_content: 区块渲染后的 HTML 内容。
• $block: 一个包含了区块数据的数组，类似于 WP_Block 对象，但不是一个对象，而是一个数组。

重要提示:

• 不要直接修改 $block 数组。 虽然 $block 数组看起来像 WP_Block 对象的属性，但直接修改它可能不会生效，或者导致不可预测的错误。 你应该使用 $block 数组中的数据来生成新的 HTML 内容，并将其赋值给 $block_content 变量。
• 注意优先级。 add_filter() 函数的第三个参数是优先级。 优先级越低，过滤器执行的越早。 你需要根据需要调整优先级，确保你的过滤器在其他过滤器之前或之后执行。

七、自定义区块与 WP_Block

当你创建自定义区块时，你需要注册区块类型，并定义区块的属性和渲染函数。

// 注册自定义区块
register_block_type( 'my-plugin/fancy-button', array(
    'attributes' => array(
        'buttonText' => array(
            'type' => 'string',
            'default' => 'Click Here',
        ),
        'buttonColor' => array(
            'type' => 'string',
            'default' => 'blue',
        ),
    ),
    'render_callback' => 'my_fancy_button_render_callback',
) );

// 定义渲染函数
function my_fancy_button_render_callback( $attributes ) {
    $button_text = $attributes['buttonText'];
    $button_color = $attributes['buttonColor'];

    $html = '<button style="background-color: ' . esc_attr( $button_color ) . '">' . esc_html( $button_text ) . '</button>';

    return $html;
}

这段代码注册了一个名为 my-plugin/fancy-button 的自定义区块。 它定义了两个属性：buttonText 和 buttonColor。 render_callback 函数负责渲染区块的 HTML 内容。

当 WordPress 渲染这个区块时，它会自动创建一个 WP_Block 对象，并将区块的名称和属性传递给 render_callback 函数。 你可以在 render_callback 函数中使用这些信息来生成区块的 HTML 内容。

八、表格总结 WP_Block 常用属性和方法

属性/方法	类型	描述
$blockName	string	区块的名称，包含命名空间，例如 'core/paragraph'。
$attrs	array	区块的属性，一个关联数组，包含了区块的所有属性和它们的值。
$innerBlocks	array	子区块的数组，每个元素都是一个 WP_Block 对象。
$innerHTML	string	区块的 HTML 内容。
$innerContent	array	一个数组，包含了区块内容的占位符和动态值。用于动态区块。
__construct()	方法	WP_Block 类的构造函数，用于创建 WP_Block 对象。
parse_blocks()	函数	WordPress 内置函数，用于解析文章内容中的区块代码，返回一个 WP_Block 对象数组。
register_block_type()	函数	WordPress 内置函数，用于注册自定义区块类型。
render_block 过滤器	过滤器	WordPress 过滤器，允许你在区块渲染之前修改区块的数据或 HTML 内容。

九、注意事项和最佳实践

• 使用 render_block 过滤器来修改区块的渲染结果。 这是修改区块渲染最安全、最推荐的方式。
• 不要直接修改 WP_Block 对象的属性。 这样做可能不会生效，或者导致不可预测的错误。
• 注意转义输出。 在渲染区块的 HTML 内容时，一定要使用 esc_html() 和 esc_attr() 函数来转义输出，防止 XSS 攻击。
• 合理使用 innerContent。 innerContent 适用于动态区块，对于静态区块，可以直接使用 $innerHTML 属性。
• 避免过度嵌套区块。 过多的嵌套会影响页面的性能和可维护性。

十、总结

WP_Block 类是 WordPress 区块系统的核心。 理解 WP_Block 类的结构和运作方式，可以帮助你更好地理解 WordPress 的区块系统，并编写更高效、更可维护的 WordPress 代码。 希望今天的讲解对你有所帮助！ 下课！