WordPress Gutenberg 编辑器资源加载完全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00711/article/details/148415054

WordPress Gutenberg 编辑器资源加载完全指南

gutenberg The Block Editor project for WordPress and beyond. Plugin is available from the official repository. 项目地址: https://gitcode.com/gh_mirrors/gu/gutenberg

前言

在WordPress Gutenberg编辑器中正确加载资源（脚本和样式）是开发者必须掌握的核心技能。本文将全面解析在Gutenberg编辑器中加载资源的最佳实践，帮助开发者针对不同场景选择最合适的加载方式。

理解Gutenberg编辑器的iframe架构

自WordPress 6.3版本起，当所有注册的区块都使用Block API版本3或更高版本且没有注册传统元框时，文章编辑器会采用iframe架构。站点编辑器则始终采用iframe架构。这种架构变化带来了资源加载方式的调整。

iframe架构的优势

更好的样式隔离
更接近前端渲染效果
减少全局样式冲突

明确加载目标

在加载资源前，必须明确目标对象：

编辑器UI：包括工具栏、侧边栏等界面组件
编辑器内容：用户创建的区块内容

不同的目标需要使用不同的钩子函数。

资源加载场景与实现

1. 编辑器UI资源加载

当需要修改编辑器界面或与编辑器API交互时，应使用enqueue_block_editor_assets钩子配合标准加载函数。

function custom_editor_assets() {
    // 加载编辑器脚本
    wp_enqueue_script(
        'custom-editor-script',
        plugins_url('js/editor.js', __FILE__),
        ['wp-blocks', 'wp-i18n', 'wp-element'],
        filemtime(plugin_dir_path(__FILE__) . 'js/editor.js')
    );
    
    // 加载编辑器样式
    wp_enqueue_style(
        'custom-editor-style',
        plugins_url('css/editor.css', __FILE__)
    );
}
add_action('enqueue_block_editor_assets', 'custom_editor_assets');

适用场景：

添加自定义检查器控件
注册区块样式和变体
开发编辑器插件

2. 编辑器内容资源加载

WordPress 6.3+版本中，通过enqueue_block_assets加载的资源会自动出现在iframe编辑器内。

function custom_content_assets() {
    // 仅在编辑器内加载
    if (is_admin()) {
        wp_enqueue_style(
            'editor-content-style',
            plugins_url('css/content.css', __FILE__)
        );
    }
}
add_action('enqueue_block_assets', 'custom_content_assets');

注意事项：

这些资源同时会在前端加载
使用is_admin()检查可限制仅在编辑器加载

3. 动态修改编辑器设置

通过block_editor_settings_all过滤器可以直接修改编辑器设置，实现更灵活的样式控制。

function modify_editor_settings($settings, $context) {
    $settings['styles'][] = [
        'css' => 'p { color: #1a1a1a; }'
    ];
    return $settings;
}
add_filter('block_editor_settings_all', 'modify_editor_settings', 10, 2);

生成的样式会自动添加.editor-styles-wrapper前缀，确保样式只影响编辑器内容。

区块与主题开发特殊处理

区块开发

使用block.json文件声明区块资源是最佳实践：

{
    "name": "custom/block",
    "editorScript": "file:./build/editor.js",
    "editorStyle": "file:./build/editor.css",
    "style": "file:./build/style.css"
}

这种方式可以：

自动处理依赖关系
按需加载资源
区分编辑器和前端资源

主题开发

主题开发者应优先使用以下方法：

add_editor_style() - 加载编辑器专用样式表
wp_enqueue_block_style() - 加载区块级样式表

// 加载编辑器样式
add_editor_style('assets/css/editor.css');

// 为特定区块加载样式
wp_enqueue_block_style(
    'core/paragraph',
    array(
        'handle' => 'theme-paragraph-style',
        'src'    => get_theme_file_uri('assets/css/blocks/paragraph.css'),
    )
);