WordPress给古腾堡编辑器添加自定义模块

古腾堡编辑器很多站长都表示用不习惯，但是我个人还是挺喜欢用这个编辑器的。比起之前那个默认的输入框，古腾堡编辑器实用多了。

关于古腾堡编辑器，官方之前给了一个初步的文档，但是那个文档是以插件化为教程进行的。对于主题设计者而言，更希望在自己的主题里直接加入古腾堡自定义模块比较方便，因此本文的方向是在主题里直接往古腾堡编辑器里插入自定义模块。

今天我们来了解下如何给古腾堡编辑器添加自定义模块。

加载古腾堡自定义模块

首先，需要在主题的 functions.php 文件中注册并加载自定义模块的脚本。

// 加载古腾堡自定义模块
function my_gutenberg_block() {
    // 注册古腾堡编辑器脚本
    wp_register_script(
        'block-js',
        get_template_directory_uri() . '/extends/src/blocks.js',
        array('wp-blocks', 'wp-element', 'wp-editor', 'wp-i18n'),
        '1.0.0'
    );
    // 注册区块类型
    // 'fishtheme/block' 是区块的唯一标识符，可自定义，例如: 'demo/block'
    register_block_type( 'fishtheme/block', array(
        'editor_script' => 'block-js'
    ) );
}
add_action( 'init', 'my_gutenberg_block' );

新建 blocks.js

在您当前使用的 WordPress 主题目录下，新建一个 src 的文件夹，并在其中创建 blocks.js 文件。

注意： blocks.js 的文件路径可以自定义，但请确保与上面 wp_register_script 函数中指定的路径一致。

编辑 blocks.js

这是定义古腾堡自定义模块功能的核心文件。

(function (blocks, element, editor, i18n) {
    var el = element.createElement; // 用于创建 React 元素
    var RichText = editor.RichText; // 用于获取富文本输入组件

    // 注册一个新的区块类型
    blocks.registerBlockType('gutenberg-examples/example-03-editable', {
        title: '测试模块', // 区块在编辑器中的显示名称
        icon: 'universal-access-alt', // 区块图标（来自 Dashicons）
        category: 'layout', // 区块所属的分类（如 layout, common, formatting 等）
        attributes: { // 定义区块的属性
            content: {
                type: 'array',
                source: 'children',
                selector: 'p',
            },
        },
        // 定义区块在编辑器中的编辑界面
        edit: function (props) {
            var content = props.attributes.content;
            function onChangeContent(newContent) {
                props.setAttributes({ content: newContent });
            }
            // 返回编辑器的 UI 结构
            return el(
                RichText,
                {
                    tagName: 'p',
                    className: props.className,
                    onChange: onChangeContent,
                    value: content,
                }
            );
        },
        // 定义区块在前端保存时的输出结构
        save: function (props) {
            return el(RichText.Content, {
                tagName: 'p',
                value: props.attributes.content,
            });
        },
    });
}(
    window.wp.blocks,
    window.wp.element,
    window.wp.editor,
    window.wp.i18n
));

代码说明：

• registerBlockType 用于注册一个新模块，其第一个参数是模块的唯一标识符（命名空间/名称）。
• edit 函数定义了模块在古腾堡编辑器中的编辑界面和行为。
• save 函数定义了模块内容如何被保存并输出到前端页面。
• 函数顶部引入的 blocks, element, editor, i18n 必须与 functions.php 中 wp_register_script 的依赖数组一一对应。

查看效果

完成以上步骤后，清空浏览器缓存并刷新 WordPress 文章编辑页面。在古腾堡编辑器中点击“添加区块”（+ 按钮），您应该在“布局元素”或其他相应分类下找到名为“测试模块”的新区块。

本文示例基于官方提供的简单 Demo。如需开发更复杂的自定义模块（例如包含多个字段、动态内容或复杂样式的模块），建议深入学习 Block Editor Handbook。