Gutenberg 编辑器资源加载指南在 iframe 化 Editor 中正确 enqueue 脚本与样式【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读本文是 Gutenberg 仓库中关于在块编辑器Block Editor中加载资源脚本与样式的权威实操指南。无论是为编辑器 UI工具栏控件、检查器控件、插件面板加载 JavaScript还是为 iframe 内的用户生成内容区块注入样式不同目标对应着enqueue_block_editor_assets、enqueue_block_assets、block_editor_settings_all等不同的钩子。读完本文你将掌握在插件与主题中按场景正确选择资源加载钩子、理解 iframe 编辑器的加载机制并能在兼容旧版 WordPress 时做出正确取舍。本文基于 Gutenberg 仓库 docs/how-to-guides/enqueueing-assets-in-the-editor.md 展开并结合仓库lib/目录下的真实实现源码进行纵深讲解。文中引用的行号均可直接在仓库中核对。背景Editor 为什么是 iframe 化的Site Editor站点编辑器始终使用 iframe。本文档撰写时Gutenberg 23.6 与 WordPress 7.1 起无论文章内容中区块的 Block API 版本 如何Post Editor文章编辑器也始终使用 iframeWordPress 7.0 仍保留了对非 iframe 文章编辑器的条件性回退。本文默认你的目标是 iframe 化编辑器支持旧版本 WordPress 时的做法请参考文末向后兼容一节。iframe 化的意义在于编辑器的画布用户内容与编辑器 UI 被隔离在独立的文档上下文中主题的前端样式不会直接污染编辑界面而编辑器中看到的区块渲染与前端也得以保持一致。这也意味着你为编辑器加载的资源其最终去向编辑器 UI 文档还是 iframe 内的内容文档直接决定了你应该使用哪个钩子。第一步先分清 Editor 与 Editor content在动手 enqueue 任何资源之前必须先回答一个问题你到底想给谁加载资源Editor编辑器 UI指编辑器本身的界面组件——顶部工具栏、检查器Inspector、区块工具条、设置面板、插件注册的侧边栏等以及所有通过 JavaScript 注册的区块变体、格式、插件。Editor content编辑器内容指用户在编辑器中创建的内容即页面/文章中的区块本体及其渲染结果。两个目标使用完全不同的钩子如果你在构建区块或主题还有额外的方法可选。下表先给出概览下文逐一展开目标推荐钩子 / 方法生效范围编辑器 UI 的脚本与样式enqueue_block_editor_assets仅编辑器用户生成内容区块的脚本与样式enqueue_block_assets编辑器 iframe 内 前端仅编辑器内的内容样式高级做法block_editor_settings_all仅编辑器 iframe 内区块自身的脚本与样式block.jsonBlock Metadata按声明控制主题的编辑器样式add_editor_style()/wp_enqueue_block_style()/theme.json编辑器 / 前端场景一为编辑器 UI 加载脚本与样式当需要为编辑器本身而非用户生成内容加载资源时使用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 );在 Gutenberg 仓库自身这一钩子被大量用于加载编辑器所需的模块化资源。例如 lib/client-assets.php 中插件通过enqueue_block_editor_assets加载了三个编辑器脚本模块add_action( enqueue_block_editor_assets, gutenberg_enqueue_latex_to_mathml_loader ); function gutenberg_enqueue_latex_to_mathml_loader() { wp_enqueue_script_module( wordpress/latex-to-mathml/loader ); } // 以及 vips 加载器、video-conversion 加载器均注册为 import map 中的动态依赖 // 以便在客户端媒体处理被触发时按需加载。可见该钩子不仅支持传统wp_enqueue_script也支持以wp_enqueue_script_module()注册 ES Module脚本模块供编辑器内部按需取用。仓库 lib/script-loader.php 还演示了如何在同一条钩子上替换全局样式 CSS 自定义属性的注册逻辑。需要强调的是虽然enqueue_block_editor_assets在技术上也能用于给编辑器内容加样式但这不是推荐做法仅作为向后兼容手段存在详见文末。场景二为编辑器内容区块加载脚本与样式2.1 首选方案enqueue_block_assets自 WordPress 6.3 起通过enqueue_block_assetsPHP 动作添加的所有资源也会被 enqueue 到 iframe 化编辑器内。这是为用户生成内容区块加载资源的主要方法——该钩子在编辑器与站点前端都会触发。因此它不应被用于添加面向编辑器 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 );从源码层面看iframe 内内容样式的加载链路在 Gutenberg 中有着精心设计的依赖顺序。lib/client-assets.php 中注册wp-edit-blocks样式时注释明确写着Only add CONTENT styles here that should be enqueued in the iframe!这里只添加应当在 iframe 内 enqueue 的内容样式并维护了如下依赖链$wp_edit_blocks_dependencies array( wp-theme, // 设计系统 tokens 最先加载确保 :root CSS 自定义属性先于消费它的样式表被定义 wp-components, wp-reset-editor-styles, // 需在块库样式之前块库样式会覆盖 reset 样式 wp-block-library, wp-block-editor-content, wp-base-styles, );这段实现印证了进入 iframe 的内容样式并非随意拼接而是按设计令牌 → 组件 → 重置 → 块库 → 编辑器内容 → 基础样式的顺序加载从而保证变量定义、重置与覆盖关系都正确。2.2 进阶方案block_editor_settings_all 过滤器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 动态修改编辑器设置来实时变更样式。在 Gutenberg 仓库中lib/block-editor-settings.php 的gutenberg_get_block_editor_settings()函数正是在block_editor_settings_all过滤器上优先级 0替换 core 的styles与__experimentalFeatures设置它收集全局样式预设、区块类样式、定制器附加 CSS 与自定义 CSS与get_block_editor_theme_styles()的结果合并后写回$settings[styles]。这展示了该过滤器在真实项目中的典型用法——在编辑器设置送达 iframe 之前集中注入、排序与兜底全局样式。场景三区块自身的脚本与样式block.json当你在构建区块时block.json是声明区块所需全部脚本与样式的推荐方式。你可以在其中分别声明用于编辑器、前端或两者兼有的资源editorScript、editorStyle、script、style、viewScript等字段详见仓库中的 Block Metadata 参考。Gutenberg 对区块资源的注册同样遵循每块多样式的分工。查看 lib/blocks.php 的gutenberg_register_core_block_assets()它为每个核心区块分别解析三个样式文件——style.css前端样式注册为wp-block-{name}、theme.css主题化样式注册为wp-block-{name}-theme以及style-editor.css编辑器样式注册为wp-block-{name}-editor并借助wp_should_load_separate_core_block_assets()判断是否启用按区块拆分加载策略。这正是block.json声明在运行时如何被翻译为独立、可精确控制的作用域。场景四主题的脚本与样式如果需要在主题中 enqueue 编辑器 JavaScript可以按前文所述使用enqueue_block_assets或enqueue_block_editor_assets。而编辑器专属的样式表几乎总应通过以下方式之一添加add_editor_style()经典主题将样式表同时应用于编辑器内容与前端渲染的常用做法wp_enqueue_block_style()允许在编辑器与前端按区块粒度加载样式表与theme.json配合是当前性能最优的区块样式方案之一。wp_enqueue_block_style()的核心价值在于按需加载——只有当页面真正渲染了某个区块时对应的样式才会被加载从而避免一次性输出全部区块样式拖慢首屏。结合theme.json中的样式声明styles与settings体系主题作者可以把区块样式从全局兜底细化为区块级精准投递。Gutenberg 仓库 lib/theme.json 与 lib/global-styles-and-settings.php 即演示了这类配置如何被解析为最终的编辑器与前端样式输出。向后兼容与已知问题兼容规则速览作为一般规则在 iframe 化编辑器中 enqueue 的资源只要你在使用 WordPress 6.3那么当编辑器不是iframe 时这些资源同样会被 enqueue反过来则不一定成立。需要兼容 6.2 及更低版本时如果你的插件或主题需要向后兼容 WordPress 6.2 或更低版本同时又要兼容 6.3那么不能依赖enqueue_block_assets——因为在 6.3 之前该钩子不会把资源 enqueue 进 iframe 编辑器的内容中。作为替代方案可以改用enqueue_block_editor_assets但前提是 enqueue 的样式表中至少包含以下选择器之一.editor-styles-wrapper、.wp-block或.wp-block-*。此时浏览器控制台会记录一条警告信息但钩子仍会把样式应用到编辑器内容上。也就是说旧版 WordPress 依赖编辑器文档内选择器命中间接应用到内容这一机制新版则直接支持 iframe 内加载。资源双加载问题自 WordPress 6.3 起enqueue_block_assetsenqueue 的资源出于向后兼容考虑会同时在编辑器 iframe 内部和外部被加载。如果你 enqueue 的脚本库对重复加载敏感例如初始化全局监听器、重复绑定事件这可能导致问题。关于这一方案的取舍Gutenberg 仓库中仍有持续的讨论遇到问题可先搜索是否已被报告。处理未收录的问题如果你在使用本文所述方法时遇到尚未被报告的问题建议在仓库的 Issue 系统中提交新问题并注明所用 WordPress/Gutenberg 版本、钩子与复现步骤。总结一个决策清单目标是谁——编辑器 UI 用enqueue_block_editor_assets用户内容用enqueue_block_assets仅编辑器内的内容样式可尝试block_editor_settings_all。是区块吗——优先使用block.json声明资源让运行时的每块多样式机制为你管理作用域。是主题吗——编辑器样式优先add_editor_style()/wp_enqueue_block_style()并结合theme.json做按块加载。要兼容 6.2 以下吗——避免单独依赖enqueue_block_assets改用带.editor-styles-wrapper/.wp-block选择器的enqueue_block_editor_assets并接受控制台警告。担心重复加载——注意 6.3 起enqueue_block_assets在 iframe 内外双加载的影响评估脚本库的幂等性。按照这张清单选择钩子你的资源就能在 iframe 化编辑器中各归其位UI 归 UI内容归内容前端归前端。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考