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

各位观众老爷，晚上好！今儿咱们唠唠 WordPress 里一个相当关键，又有点儿神秘的家伙——the_content 过滤器在古登堡（Gutenberg）编辑器里的实现。这玩意儿就像个魔术师，能把你在后台编辑器里拖来拽去的那些花花绿绿的区块，变成最终呈现在用户面前的 HTML 代码。

准备好，咱们这就开始揭秘！

一、the_content：老朋友，新任务

the_content 过滤器在 WordPress 已经存在很久了，早在古登堡出现之前，它就负责在文章内容显示之前对内容进行处理。比如，你可以用它来实现自动链接、表情符号转换等等。

但古登堡横空出世之后，the_content 的任务就变得更加复杂了。它不仅要处理传统的文本内容，还要处理那些由区块组成的复杂结构。简单来说，它要负责把区块对象翻译成最终的 HTML。

二、区块是什么？

在深入 the_content 之前，咱们得先搞清楚“区块”到底是个什么玩意儿。你可以把区块想象成一个个独立的、可重复使用的内容单元。比如，一个段落、一张图片、一个标题、一个按钮，甚至一个嵌入的 YouTube 视频，都可以是一个区块。

每个区块都有自己的属性，这些属性定义了区块的内容和样式。比如，一个段落区块可能包含 content 属性（段落文本）和 align 属性（对齐方式）。

这些区块的信息都以特定的格式存储在数据库里。在 WordPress 5.0 之后，默认的存储格式是“块语法”（Block Syntax），它看起来有点像这样：

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

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

看到没？每个区块都用  和  包裹起来，中间是区块的内容和属性。

三、the_content 的工作流程：化腐朽为神奇

现在，我们来看看 the_content 过滤器是如何将这些区块语法转换成最终的 HTML 的。简单来说，它主要做了以下几件事：

读取文章内容： 首先，the_content 过滤器会获取文章的原始内容，也就是包含块语法的字符串。
解析区块： 接下来，它会使用 WordPress 内置的函数（比如 parse_blocks()）来解析这些块语法，将它们转换成一个 PHP 对象数组。每个对象代表一个区块，包含了区块的名称、属性和子区块等信息。
渲染区块： 这是最关键的一步。对于每个区块，the_content 过滤器会找到对应的渲染函数（通常是区块的 render_callback），然后调用这个函数来生成区块的 HTML。
拼接 HTML： 最后，the_content 过滤器会将所有区块的 HTML 片段拼接起来，形成最终的文章内容，并返回给浏览器。

四、源码解析：深入了解 the_content 的魔术

咱们现在就来扒一扒 WordPress 的源码，看看 the_content 过滤器到底是怎么实现的。

核心的逻辑位于 wp-includes/default-filters.php 文件中。你可以找到类似这样的代码：

add_filter( 'the_content', 'wpautop' );
add_filter( 'the_content', 'do_blocks', 9 );
add_filter( 'the_content', 'wptexturize' );
add_filter( 'the_content', 'convert_smilies', 20 );
add_filter( 'the_content', 'convert_chars' );
add_filter( 'the_content', 'wp_smartypants' );
add_filter( 'the_content', 'shortcode_unautop' );
add_filter( 'the_content', 'prepend_attachment' );
add_filter( 'the_content', 'wp_kses_post' );

这里，the_content 过滤器被添加了一堆函数，这些函数按照顺序依次对文章内容进行处理。其中，do_blocks 函数就是负责处理区块的关键。

让我们深入 do_blocks 函数，看看它是如何工作的。do_blocks 函数的定义位于 wp-includes/blocks.php 文件中。它的主要逻辑如下：

function do_blocks( $content ) {
    if ( ! has_blocks( $content ) ) {
        return $content;
    }

    $blocks = parse_blocks( $content );

    if ( empty( $blocks ) ) {
        return '';
    }

    $output = '';

    foreach ( $blocks as $block ) {
        $output .= render_block( $block );
    }

    return $output;
}

这个函数做了以下几件事：

检查是否有区块： 首先，它使用 has_blocks() 函数检查文章内容是否包含块语法。如果没有，就直接返回原始内容，不做任何处理。
解析区块： 如果文章内容包含块语法，它就使用 parse_blocks() 函数将块语法解析成一个 PHP 对象数组。
渲染区块： 然后，它遍历这个数组，对每个区块调用 render_block() 函数来生成 HTML。
拼接 HTML： 最后，它将所有区块的 HTML 片段拼接起来，形成最终的文章内容。

parse_blocks() 函数的源码比较复杂，它负责解析块语法，并将每个区块的信息提取出来，存储在一个 PHP 对象中。你可以自行阅读 wp-includes/blocks.php 文件中的源码，了解它的具体实现。

render_block() 函数是另一个关键函数，它负责根据区块的类型调用相应的渲染函数。它的源码如下：

function render_block( $block ) {
    $block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );

    if ( ! $block_type ) {
        return '';
    }

    if ( ! empty( $block_type->render_callback ) && is_callable( $block_type->render_callback ) ) {
        $content = call_user_func( $block_type->render_callback, $block['attrs'], $block['content'] );
    } else {
        $content = '';
    }

    return $content;
}

这个函数做了以下几件事：

获取区块类型： 首先，它根据区块的名称（blockName）从 WP_Block_Type_Registry 中获取区块类型对象。WP_Block_Type_Registry 是一个注册表，存储了所有已注册的区块类型的信息。
检查渲染回调函数： 然后，它检查区块类型对象是否定义了 render_callback 属性，以及这个属性是否是一个可调用的函数。render_callback 属性指定了用于渲染区块的函数。
调用渲染回调函数： 如果区块类型定义了 render_callback 属性，并且这个属性是一个可调用的函数，它就使用 call_user_func() 函数调用这个函数，并将区块的属性（attrs）和内容（content）作为参数传递给它。
返回 HTML： 最后，它返回渲染函数生成的 HTML。

五、自定义区块的渲染：我的地盘我做主

如果你想自定义区块的渲染方式，你可以通过注册自己的区块类型，并指定自己的 render_callback 函数来实现。

例如，假设你想创建一个名为 my-plugin/custom-paragraph 的自定义段落区块，你可以这样做：

注册区块类型： 使用 register_block_type() 函数注册区块类型。

function my_plugin_register_block() {
    register_block_type( 'my-plugin/custom-paragraph', array(
        'attributes'      => array(
            'content' => array(
                'type'    => 'string',
                'default' => '',
            ),
            'alignment' => array(
                'type'    => 'string',
                'default' => 'left',
            ),
        ),
        'render_callback' => 'my_plugin_render_custom_paragraph',
    ) );
}
add_action( 'init', 'my_plugin_register_block' );

在这个例子中，我们定义了两个属性：content（段落文本）和 alignment（对齐方式）。我们还指定了 my_plugin_render_custom_paragraph 函数作为渲染回调函数。

定义渲染回调函数： 定义 my_plugin_render_custom_paragraph 函数，用于生成区块的 HTML。

function my_plugin_render_custom_paragraph( $attributes, $content ) {
    $alignment = isset( $attributes['alignment'] ) ? $attributes['alignment'] : 'left';
    $paragraph_content = isset( $attributes['content'] ) ? $attributes['content'] : '';

    $html = '<p style="text-align: ' . esc_attr( $alignment ) . ';">' . esc_html( $paragraph_content ) . '</p>';

    return $html;
}

在这个例子中，我们根据 alignment 属性设置段落的对齐方式，然后将段落文本包裹在 <p> 标签中，并返回 HTML。

通过这种方式，你可以完全控制自定义区块的渲染方式，实现各种各样的效果。

六、表格总结：the_content 过滤器与区块渲染

为了更好地理解 the_content 过滤器与区块渲染的关系，我们用一个表格来总结一下：

步骤	函数/过程	描述
1. 获取文章内容	`get_the_content()`	获取包含块语法的文章内容。
2. 应用 `the_content` 过滤器	`apply_filters( 'the_content', $content )`	将文章内容传递给 `the_content` 过滤器，由一系列函数进行处理。
3. 检查是否有区块	`has_blocks( $content )`	检查文章内容是否包含块语法。
4. 解析区块	`parse_blocks( $content )`	将块语法解析成 PHP 对象数组，每个对象代表一个区块，包含区块的名称、属性和子区块等信息。
5. 渲染区块	`render_block( $block )`	根据区块的类型调用相应的渲染函数（通常是区块的 `render_callback`），生成区块的 HTML。
6. 拼接 HTML	(循环拼接)	将所有区块的 HTML 片段拼接起来，形成最终的文章内容。
7. 返回 HTML	(函数返回)	将最终的文章内容返回给浏览器。

七、总结：the_content，古登堡的幕后英雄

the_content 过滤器在古登堡编辑器中扮演着至关重要的角色。它负责将你在后台编辑器里拖来拽去的那些区块，转换成最终呈现在用户面前的 HTML 代码。

理解 the_content 过滤器的工作原理，可以帮助你更好地理解古登堡编辑器的工作方式，也可以让你更好地自定义区块的渲染方式，实现各种各样的效果。

希望今天的讲解对你有所帮助。咱们下回再见！

发表回复 取消回复

发表回复取消回复