Gutenberg 编辑器 Hooks 全指南使用 WordPress 过滤器与动作深度定制 Block Editor【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读WordPress 通过block_editor_settings_all等 PHP 过滤器、wordpress/hooks的 JavaScript 过滤器/动作以及 REST API 预加载路径过滤向插件与主题作者开放了大量编辑体验定制点。本文以官方文档 editor-filters.md 为核心骨架结合 Gutenberg 仓库源码系统讲解从禁用代码编辑器、限制响应式编辑到客户端媒体处理、错误边界日志上报的完整实现方案。读完本文你将能精确控制编辑器的行为开关、按需裁剪功能入口并将自己的逻辑无缝挂入编辑器的渲染管线。认识编辑器设置过滤器block_editor_settings_allblock_editor_settings_all是修改编辑器行为的最常用入口。它在编辑器初始化之前、设置项被发送到客户端之前被应用让插件与主题作者对编辑器行为拥有广泛的控制权。该钩子向回调函数传递两个参数$settings—— 编辑器可配置设置的数组$context——WP_Block_Editor_Context实例包含当前编辑器的信息如当前文章对象post、编辑器类型等。在 Gutenberg 仓库中插件自身的核心设置也是通过该过滤器注入的lib/block-editor-settings.php第 126 行以优先级0挂载gutenberg_get_block_editor_settings用于替换 WordPress 核心的styles与__experimentalFeatures设置并注明该钩子应最先运行因为它会完整替换核心设置。这说明过滤器存在执行顺序语义——如果你要在 Gutenberg 的默认值之上做叠加通常应使用默认优先级10若需先于或晚于插件内置逻辑可调整优先级参数第三个参数。兼容性提示WordPress 5.8 之前该钩子名为block_editor_settings现已废弃。如需兼容旧版本可通过判断WP_Block_Editor_Context类是否存在5.8 引入来决定使用哪个过滤器名称。Gutenberg 仓库中的兼容层实践可参考 lib/compat 目录其中针对不同 WordPress 版本拆分兼容代码。以下示例在存在文章上下文时修改最大上传文件大小可直接放入插件或主题的functions.php测试add_filter( block_editor_settings_all, example_filter_block_editor_settings_when_post_provided, 10, 2 ); function example_filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) { if ( ! empty( $editor_context-post ) ) { $editor_settings[maxUploadFileSize] 12345; } return $editor_settings; }编辑器设置有数十个无法在此逐一列举以下各节针对常见定制场景给出完整示例。要查看全部设置当前值打开编辑器后在浏览器控制台执行wp.data.select( core/block-editor ).getSettings()即可实时获取。按能力限制编辑器视图限制代码编辑器访问codeEditingEnabled默认值为true控制用户能否在可视化编辑器之外访问代码编辑器。当设置为false时设置菜单中的切换选项不可用切换编辑器类型的键盘快捷键不生效用户无法在可视化与代码编辑器之间切换。以下示例为无法激活插件的用户禁用代码编辑器add_filter( block_editor_settings_all, example_restrict_code_editor ); function example_restrict_code_editor( $settings ) { $can_active_plugins current_user_can( activate_plugins ); // Disable the Code Editor for users that cannot activate plugins (Administrators). if ( ! $can_active_plugins ) { $settings[ codeEditingEnabled ] false; } return $settings; }限制可视化编辑器访问与codeEditingEnabled类似richEditingEnabled控制谁能使用可视化编辑器。该设置默认取user_can_richedit()的返回值此函数同时检查用户是否具备可视化编辑权限以及浏览器是否支持相关能力。当将其设为false时用户只能以代码编辑器方式编辑。限制响应式编辑responsiveEditingEnabled默认值为true控制编辑器视图菜单中的 Responsive styles响应式样式选项是否可用。当设为false时该选项不再渲染Global Styles全局样式中的视口状态控件也被隐藏用户无法针对单个视口viewport定向修改样式但伪状态如 hover仍然可用主题或 Global Styles 中已定义的响应式样式不受影响。add_filter( block_editor_settings_all, example_disable_responsive_editing ); function example_disable_responsive_editing( $settings ) { $settings[responsiveEditingEnabled] false; return $settings; }限制块状态编辑blockStatesEditingEnabled默认值为true控制块检查器Block Inspector与 Global Styles 中的块状态控件是否渲染。设为false后用户无法从这些界面为状态states应用块样式视口状态控件不受影响仍由responsiveEditingEnabled控制。已保存在theme.json、Global Styles 或块style属性中的状态样式不受影响。add_filter( block_editor_settings_all, example_disable_block_states_editing ); function example_disable_block_states_editing( $settings ) { $settings[blockStatesEditingEnabled] false; return $settings; }设置默认图片大小与媒体相关开关设置默认图片大小编辑器中图片默认使用large尺寸。如果你配置了自定义图片尺寸可通过imageDefaultSize修改默认值。以下示例将默认图片尺寸改为mediumadd_filter( block_editor_settings_all, example_set_default_image_size ); function example_set_default_image_size( $settings ) { $settings[imageDefaultSize] medium; return $settings; }禁用 OpenverseOpenverse 媒体集成默认对所有 WordPress 站点启用由enableOpenverseMediaCategory设置控制。禁用方法add_filter( block_editor_settings_all, example_disable_openverse ); function example_disable_openverse( $settings ) { $settings[enableOpenverseMediaCategory] false; return $settings; }禁用字体库字体库Font Library允许用户在站点上安装新字体默认启用由fontLibraryEnabled控制add_filter( block_editor_settings_all, example_disable_font_library ); function example_disable_font_library( $settings ) { $settings[fontLibraryEnabled] false; return $settings; }禁用块检查器标签页多数块在检查器中显示两个标签页Settings设置与 Styles样式。可通过blockInspectorTabs设置禁用这些标签页。以下示例对所有块默认禁用标签页add_filter( block_editor_settings_all, example_disable_inspector_tabs_by_default ); function example_disable_inspector_tabs_by_default( $settings ) { $settings[blockInspectorTabs] array( default false ); return $settings; }也可以针对特定块禁用。以下示例为自定义块my-plugin/my-custom-block关闭标签页并注意使用_wp_array_get读取现有配置后通过array_merge合并避免覆盖其他设置add_filter( block_editor_settings_all, example_disable_tabs_for_my_custom_block ); function example_disable_tabs_for_my_custom_block( $settings ) { $current_tab_settings _wp_array_get( $settings, array( blockInspectorTabs ), array() ); $settings[blockInspectorTabs] array_merge( $current_tab_settings, array( my-plugin/my-custom-block false ) ); return $settings; }blockInspectorTabs是按块名索引的关联数组default键控制全局默认行为块名键如core/paragraph控制单块行为后者优先级更高——这正是 Gutenberg 客户端检查器渲染时逐块读取该配置的依据。禁用 Block Directory 与远程 Block Patterns禁用 Block DirectoryBlock Directory 允许用户在编辑器中直接安装来自 WordPress.org 插件目录的块插件。禁用方式是移除负责入队其资源的动作remove_action( enqueue_block_editor_assets, wp_enqueue_editor_block_directory_assets );这段代码应在插件或主题的初始化阶段如init钩子执行确保在enqueue_block_editor_assets触发前完成移除。禁用远程 Block Patterns远程模式如来自 WordPress.org 模式目录的 pattern默认在编辑器中对用户可用。该功能由should_load_remote_block_patterns控制默认值为trueadd_filter( should_load_remote_block_patterns, __return_false );Gutenberg 仓库的 packages/e2e-tests/mu-plugins/disable-remote-patterns.php 正是这样一个最小化测试插件——整个文件只有一句add_filter( should_load_remote_block_patterns, __return_false );被 e2e 测试用于验证远程模式禁用场景可作为生产环境的最小实现参考。禁用后编辑器将只展示本地注册的模式。使用 JavaScript 过滤器扩展编辑器特性JavaScript 侧通过wordpress/hooks包提供的addFilter/addAction挂入编辑器内部流程。以下过滤器均需在 JavaScript 环境中注册例如通过wp.hooks全局或在模块构建流程中导入wordpress/hooks。editor.PostFeaturedImage.imageSize该过滤器用于修改文章特色图片组件中显示的图片尺寸。默认值为post-thumbnail当指定尺寸在媒体对象中不存在时会回退到full尺寸。它借鉴了经典编辑器中admin_post_thumbnail_size过滤器的设计。import { addFilter } from wordpress/hooks; const withImageSize function ( size, mediaId, postId ) { return large; }; addFilter( editor.PostFeaturedImage.imageSize, my-plugin/with-image-size, withImageSize );从源码看该过滤器定义于 packages/editor/src/components/post-featured-image/index.jsx在解析特色图片 URL 时通过applyFilters( editor.PostFeaturedImage.imageSize, ... )应用回调可依据mediaId、postId按需返回不同尺寸。addFilter的第一个参数是钩子名第二个参数是命名空间标识建议使用插件名/功能名格式避免与第三方冲突第三个参数是回调函数可选的第四个参数为优先级。editor.PostPreview.interstitialMarkup该过滤器用于自定义生成预览时显示的过渡interstitial消息import { addFilter } from wordpress/hooks; const customPreviewMessage function () { return bPost preview is being generated!/b; }; addFilter( editor.PostPreview.interstitialMarkup, my-plugin/custom-preview-message, customPreviewMessage );其调用点位于 packages/editor/src/components/post-preview-button/index.jsxmarkup applyFilters( editor.PostPreview.interstitialMarkup, markup );。回调返回的字符串将作为预览生成期间的占位 HTML 注入预览窗口可用于品牌化提示或展示加载状态。media.crossOrigin该过滤器用于设置或修改跨域媒体元素audio、img、link、script、video的crossOrigin属性。回调接收第二个参数mediaSrc实际跨域媒体的 URL便于依据来源决定返回值import { addFilter } from wordpress/hooks; addFilter( media.crossOrigin, my-plugin/with-cors-media, // The callback accepts a second mediaSrc argument which references // the url to actual foreign media, useful if you want to decide // the value of crossOrigin based upon it. ( crossOrigin, mediaSrc ) { if ( mediaSrc.startsWith( https://example.com ) ) { return use-credentials; } return crossOrigin; } );crossOrigin的合法值包括anonymous与use-credentials。一个典型应用是图片块的变换transform功能为使跨域图片可被绘制进canvascanvas 会污染无法读取必须为其设置正确的 CORS 属性本过滤器正是该场景的定制入口。过滤编辑器 REST API 预加载路径block_editor_rest_api_preload_paths用于过滤初始化编辑器时预加载的 REST API 路径数组从而控制哪些公共数据随首屏一并下发。以下示例在存在文章上下文时追加OPTIONS请求以预取块类型信息add_filter( block_editor_rest_api_preload_paths, example_filter_block_editor_rest_api_preload_paths_when_post_provided, 10, 2 ); function example_filter_block_editor_rest_api_preload_paths_when_post_provided( $preload_paths, $editor_context ) { if ( ! empty( $editor_context-post ) ) { array_push( $preload_paths, array( /wp/v2/blocks, OPTIONS ) ); } return $preload_paths; }注意路径元素使用array( /wp/v2/blocks, OPTIONS )形式——这是 WordPress 预加载机制支持的路径 请求方法复合格式。Gutenberg 内部多处使用该过滤器注入依赖数据例如 lib/compat/wordpress-7.1/preload.php 与 lib/experimental/dataform-inspector-preload.php 中的预加载逻辑。客户端媒体处理Client-side Media Processing客户端媒体处理在浏览器内使用 WebAssemblyvips 库完成图片压缩、缩放、格式转换、旋转与缩略图生成。相关过滤器与参数如下完整架构参见 客户端媒体架构说明开发者指南参见 客户端媒体处理指南。wp_client_side_media_processing_enabled总开关该 PHP 过滤器控制客户端媒体处理是否启用默认值为true// Disable client-side media processing entirely. add_filter( wp_client_side_media_processing_enabled, __return_false );也可以按条件禁用add_filter( wp_client_side_media_processing_enabled, example_disable_for_editors ); function example_disable_for_editors( $enabled ) { if ( current_user_can( edit_posts ) ! current_user_can( manage_options ) ) { return false; } return $enabled; }禁用后所有上传回退到传统的服务端处理管线。该总开关同样统辖动画 GIF 转视频行为见下文因此是一个全局性主控。客户端处理遵循的既有 WordPress 过滤器客户端处理通过 REST API 从服务端读取以下既有过滤器配置并在浏览器端图像处理时应用过滤器作用默认值/说明big_image_size_threshold图像缩放阈值默认 2560px超过此尺寸的图像在客户端被缩放image_editor_output_format输入 MIME 类型到输出 MIME 类型的映射用于自动格式转换如 JPEG → WebP在客户端转码阶段应用image_save_progressive控制渐进式JPEG/交错式PNG、GIF编码在客户端压缩与格式转换阶段应用wp_image_maybe_exif_rotate控制基于 EXIF 的旋转客户端处理激活时服务端旋转被禁用由客户端处理wp_editor_set_qualityJPEG 输出另含jpeg_quality编码质量1–100服务端按每个注册尺寸解析该过滤器并在上传响应的 size-awareimage_quality字段中报告结果客户端在子尺寸缩放与转码时应用没有独立的 JavaScript 质量过滤器image_strip_meta控制是否剥离生成图像的元数据在 REST 索引上导出为false时客户端保留全部元数据EXIF、XMP、IPTC而不是剥离除色彩配置及 HDR 增益图之外的所有内容image_max_bit_depth限制生成图像的位深针对高比特深度 AVIF/HDR 源在 REST 索引上导出客户端编码器按 AVIF 编码器支持的位深8、10 或 12 位对齐需要特别注意的是客户端处理激活时由于不涉及服务端WP_Image_Editor以下三个服务端钩子永远不会触发wp_image_editors、image_make_intermediate_size、image_memory_limit。依赖这些钩子的插件需要改用 客户端媒体处理指南中的服务端插件兼容章节 提供的替代信号。关于可处理 MIME 类型客户端处理没有针对 MIME 类型集合的过滤器。受支持的集合固定为CLIENT_SIDE_SUPPORTED_MIME_TYPESimage/jpeg、image/png、image/gif、image/webp、image/avif定义于 packages/upload-media/src/store/constants.ts。此集合之外的格式回退到服务端处理HEIC/HEIF 则走独立的基于 canvas 的解码路径。REST API 附加参数客户端处理在上传媒体时使用以下附加 REST API 参数generate_sub_sizes布尔默认true—— 在POST /wp/v2/media上设为false时服务端跳过缩略图生成。客户端处理会将其设为false以便自行生成并 sideload 缩略图。convert_format布尔默认true—— 在POST /wp/v2/media或POST /wp/v2/media/{id}/sideload上设为false时服务端跳过基于image_editor_output_format过滤器的格式转换。当客户端已完成转换时使用。url字符串—— 传给POST /wp/v2/media而非文件主体时服务端下载远程图片并 sideload。用于在跨域隔离cross-origin-isolated的编辑器中导入外部图片规避浏览器跨域 fetch 失败的问题。动画 GIF 转视频不透明的动画 GIF 会在客户端转换为配套的 MP4/WebM 视频图片块上会出现 Display as video 控件允许用户将其切换为视频块的 GIF 变体。该行为没有专用过滤器——由上文的总开关wp_client_side_media_processing_enabled统一控制当浏览器缺少 WebCodecs 视频编码能力时回退为上传原始 GIF。详见 架构文档的动画 GIF 转视频章节 与 how-to 指南。捕获并上报编辑器错误editor.ErrorBoundary.errorLogged界面某处的 JavaScript 错误不应导致整个应用崩溃。为此 React 使用错误边界Error Boundary机制——错误边界是能捕获其子组件树中任意位置 JavaScript 错误的 React 组件并渲染备用 UI 而非崩溃的组件树。Gutenberg 的editor.ErrorBoundary.errorLogged动作让你能接入错误边界并获得错误对象以及 React 的 error info 对象其componentStack属性描述错误在组件树中被抛出的位置。典型用途是将错误发送到外部错误追踪工具import { addAction } from wordpress/hooks; addAction( editor.ErrorBoundary.errorLogged, mu-plugin/error-capture-setup, ( error, errorInfo ) { // Error is the exceptions error object. // You can console.log it or send it to an external error-tracking tool. console.log ( error, errorInfo?.componentStack ); } );注意这里是addAction而非addFilter——该钩子是一个无返回值的副作用型动作用于监听错误事件。其触发点位于 packages/editor/src/components/error-boundary/index.jsx错误边界捕获异常后调用doAction( editor.ErrorBoundary.errorLogged, error, errorInfo )。你可以将error与errorInfo?.componentStack序列化后发送到 Sentry 等外部错误追踪服务从而在不侵入编辑器内部实现的情况下获得全站编辑器错误的可观测性。结语与进一步阅读编辑器定制从上到下分为三个层次PHP 侧的block_editor_settings_all设置开关、block_editor_rest_api_preload_paths数据预加载、should_load_remote_block_patterns等内容来源控制JavaScript 侧的wordpress/hooks过滤器与动作以及客户端媒体处理所遵循的服务端既有过滤器。掌握这些钩子后你可以精确裁剪编辑器功能、调整媒体行为并把自定义逻辑无缝接入编辑器生命周期。如需继续深入推荐阅读本仓库中的相关文档block-editor-settings.phpGutenberg 如何注入默认设置、客户端媒体架构说明、客户端媒体处理指南以及参考指南总览 filters 下的其他过滤器文档。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考