解析 WordPress `the_content` 过滤器在 Gutenberg 中的源码：如何将区块数据转换为 HTML。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，晚上好！今天咱们来聊聊 WordPress 的 the_content 过滤器，特别是它在古腾堡（Gutenberg）编辑器里头，是怎么把那些花里胡哨的区块数据，变成能在浏览器里展示的 HTML 的。这可不是个简单的活儿，里头藏着不少门道呢！

开场白：the_content 是个老司机

在 WordPress 的世界里，the_content 过滤器绝对是个老司机了。它可以让你在文章内容输出之前，对内容进行各种各样的操作，比如加广告、改格式、甚至直接换成别的什么东西。

add_filter( 'the_content', 'my_custom_content_filter' );

function my_custom_content_filter( $content ) {
  // 这里写你的代码，修改 $content 变量
  $content = '<div>' . $content . '</div>'; // 举个例子，加个 div 包裹
  return $content;
}

这段代码很简单吧？但它的威力可不小。问题来了，以前的文章内容都是 HTML，直接改就行。现在有了古腾堡，文章内容变成了区块数据，这可怎么改？总不能手动解析 JSON 吧？

古腾堡的区块：数据化的内容

古腾堡把文章内容拆成了一个个的“区块”，每个区块都有自己的数据结构，通常是 JSON 格式的。这些数据描述了区块的类型、属性、以及它应该如何展示。

举个例子，一个简单的段落区块可能是这样子的：

{
  "blockName": "core/paragraph",
  "attrs": {
    "content": "这是一个段落。"
  },
  "innerBlocks": [],
  "innerHTML": "n<p>这是一个段落。</p>n",
  "innerContent": [
    "n<p>这是一个段落。</p>n"
  ]
}

blockName 告诉我们这是个段落区块，attrs 里头放着它的属性，比如 content 就是段落的内容。 innerHTML 和 innerContent 是渲染后的HTML，它们会被用来替换原有的标记。（注意：innerHTML 和 innerContent 在早期版本中可能不存在，或者结构不同，这里是为了方便讲解做了简化）。

那么问题来了，the_content 过滤器接收到的 content 参数，到底是什么？是 JSON 字符串？还是已经解析好的区块数据？

the_content 过滤器：迎来新的挑战

实际上，the_content 过滤器接收到的 content 参数，仍然是一个字符串。只不过，这个字符串不再是纯粹的 HTML 了，而是包含了区块标记的特殊字符串。

这个字符串看起来是这样的：

<!-- wp:paragraph -->
<p>这是一个段落。</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":123,"sizeSlug":"large"} -->
<figure class="wp-block-image size-large"><img src="image.jpg" alt="" class="wp-image-123"/></figure>
<!-- /wp:image -->

看到了吗？每个区块都用  和  包裹起来。中间是这个区块对应的 HTML。

WordPress 的应对：do_blocks() 函数

WordPress 提供了一个函数 do_blocks()，专门用来解析这种包含区块标记的字符串，并把它转换成最终的 HTML。

$content = do_blocks( $content );

这行代码就是古腾堡的核心秘密之一。do_blocks() 函数会遍历 content 字符串，找到所有的区块标记，然后根据区块的类型和属性，生成对应的 HTML。

do_blocks() 的内部机制：庖丁解牛

do_blocks() 函数的内部实现比较复杂，大致可以分为以下几个步骤：

识别区块标记： 使用正则表达式，找到所有的  和 。
解析区块属性： 从区块标记中提取区块的名称和属性。
渲染区块： 根据区块的名称，找到对应的渲染函数，把属性传递给渲染函数，生成 HTML。
替换原始标记： 把原始的区块标记替换成生成的 HTML。

区块渲染：render_block() 函数

每个区块都有一个对应的渲染函数，负责把区块的数据转换成 HTML。这些渲染函数通常定义在区块的注册代码里。

register_block_type(
  'core/paragraph',
  array(
    'render_callback' => 'render_block_core_paragraph',
  )
);

function render_block_core_paragraph( $attributes, $content ) {
  $text = isset( $attributes['content'] ) ? $attributes['content'] : '';
  return '<p>' . $text . '</p>';
}

render_callback 指定了渲染函数的名字。渲染函数接收两个参数：$attributes 是区块的属性，$content 是区块的内部 HTML（如果有的话）。

自定义区块：打造自己的积木

古腾堡的强大之处在于，你可以自定义区块，打造自己的积木。自定义区块需要做以下几件事：

注册区块： 使用 register_block_type() 函数注册你的区块。
定义编辑界面： 使用 JavaScript 和 React 定义区块在编辑器里的样子。
定义渲染函数： 使用 PHP 定义区块在前台展示的样子。

实际案例：修改段落区块的样式

假设你想给所有的段落区块加上一个 my-paragraph 的 CSS 类，你可以这样做：

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

function my_custom_paragraph_class( $block_content, $block ) {
  if ( $block['blockName'] === 'core/paragraph' ) {
    $block_content = str_replace( '<p>', '<p class="my-paragraph">', $block_content );
  }
  return $block_content;
}

这段代码使用了 render_block 过滤器，这个过滤器会在每个区块渲染之后执行。它检查区块的名称是不是 core/paragraph，如果是，就给 <p> 标签加上 my-paragraph 类。

更优雅的方式：使用 block_core_paragraph_render_block 过滤器

实际上，WordPress 提供了一个更优雅的方式来修改特定区块的渲染结果：使用 block_{区块名}_render_block 过滤器。

add_filter( 'block_core_paragraph_render_block', 'my_custom_paragraph_class', 10, 2 );

function my_custom_paragraph_class( $block_content, $block ) {
  $block_content = str_replace( '<p>', '<p class="my-paragraph">', $block_content );
  return $block_content;
}

这段代码和上面的代码效果一样，但是更加简洁明了。

总结：the_content 的新用法

在古腾堡时代，the_content 过滤器仍然非常重要。你可以使用它来：

添加全局性的内容，比如广告、版权信息。
修改特定区块的渲染结果。
对整个文章的内容进行一些全局性的处理。

实用技巧与最佳实践

谨慎修改核心区块： 尽量不要直接修改核心区块的渲染结果，因为这可能会导致不可预测的问题。最好是自定义区块，或者使用 CSS 来修改样式。
使用 block_{区块名}_render_block 过滤器： 修改特定区块的渲染结果时，优先使用 block_{区块名}_render_block 过滤器，而不是 render_block 过滤器。
缓存渲染结果： 如果你的渲染函数比较耗时，可以考虑缓存渲染结果，提高网站的性能。
注意兼容性： 确保你的代码在不同的 WordPress 版本和主题下都能正常工作。

代码示例汇总

功能	代码示例
使用 `the_content` 添加全局内容	`php<br>add_filter( 'the_content', 'my_custom_content_filter' );<br><br>function my_custom_content_filter( $content ) {<br> $content = '<div class="my-global-content">' . $content . '</div>';<br> return $content;<br>}<br>`
使用 `render_block` 修改段落样式	`php<br>add_filter( 'render_block', 'my_custom_paragraph_class', 10, 2 );<br><br>function my_custom_paragraph_class( $block_content, $block ) {<br> if ( $block['blockName'] === 'core/paragraph' ) {<br> $block_content = str_replace( '<p>', '<p class="my-paragraph">', $block_content );<br> }<br> return $block_content;<br>}<br>`
使用 `block_core_paragraph_render_block` 修改段落样式	`php<br>add_filter( 'block_core_paragraph_render_block', 'my_custom_paragraph_class', 10, 2 );<br><br>function my_custom_paragraph_class( $block_content, $block ) {<br> $block_content = str_replace( '<p>', '<p class="my-paragraph">', $block_content );<br> return $block_content;<br>}<br>`

高级话题：深入 do_blocks() 的源码

如果你对 do_blocks() 的内部实现感兴趣，可以去 WordPress 的源码里看看。wp-includes/blocks.php 文件里有 do_blocks() 函数的定义。虽然代码比较复杂，但是如果你理解了它的基本原理，就能更好地掌握古腾堡的工作方式。

总结与展望

古腾堡的出现，给 WordPress 的内容创作带来了革命性的变化。the_content 过滤器也因此焕发了新的生机。掌握 the_content 过滤器在古腾堡中的用法，可以让你更好地控制文章内容的展示，打造更加个性化的网站。

未来的 WordPress，区块将会扮演更加重要的角色。理解区块的工作原理，将会成为 WordPress 开发者的必备技能。

好了，今天的讲座就到这里。希望大家有所收获！下次再见！

发表回复 取消回复

发表回复取消回复