在编辑器中加载资源

本指南旨在成为在编辑器中加载资源（脚本和样式）的权威参考。此处概述的方法代表了推荐实践，但请注意，随着 WordPress 的发展，本资源也会不断更新。我们鼓励您持续关注更新。

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

有关编辑器为何采用 iframe 嵌入的更多信息，请重新阅读文章 iframe 嵌入（模板）编辑器中的区块。

编辑器与编辑器内容

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

您是想为用户在编辑器中生成的内容（区块）添加样式或 JavaScript？还是希望修改编辑器用户界面（UI）组件或与编辑器 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_assets PHP 操作添加的资源也会在 iframe 编辑器中入队。更多详情请参阅 #48286。

这是为（区块的）用户生成内容入队资源的主要方法，此钩子会在编辑器中和网站前端同时触发。它不应被用于添加面向编辑器界面或与编辑器 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 无法满足您的需求时才应使用它。

以下示例将所有段落的默认文本颜色设置为 green。

/**
 * 通过添加自定义样式来修改编辑器设置。
 *
 * @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。

阻止脚本和样式

在构建区块时，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 上提交问题。