Gutenberg 的 PluginBlockSettingsMenuItem 插槽指南为块设置菜单More Options注入自定义菜单项【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergPluginBlockSettingsMenuItem 是 Gutenberg 块编辑器wordpress/editor提供的一个 SlotFill 插槽允许插件开发者向选中块的「更多选项」More Options菜单中注入自定义菜单项。本文围绕官方参考文档 plugin-block-settings-menu-item.md 展开结合仓库内 plugin-block-settings-menu-item.jsx 的源码实现完整讲解它的位置、全部 Props、可复制运行的示例代码以及底层的渲染与过滤逻辑帮助你在不修改核心代码的前提下扩展块级操作入口。这个插槽是什么PluginBlockSettingsMenuItem 是一个「块设置菜单项」插槽。它把插件自定义的菜单项渲染进每个块的操作菜单即选中块后工具栏上的「更多选项 / Options」三圆点下拉菜单中。它的两个关键特性位置随用户设置变化菜单项会出现在每个块的控件菜单中或出现在**顶部工具栏Top Toolbar**中具体取决于用户的界面设置参考文档原文This will either appear in the controls for each block or at the Top Toolbar depending on the users setting。即开启「统一工具条Unified toolbar」偏好时块操作菜单会收拢到顶部工具栏你的菜单项也随之移动无需插件做任何额外适配。按块类型定向显示通过allowedBlocks属性你可以让菜单项只出现在指定块如仅core/paragraph的菜单中实现精准的上下文注入。在 docs/reference-guides/slotfills/README.md 的 SlotFills 参考列表中它与其他插槽如PluginBlockSettingsMenuGroup、PluginDocumentSettingPanel并列是扩展块编辑体验的标准入口之一。Props 详解根据官方文档 packages/editor/README.md 的参数说明与源码 plugin-block-settings-menu-item.jsx 的 JSDoc该组件接受以下属性属性类型必填说明allowedBlocksArray否块名称Block Name数组指定菜单项仅在哪些块上显示。不传则对所有块显示。多选块时仅当所有选中块的类型都在该列表中才显示不要求是同一个块。iconWPBlockTypeIconRender否菜单项图标。可以是 Dashicon 的 slug 字符串如smiley也可以是一个 SVG WP 元素。labelstring是菜单项文本。onClickFunction是用户点击菜单项时执行的回调函数。smallboolean否是否渲染 label 文本。true时 label 作为MenuItem的label属性传入配合noIcons场景下的紧凑布局false默认时 label 作为菜单项的子文本渲染。rolestring否菜单项的 ARIA role用于无障碍访问语义定制。完整示例ESNext可直接复制运行继承参考文档的官方示例plugin-block-settings-menu-item.md并补充国际化与注释使其可直接放进插件的入口 JS 文件import { registerPlugin } from wordpress/plugins; import { PluginBlockSettingsMenuItem } from wordpress/editor; import { __ } from wordpress/i18n; const PluginBlockSettingsMenuGroupTest () ( PluginBlockSettingsMenuItem allowedBlocks{ [ core/paragraph ] } iconsmiley label{ __( Menu item text, my-plugin ) } onClick{ () { alert( clicked ); } } / ); registerPlugin( block-settings-menu-group-test, { render: PluginBlockSettingsMenuGroupTest, } );关键点registerPlugin来自wordpress/plugins插件必须通过它注册组件才会被挂载进编辑器。PluginBlockSettingsMenuItem从wordpress/editor导入它由 packages/editor/src/components/index.js 统一导出。上面的label使用__()做国际化非官方示例必需但属于插件开发最佳实践。点击后菜单会自动关闭因为源码中使用compose( onClick, onClose )将你的回调与关闭菜单的onClose组合在一起详见下文原理分析所以你只需关注自己的业务逻辑。ES5 传统写法不使用构建工具时如果插件不经过 Webpack/Babel 构建可以使用wp.editor全局变量以 ES5 方式实现同样的效果官方文档 packages/editor/README.md 提供了该写法var __ wp.i18n.__; var PluginBlockSettingsMenuItem wp.editor.PluginBlockSettingsMenuItem; function doOnClick() { // 用户点击菜单项时要执行的逻辑 } function MyPluginBlockSettingsMenuItem() { return React.createElement( PluginBlockSettingsMenuItem, { allowedBlocks: [ core/paragraph ], icon: dashicon-name, label: __( Menu item text ), onClick: doOnClick, } ); }底层实现原理理解源码能帮你更准确地使用这个插槽。核心实现在 plugin-block-settings-menu-item.jsx 中仅约 100 行逻辑非常清晰。1. 它本质上是 BlockSettingsMenuControls 的薄封装组件内部导入了wordpress/block-editor的BlockSettingsMenuControls源码第 1 行并以 render props 方式消费它BlockSettingsMenuControls { ( { selectedBlocks, onClose } ) { if ( ! shouldRenderItem( selectedBlocks, allowedBlocks ) ) { return null; } return ( MenuItem onClick{ compose( onClick, onClose ) } icon{ icon } label{ small ? label : undefined } role{ role } { ! small label } /MenuItem ); } } /BlockSettingsMenuControls从源码结构看BlockSettingsMenuControls是更底层的插槽Slot 定义在 packages/block-editor/src/components/block-settings-menu-controls/index.jsx 的createSlotFill( BlockSettingsMenuControls )它本身也承载了「转换为组 / 锁定 / 重命名 / 可见性」等核心菜单项。PluginBlockSettingsMenuItem相当于为插件开发者提供了「只添加一个菜单项」的便捷封装而不必手动处理selectedBlocks判断和MenuItem组合。2. allowedBlocks 的过滤逻辑源码中shouldRenderItem与isEverySelectedBlockAllowed两段辅助函数plugin-block-settings-menu-item.jsx决定了菜单项的显隐const isEverySelectedBlockAllowed ( selected, allowed ) selected.filter( ( id ) ! allowed.includes( id ) ).length 0; const shouldRenderItem ( selectedBlocks, allowedBlocks ) ! Array.isArray( allowedBlocks ) || isEverySelectedBlockAllowed( selectedBlocks, allowedBlocks );未传入allowedBlocks即非数组时菜单项对所有块渲染传入数组时当前选中块列表中任意一个不在白名单内菜单项就不渲染多选场景当多个块被选中时只有全部选中块的类型都属于白名单允许是不同类型的块才显示。selectedBlocks来自BlockSettingsMenuControls的 Slot fillProps——在 block-settings-menu-controls/index.jsx 中通过getBlockNamesByClientId( ids )获取当前选中块的名称数组并随canEdit、selectedClientIds一起下发。3. 点击后自动关闭菜单onClick被compose( onClick, onClose )包裹源码第 93 行即点击你的菜单项后块设置菜单会自动关闭无需在回调里手动处理。onClose由BlockSettingsDropdown在下拉菜单打开时注入——见 block-settings-dropdown.jsx其中以fillProps{ { onClose, count, firstBlockClientId } }渲染BlockSettingsMenuControls.Slot。4. 渲染位置与内容保护从 block-settings-dropdown.jsx 与 block-settings-menu-controls/index.jsx 的代码可以看出插槽填充fills仅在非contentOnly编辑模式即非「仅内容编辑」的模板局部锁定状态下渲染同时它被放进MenuGroup中与「转换为组、锁定、重命名」等核心菜单项同组显示视觉上紧邻这些系统菜单项。实战注意事项国际化label建议用__()包裹参考packages/editor包内其他组件的做法避免硬编码文案。图标选择icon传 Dashicon slug如smiley、star-filled最简单需要定制图形时也可直接传 SVG 元素。不要把重型操作放 onClick 里菜单项点击即触发且菜单随即关闭适合「复制内容、跳转、开关设置」这类短操作需要长流程交互时建议改用PluginBlockSettingsMenuGroup可嵌入表单控件或Modal组合方案。与PluginBlockSettingsMenuGroup的区别PluginBlockSettingsMenuItem只负责渲染单个MenuItem如果需要在同一组中放置多个控件开关、输入框、分组菜单应使用同目录下的其他 Group 类插槽它们共享同一个BlockSettingsMenuControls底层槽位。相关文件指引官方参考文档docs/reference-guides/slotfills/plugin-block-settings-menu-item.md组件源码packages/editor/src/components/block-settings-menu/plugin-block-settings-menu-item.jsx导出声明packages/editor/src/components/index.jsAPI 文档含参数表与双版本示例packages/editor/README.md底层插槽实现packages/block-editor/src/components/block-settings-menu-controls/index.jsx菜单挂载点packages/block-editor/src/components/block-settings-menu/block-settings-dropdown.jsxSlotFills 索引docs/reference-guides/slotfills/README.md综上PluginBlockSettingsMenuItem是向块级「更多选项」菜单注入操作入口的最轻量方案一个registerPlugin加一个组件即完成接入allowedBlocks负责精准定向底层由BlockSettingsMenuControls插槽统一承载且天然兼容用户对工具栏布局的偏好设置。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考