在编辑器中加载资源-WordPress区块编辑器手册-果果开发

本指南旨在成为在编辑器中加载资源（脚本和样式）的权威参考。此处概述的方法代表了最佳实践，但请记住，随着 WordPress 的发展，本资源也将随之演变。欢迎提交更新。

站点编辑器始终使用 iframe。Gutenberg 23.6 和 WordPress 7.1 也始终对文章编辑器使用 iframe，无论文章内容中的 Block API version 如何。WordPress 7.0 保留了针对非 iframe 文章编辑器的条件回退机制。本指南假设您针对的是 iframe 编辑器；在支持旧版 WordPress 版本时，请参阅下方的向后兼容性部分。

有关为何编辑器使用 iframe 的更多信息，请重新阅读帖子 Blocks in an iframed (template) editor。

编辑器与编辑器内容

在编辑器中加载资源之前，您必须首先确定要针对的目标是什么。

您是想为编辑器中的用户生成内容（区块）添加样式或 JavaScript？还是想修改编辑器用户界面 (UI) 组件或与编辑器 API 交互？这可能包括从创建自定义区块控件到注册区块变体的一切内容。

根据这些问题的答案，有不同的钩子可以使用。如果您正在构建区块或主题，还有额外的方法需要考虑。请参阅下方的指定部分。

加载资源的场景

编辑器脚本和样式

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

示例包括添加自定义检查器或工具栏控件、在 JavaScript 中注册区块样式和变体、注册编辑器插件等。

/**
 * Enqueue Editor assets.
 */
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。

这是您应该用于为用户生成内容（区块）加载资源的主要方法，此钩子会在编辑器和您的站点前端同时触发。不应将其用于添加旨在编辑器 UI 或与编辑器 API 交互的资源。有关向后兼容性的说明，请参见下文。

在某些情况下，您可能只想在编辑器中添加资源，而不想在页面前端添加。您可以通过使用 is_admin() 检查来实现这一点。

/**
 * Enqueue content assets but only in the Editor.
 */
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。

/**
 * Modify the Editor settings by adding custom styles.
 *
 * @param array  $editor_settings An array containing the current Editor settings.
 * @param string $editor_context  The context of the editor.
 *
 * @return array Modified editor settings with the added custom CSS style.
 */
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 是加载专门针对区块本身所需的所有脚本和样式的推荐方法。您可以为编辑器、页面前端或两者加载资源。有关更多详细信息，请参见 Block Metadata 文章。

主题脚本和样式

如果您需要在主题中加载编辑器 JavaScript，您可以使用上述的 enqueue_block_assets 或 enqueue_block_editor_assets。特定于编辑器的样式表几乎总是应该通过 add_editor_style() 或 wp_enqueue_block_style() 添加。

wp_enqueue_block_style() 函数允许您在编辑器和页面前端加载每个区块的样式表。结合 theme.json，这是样式化区块的最佳方法之一。有关更多详细信息，请参见 WordPress 开发者博客文章 Leveraging theme.json and per-block styles for more performant themes。

向后兼容性和已知问题

作为一般规则，当您在 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 repository 中进行查看。

如果您遇到本指南中概述的任何方法的问题且尚未报告，请在 GitHub 上提交问题。