解析 WordPress `add_action(‘render_block’, …)` 钩子的源码：如何修改或包装区块的渲染输出。

各位观众老爷，大家好！今天咱们聊聊 WordPress 里一个非常强大的钩子：add_action('render_block', ...)。这玩意儿就像一个万能的装修工，能让你在 WordPress 区块渲染出来之前，给它动动刀子，改改面貌，甚至直接给它换个新家。准备好了吗？咱们开始！

一、什么是 render_block 钩子？

简单来说，render_block 钩子允许你拦截并修改 WordPress 区块的最终 HTML 输出。每次 WordPress 渲染一个区块时，它都会触发这个钩子。你可以编写一个函数，挂载到这个钩子上，这个函数就能接收到区块的数据，并返回修改后的 HTML。

就像一个流水线，所有的区块都要经过这个钩子，你想对哪个区块下手，就对哪个区块下手，简直是为所欲为！ (当然，要小心操作，不然容易出问题)

二、 render_block 钩子的参数

挂载到 render_block 钩子的函数通常接收三个参数：

参数	类型	描述
$block_content	string	区块的原始 HTML 输出。这是 WordPress 默认生成的 HTML，你可以在这里进行修改。
$block	array	包含区块所有属性信息的数组。包括区块的名称、属性值、以及其他元数据。这个数组非常重要，因为你可以根据区块的属性来决定是否修改其输出。
$instance	WP_Block	WP_Block 对象，提供了一系列操作区块的方法。比如，你可以通过它来获取区块的属性值，检查区块是否是动态区块等等。

三、 使用 render_block 钩子的基本姿势

首先，你需要创建一个函数，这个函数就是你的“装修工”。然后，使用 add_action() 函数把你的“装修工”挂载到 render_block 钩子上。

<?php
/**
 * 修改区块输出的函数
 *
 * @param string   $block_content 区块的原始 HTML 输出.
 * @param array    $block       包含区块所有属性信息的数组.
 * @param WP_Block $instance    WP_Block 对象.
 *
 * @return string 修改后的 HTML 输出.
 */
function my_custom_render_block( $block_content, $block, $instance ) {
  // 在这里写你的修改逻辑
  return $block_content; // 默认返回原始输出，如果没做修改
}

add_action( 'render_block', 'my_custom_render_block', 10, 3 );

这段代码只是一个框架，my_custom_render_block 函数里面什么都没做。你需要根据你的需求，往里面添加修改逻辑。

四、 实战演练：修改区块输出

现在，咱们来几个实际的例子，看看怎么用 render_block 钩子来修改区块的输出。

1. 给所有段落区块添加一个 class

<?php
/**
 * 给所有段落区块添加一个 class
 *
 * @param string   $block_content 区块的原始 HTML 输出.
 * @param array    $block       包含区块所有属性信息的数组.
 * @param WP_Block $instance    WP_Block 对象.
 *
 * @return string 修改后的 HTML 输出.
 */
function my_add_class_to_paragraph( $block_content, $block, $instance ) {
  if ( 'core/paragraph' === $block['blockName'] ) {
    $block_content = str_replace( '<p', '<p class="my-custom-paragraph-class"', $block_content );
  }
  return $block_content;
}

add_action( 'render_block', 'my_add_class_to_paragraph', 10, 3 );

这段代码会给所有段落区块的 <p> 标签添加一个 my-custom-paragraph-class 类。看起来很简单，但非常实用，可以让你方便地给特定类型的区块添加样式。

2. 修改图像区块的 alt 属性

<?php
/**
 * 修改图像区块的 alt 属性
 *
 * @param string   $block_content 区块的原始 HTML 输出.
 * @param array    $block       包含区块所有属性信息的数组.
 * @param WP_Block $instance    WP_Block 对象.
 *
 * @return string 修改后的 HTML 输出.
 */
function my_modify_image_alt_attribute( $block_content, $block, $instance ) {
  if ( 'core/image' === $block['blockName'] && isset( $block['attrs']['alt'] ) ) {
    $original_alt = $block['attrs']['alt'];
    $new_alt = 'Image: ' . $original_alt;
    $block_content = str_replace( 'alt="' . esc_attr( $original_alt ) . '"', 'alt="' . esc_attr( $new_alt ) . '"', $block_content );
  }
  return $block_content;
}

add_action( 'render_block', 'my_modify_image_alt_attribute', 10, 3 );

这段代码会给所有图像区块的 alt 属性前面加上 "Image: " 前缀。这在 SEO 优化中很有用，可以让你更精确地控制图像的 alt 属性。

3. 包装核心/列表区块

<?php
/**
 * 包装核心/列表区块
 *
 * @param string   $block_content 区块的原始 HTML 输出.
 * @param array    $block       包含区块所有属性信息的数组.
 * @param WP_Block $instance    WP_Block 对象.
 *
 * @return string 修改后的 HTML 输出.
 */
function my_wrap_core_list_block( $block_content, $block, $instance ) {
    if ( 'core/list' === $block['blockName'] ) {
        $wrapper_start = '<div class="custom-list-wrapper">';
        $wrapper_end   = '</div>';
        $block_content = $wrapper_start . $block_content . $wrapper_end;
    }
    return $block_content;
}

add_action( 'render_block', 'my_wrap_core_list_block', 10, 3 );

这段代码会在核心列表区块的外面包裹一个 div 元素，并添加 custom-list-wrapper 类名。

4. 根据属性值修改区块输出

<?php
/**
 * 根据属性值修改区块输出
 *
 * @param string   $block_content 区块的原始 HTML 输出.
 * @param array    $block       包含区块所有属性信息的数组.
 * @param WP_Block $instance    WP_Block 对象.
 *
 * @return string 修改后的 HTML 输出.
 */
function my_modify_block_output_based_on_attribute( $block_content, $block, $instance ) {
  if ( 'core/heading' === $block['blockName'] && isset( $block['attrs']['level'] ) ) {
    if ( $block['attrs']['level'] === 2 ) {
      $block_content = '<div class="custom-h2-wrapper">' . $block_content . '</div>';
    }
  }
  return $block_content;
}

add_action( 'render_block', 'my_modify_block_output_based_on_attribute', 10, 3 );

这段代码会判断标题区块的 level 属性是否为 2，如果是，则把标题区块包裹在一个 div 元素中，并添加 custom-h2-wrapper 类名。

5. 移除特定区块

有时候，你可能想彻底移除某个区块，不让它显示在页面上。

<?php
/**
 * 移除特定区块
 *
 * @param string   $block_content 区块的原始 HTML 输出.
 * @param array    $block       包含区块所有属性信息的数组.
 * @param WP_Block $instance    WP_Block 对象.
 *
 * @return string 修改后的 HTML 输出.
 */
function my_remove_specific_block( $block_content, $block, $instance ) {
  if ( 'core/comment-template' === $block['blockName'] ) {
    return ''; // 直接返回空字符串，移除区块
  }
  return $block_content;
}

add_action( 'render_block', 'my_remove_specific_block', 10, 3 );

这段代码会移除评论模板区块。直接返回一个空字符串，就可以让区块不显示出来。

五、 使用 WP_Block 对象

$instance 参数是一个 WP_Block 对象，它提供了一些有用的方法来操作区块。

方法	描述
$instance->block_type->name	获取区块的名称，和 $block['blockName'] 一样。
$instance->block_type->attributes	获取区块的所有属性定义。
$instance->attributes	获取区块的属性值，和 $block['attrs'] 一样。
$instance->is_dynamic()	检查区块是否是动态区块。动态区块是服务器端渲染的区块，它的 HTML 内容是在服务器端动态生成的。
$instance->render()	渲染区块。通常情况下你不需要手动调用这个方法，因为 WordPress 会自动渲染区块。但如果你想重新渲染区块，或者在修改了区块的属性之后重新渲染，可以使用这个方法。

虽然$instance对象有很多方法，但是最常用的还是$instance->block_type->name和$instance->attributes，它们分别对应于$block['blockName']和$block['attrs']。

六、 注意事项

• 性能问题： render_block 钩子会在每个区块渲染时都触发，所以你的函数需要尽可能高效，避免影响页面加载速度。尽量减少字符串操作，使用缓存等技术来优化性能。

• 优先级： add_action() 函数的第三个参数是优先级。默认优先级是 10。如果多个函数挂载到同一个钩子上，优先级越低的函数越先执行。

• 区块嵌套： render_block 钩子也会被嵌套的区块触发。你需要小心处理嵌套区块的情况，避免出现无限循环或者其他问题。

• 动态区块： 动态区块的内容是在服务器端动态生成的，所以你不能直接修改动态区块的 HTML 输出。你需要修改动态区块的渲染逻辑，才能改变它的内容。

• 兼容性： 不同的主题和插件可能会修改区块的输出。你需要测试你的代码在各种情况下都能正常工作，避免出现兼容性问题。

七、 总结

render_block 钩子是一个非常强大的工具，可以让你灵活地修改 WordPress 区块的输出。你可以根据区块的类型、属性值，以及其他条件，来定制区块的显示方式。只要你掌握了它的用法，就能创造出各种各样的效果，让你的 WordPress 网站更加个性化。

希望今天的讲座对大家有所帮助！下次再见！