2025-10-22 01:40:18 +08:00

7.2 KiB

Raw Blame History

区块脚本与样式

在构建区块时，推荐使用 block.json 来加载区块本身所需的所有脚本和样式。您可以为编辑器、前端或两者同时加载资源。详见区块元数据文档。

主题脚本与样式

若需在主题中加载编辑器JavaScript，可参照上文使用 enqueue_block_assets 或 enqueue_block_editor_assets。编辑器专用样式表应始终通过 add_editor_style() 或 wp_enqueue_block_style() 添加。

wp_enqueue_block_style() 函数支持在编辑器及前端加载逐区块样式表。结合 theme.json 使用，这是样式化区块的最佳方案之一。更多细节请参阅WordPress开发者博客文章运用theme.json与逐区块样式打造高性能主题。

向后兼容性与已知问题

通常而言，在iframe模式编辑器中加载的资源，在WordPress 6.3+版本的非iframe模式下也会同步加载，但反向兼容并不总是成立。

若您开发的插件或主题需兼容6.2及以下版本，同时保持与WordPress 6.3的兼容性，则无法使用 enqueue_block_assets 钩子——因为在6.3之前该钩子不会在iframe编辑器内容中加载资源。

替代方案是使用 enqueue_block_editor_assets，只要加载的样式表包含以下任一选择器：.editor-styles-wrapper、.wp-block 或 .wp-block-*。控制台会显示警告信息，但该钩子仍会将样式应用于编辑器内容。

需特别注意：从WordPress 6.3开始，为保持向后兼容，通过 enqueue_block_assets 加载的资源会在编辑器iframe内外同时加载。根据所加载的脚本库不同，这可能引发问题。Gutenberg项目的GitHub代码库正在持续讨论这一机制。

如果您在使用本指南所述方法时遇到未被报告过的问题，请在GitHub上提交问题报告。

在编辑器中加载资源

本指南旨在成为在编辑器中加载资源（脚本和样式）的权威参考。这里概述的方法代表了推荐实践，但请注意，随着WordPress的发展，本资源也会不断更新。欢迎贡献更新内容。

自WordPress 6.3起，如果所有已注册区块都具备区块API版本3或更高版本，且未注册传统元框，则文章编辑器将采用iframe嵌入。站点编辑器始终采用iframe嵌入。本指南假设您需要为iframe嵌入的编辑器加载资源，但请参考下文的后向兼容性章节了解其他注意事项。

若需了解编辑器为何采用iframe嵌入，请重温iframe嵌入（模板）编辑器中的区块这篇文章。

编辑器与编辑器内容

在编辑器中加载资源前，首先需要明确目标范围。

您是要为用户生成内容（区块）添加样式或JavaScript？还是要修改编辑器用户界面组件或与编辑器API交互？这可能包括从创建自定义区块控件到注册区块变体等各种场景。

根据这些问题的答案，需要使用不同的钩子。如果您正在构建区块或主题，还需要考虑其他方法。请参考下文对应章节。

资源加载场景

编辑器脚本与样式

当需要为编辑器本身（即非用户生成内容）加载资源时，应使用enqueue_block_editor_assets钩子，配合标准的wp_enqueue_script和wp_enqueue_style函数。

典型应用场景包括：添加自定义检查器或工具栏控件、通过JavaScript注册区块样式和变体、注册编辑器插件等。

/**
 * 加载编辑器资源
 */
function example_enqueue_editor_assets() {
    wp_enqueue_script(
        'example-editor-scripts',
        plugins_url( 'editor-scripts.js', __FILE__ )
    );
    wp_enqueue_style(
        'example-editor-styles',
        plugins_url( 'editor-styles.css', __FILE__ )
    );
}
add_action( 'enqueue_block_editor_assets', 'example_enqueue_editor_assets' );

虽然不推荐，但需注意出于后向兼容考虑，enqueue_block_editor_assets也可用于设置编辑器内容样式。详见下文说明。

编辑器内容脚本与样式

自WordPress 6.3起，所有通过enqueue_block_assetsPHP操作添加的资源都会在iframe嵌入的编辑器中加载。详见#48286。

这是为用户生成内容（区块）加载资源的主要方法，该钩子会在编辑器环境和网站前端同时触发。不应用于添加针对编辑器UI的资源或与编辑器API交互。后向兼容性说明详见下文。

某些情况下可能只需在编辑器中加载资源而不在前端加载。可通过is_admin()检测实现。

/**
 * 仅限编辑器内加载内容资源
 */
function example_enqueue_editor_content_assets() {
    if ( is_admin() ) {
        wp_enqueue_script(
            'example-editor-content-scripts',
            plugins_url( 'content-scripts.js', __FILE__ )
        );
        wp_enqueue_style(
            'example-editor-content-styles',
            plugins_url( 'content-styles.css', __FILE__ )
        );
    }
}
add_action( 'enqueue_block_assets', 'example_enqueue_editor_content_assets' );

也可使用block_editor_settings_all钩子直接修改编辑器设置。此方法实现稍复杂但灵活性更高，仅当enqueue_block_assets无法满足需求时使用。

以下示例将所有段落默认文字颜色设为绿色：

/**
 * 通过添加自定义样式修改编辑器设置
 *
 * @param array  $editor_settings 包含当前编辑器设置的数组
 * @param string $editor_context  编辑器上下文
 *
 * @return array 添加自定义CSS样式后的编辑器设置
 */
function example_modify_editor_settings( $editor_settings, $editor_context ) {
    $editor_settings["styles"][] = array(
        "css" => 'p { color: green }'
    );

    return $editor_settings;
}
add_filter( 'block_editor_settings_all', 'example_modify_editor_settings', 10,2 );

这些样式会以内联方式插入iframe编辑器的body中，并添加.editor-styles-wrapper前缀。最终生成的标记如下：

<style>.editor-styles-wrapper p { color: green; }</style>

从WordPress 6.3开始，还可通过这种修改编辑器设置的方法，使用JavaScript动态更改样式。详见#52767。

7.2 KiB Raw Blame History Unescape Escape