使用 PluginMoreMenuItem 为 WordPress 块编辑器注入更多工具与选项菜单项【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergPluginMoreMenuItem是 Gutenberg 编辑器包wordpress/editor提供的 SlotFill 组件允许插件在块编辑器右上角更多工具与选项More Tools Options下拉菜单中注入自定义菜单项。本文将以 docs/reference-guides/slotfills/plugin-more-menu-item.md 为骨架结合仓库源码packages/editor/src/components/plugin-more-menu-item/index.jsx、packages/editor/src/components/more-menu/index.jsx 等深入讲解其用法、Props、底层原理、条件渲染与迁移注意事项读完即可在你的插件中实现一个功能完整的菜单项。PluginMoreMenuItem 是什么PluginMoreMenuItem是一个 SlotFill 扩展点其作用正如官方文档所述This slot will add a new item to the More Tools Options section.即向块编辑器界面右上角的选项Options下拉菜单即通常所说的 More Menu中新增一个菜单条目。该条目可以表现为按钮执行回调或链接跳转 URL具体取决于传入的 Props。SlotFill 是 Gutenberg 暴露给开发者的扩展机制允许把内容注入到编辑器预先定义好的位置。按照 SlotFills 参考文档 的说明使用任何 SlotFill 都需要四步从wordpress/plugins导入registerPlugin从wordpress/editor导入所需的 SlotFill 组件这里是PluginMoreMenuItem定义一个渲染自定义内容的组件把要注入的内容包裹在 SlotFill 组件内部调用registerPlugin注册插件。PluginMoreMenuItem与同类的PluginSidebarMoreMenuItem、PluginBlockSettingsMenuItem、PluginDocumentSettingPanel等组件共同组成了编辑器的官方扩展体系完整的 SlotFill 清单可参考 SlotFills Reference。快速上手注入一个按钮型菜单项官方文档给出了最简示例。下面的代码注册一个插件在 More Menu 中新增一个带图标的菜单项点击时弹出提示框import { registerPlugin } from wordpress/plugins; import { PluginMoreMenuItem } from wordpress/editor; import { image } from wordpress/icons; const MyButtonMoreMenuItemTest () ( PluginMoreMenuItem icon{ image } onClick{ () { alert( Button Clicked ); } } More Menu Item /PluginMoreMenuItem ); registerPlugin( more-menu-item-test, { render: MyButtonMoreMenuItemTest } );要点拆解registerPlugin( more-menu-item-test, { render: ... } )插件名必须全局唯一render传入要渲染的 React 组件PluginMoreMenuItem的children 即菜单项的显示文本More Menu Itemicon传入wordpress/icons中的 SVG 图标onClick是点击菜单项时执行的回调。菜单项出现的位置在编辑器右上角的竖向省略号Options下拉菜单中。在该菜单展开时插件注入的条目会出现在面板Panels分组中与编辑器内置的视图切换Visual editor / Code editor等条目同属一个大菜单。核心 API 与 Props 详解根据组件源码 JSDocpackages/editor/src/components/plugin-more-menu-item/index.jsx#L9-L14PluginMoreMenuItem支持以下 PropsProp类型默认值说明childrenReact.ReactNode—菜单项的显示内容通常为标签文本hrefstring—提供时菜单项渲染为a链接而非按钮对应锚点的href属性iconDashicon slug 字符串或 SVG WP 元素继承自插件渲染在菜单项标签左侧的图标onClickFunctionnoop用户点击菜单项时执行的回调函数其他 Props...*—透传给底层菜单项组件as已被废弃并忽略几个值得注意的行为icon默认继承插件图标。源码中icon{ itemProps.icon || context.icon }context来自usePluginContext()packages/editor/src/components/plugin-more-menu-item/index.jsx#L62-L81。因此如果你在registerPlugin时设置了插件的icon菜单项会自动使用它无需重复传入。href决定渲染形态。传入href时菜单项变成链接源码中由more-menu-group.tsx的toMenuItems根据fill.props.href ! undefined选择渲染Menu.LinkItem还是Menu.Item见 more-menu-group.tsx#L64-L72。as已废弃。源码检测到as时调用deprecated()并忽略该属性自版本 7.2 起因为菜单项由菜单自身的机制渲染不需要外部指定组件。使用 ES5 语法的写法源码 JSDoc 中还保留了基于wp.*全局对象的 ES5 示例适用于未使用构建工具的环境var __ wp.i18n.__; var PluginMoreMenuItem wp.editor.PluginMoreMenuItem; var moreIcon wp.element.createElement( svg ); // ...svg element. function onButtonClick() { alert( Button clicked. ); } function MyButtonMoreMenuItem() { return wp.element.createElement( PluginMoreMenuItem, { icon: moreIcon, onClick: onButtonClick, }, __( My button title ) ); }现代开发建议直接使用import语法ESNext因为wp.editor.PluginMoreMenuItem需要你的插件在编辑器环境wordpress/editor已加载中运行。源码原理从 PluginMoreMenuItem 到菜单渲染要理解这个 SlotFill 的完整链路需要沿着源码走一遍。1. 组件本身只是 ActionItem 的封装PluginMoreMenuItem的真实实现非常轻量packages/editor/src/components/plugin-more-menu-item/index.jsx#L62-L81export default function PluginMoreMenuItem( props ) { const context usePluginContext(); const { as, ...itemProps } props; if ( as ) { deprecated( The as prop of wp.editor.PluginMoreMenuItem, { since: 7.2, hint: The menu renders the item itself. The prop is ignored., } ); } return ( ActionItem namecore/plugin-more-menu icon{ itemProps.icon || context.icon } { ...itemProps } / ); }它把一切交给wordpress/interface包的ActionItem并指定了 Slot 名称为core/plugin-more-menu。2. ActionItem 通过 Slot/Fill 建立连接ActionItem由Fill填充方即你的插件与ActionItem.Slot槽位方即编辑器菜单两部分组成packages/interface/src/components/action-item/index.tsxActionItem渲染Fill name{ name }把自身作为填充内容注入槽位ActionItem.Slot渲染Slot name{ name }收集所有同名 Fill通过children函数render prop交给菜单渲染。ActionItem有一个关键交互设计槽位会把用于渲染菜单项的组件as默认MenuItem和关闭菜单的 onClick通过fillProps传给每个 Fill。Fill 端的onClick不会替换槽位的 handler而是两者串联执行action-item/index.tsx#L33-L60const Component as ?? slotAs; const handlers [ onClick, slotOnClick ].filter( Boolean ); // ...合并调用所有 handlers这意味着你写的onClick执行后菜单还会自行关闭无需手动处理。3. 编辑器 More Menu 中的槽位真正的插槽位于编辑器头部菜单组件中packages/editor/src/components/more-menu/index.jsx#L114-L123ActionItem.Slot namecore/plugin-more-menu fillProps{ { as: MoreMenuItem } } { ( items ) ( MoreMenuGroup label{ __( Panels ) } { items } /MoreMenuGroup ) } /ActionItem.Slot可以看到槽位名称core/plugin-more-menu与PluginMoreMenuItem内部使用的名称完全一致fillProps.as被设为编辑器的MoreMenuItem因此你的菜单项最终由编辑器自己的菜单项组件渲染保证风格与无障碍行为一致所有插件注入的条目被统一收进 label 为Panels面板的分组组内由 MoreMenuGroup 负责把每个 Fill 转换为Menu.Item按钮或Menu.LinkItem链接。4. 分组与键盘导航MoreMenuGroup的toMenuItems函数more-menu-group.tsx#L49-L73负责把自带渲染内容的 Fill包装成真正参与菜单键盘导航的菜单项并利用renderprop 保留 Fill 自身的渲染输出。也就是说即使你的组件没有使用编辑器提供的MoreMenuItem它也会被正确包装进菜单的无障碍导航树中。进阶实践链接菜单项与条件渲染渲染为链接需要跳转时传入href菜单项即变为链接import { registerPlugin } from wordpress/plugins; import { PluginMoreMenuItem } from wordpress/editor; import { external } from wordpress/icons; const MyLinkMoreMenuItem () ( PluginMoreMenuItem hrefhttps://example.com/docs icon{ external } target_blank View documentation /PluginMoreMenuItem ); registerPlugin( more-menu-item-link, { render: MyLinkMoreMenuItem } );href之外的其他 Props如target会透传给底层菜单项组件。菜单对链接型条目会渲染为Menu.LinkItem支持target_blank新窗口打开。控制注入时机与范围根据 SlotFills 参考文档 的说明绝大多数 SlotFill包括PluginMoreMenuItem在文章编辑器Post Editor与站点编辑器Site Editor中都会渲染因此通常需要自行控制显示范围。常用手法包括限制在文章编辑器通过editorStore.getCurrentPostType()与coreStore.getPostType()判断当前文章类型的viewable属性是否为true限制在特定文章类型维护一个允许列表如[ page ]仅在该列表内渲染限制在站点编辑器与上面逻辑相反非 viewable 的内部文章类型如wp_template、wp_template_part、wp_block即站点编辑器场景。示例仅对 page 文章类型显示菜单项import { registerPlugin } from wordpress/plugins; import { PluginMoreMenuItem, store as editorStore } from wordpress/editor; import { store as coreStore } from wordpress/core-data; import { useSelect } from wordpress/data; import { settings } from wordpress/icons; const PageOnlyMoreMenuItem () { const isPage useSelect( ( select ) { const postType select( editorStore ).getCurrentPostType(); return postType page; }, [] ); if ( ! isPage ) { return null; } return ( PluginMoreMenuItem icon{ settings } Page-only action /PluginMoreMenuItem ); }; registerPlugin( page-only-more-menu-item, { render: PageOnlyMoreMenuItem } );结合其他 SlotFill 使用PluginMoreMenuItem常与PluginSidebar配合通过PluginSidebarMoreMenuItem打开侧边栏。若你的侧边栏开关已经存在于更多工具与选项菜单中注意不要让菜单项重复PluginSidebarMoreMenuItem内部同样基于core/plugin-more-menu槽位机制工作属于同一体系相关组件清单见 packages/editor/src/components/index.js#L28。兼容性与迁移说明历史上PluginMoreMenuItem同时从wordpress/edit-post暴露wp.editPost.PluginMoreMenuItem。在 packages/edit-post/src/deprecated.jsx 中可以确认该别名自6.6起已废弃const deprecateSlot ( name ) { deprecated( wp.editPost.${ name }, { since: 6.6, alternative: wp.editor.${ name }, } ); };并且wp.editPost版本的PluginMoreMenuItem在站点编辑器site-editor.php中会直接返回nulldeprecated.jsx#L17-L19、deprecated.jsx#L54-L60。因此新代码一律从wordpress/editor导入PluginMoreMenuItem旧代码应迁移wp.editPost.PluginMoreMenuItem→wp.editor.PluginMoreMenuItem从wordpress/edit-site暴露的同名别名同样是迁移桩见 packages/edit-site/src/deprecated.jsx#L24-L29同样应改用wordpress/editor。无障碍与测试保障菜单项最终由wordpress/ui的Menu体系渲染自带完整的键盘导航、ARIA 角色与焦点管理。仓库中的单元测试packages/editor/src/components/more-menu/test/more-menu-item.jsdom.test.tsx覆盖了以下关键行为可作为你实现菜单项时的参考基准复选框/单选角色保留rolemenuitemcheckbox、menuitemradio与aria-checked状态会被正确保留isSelected也能驱动选中态链接渲染href空字符串也渲染为链接target_blank生效disabled链接变为不可交互项并带aria-disabledtrue快捷键显示支持字符串或{ display, ariaLabel }对象形式的shortcut并提供可访问的快捷键描述Dashicon以 slug 传入的图标如editor-kitchensink会渲染对应的.dashicons类名。小结PluginMoreMenuItem是一个薄封装 强生态的扩展点组件本身只有约 20 行代码但经由ActionItempackages/interface/src/components/action-item/index.tsx与core/plugin-more-menu槽位被无缝接入编辑器右上角更多工具与选项菜单的 Panels 分组并获得图标继承、链接/按钮双形态、菜单关闭联动与无障碍键盘导航等能力。实际开发时只需记住从wordpress/editor导入、用registerPlugin注册、用icon/href/onClick/children 控制形态并按需用editorStore/coreStore做条件渲染。若想了解更多注入点可继续阅读 SlotFills Reference 中列出的其他 SlotFill 文档或查看 wordpress/plugins 包说明 了解插件注册 API 的完整用法。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考