Gutenberg 插件侧边栏菜单项 PluginSidebarMoreMenuItem：从 Options 菜单打开 PluginSidebar 的完整指南

Gutenberg 插件侧边栏菜单项 PluginSidebarMoreMenuItem从 Options 菜单打开 PluginSidebar 的完整指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergPluginSidebarMoreMenuItem是 WordPress Gutenberg 编辑器提供的 SlotFill 插槽用于在编辑器右上角Options更多工具与选项下拉菜单中注册一个菜单项点击后即可激活对应的PluginSidebar /侧边栏面板。本文将基于 Gutenberg 仓库中的官方参考文档docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md为主线结合 packages/editor 与 packages/interface 的源码实现讲解该插槽的用途、自动注册机制、props 说明、完整示例与底层原理帮助你为插件侧边栏提供自定义的菜单入口文本与图标。一、这个 Slot 解决什么问题在 Gutenberg 的插件扩展体系SlotFill 体系中PluginSidebarMoreMenuItem是一个Fill填充物插槽它的作用是在编辑器界面的Options 下拉菜单More Tools Options / 更多工具与选项中向Plugins插件分组渲染一个菜单项点击该菜单项时激活对应的PluginSidebar /侧边栏面板。也就是说它是「Options 菜单 ↔ 插件侧边栏」之间的桥梁用户无需通过工具栏图标而是可以通过 Options 菜单直接打开或切换插件侧边栏。默认行为自动注册通常无需手动使用文档明确指出一个关键设计当你注册一个PluginSidebar /时Gutenberg 会自动使用该侧边栏的titleprop 注册一个对应的PluginSidebarMoreMenuItem /。因此在大多数场景下你并不需要手动使用这个 Slot 来创建菜单项。从源码可以验证这一点。PluginSidebar底层渲染的是ComplementaryArea见 packages/editor/src/components/plugin-sidebar/index.jsx而在 packages/interface/src/components/complementary-area/index.tsx 中有如下逻辑{ name isPinnable ! hasMenuItem ( DefaultComplementaryAreaMoreMenuItem target{ name } scope{ scope } icon{ icon } identifier{ identifier } { title } /DefaultComplementaryAreaMoreMenuItem ) }其中hasMenuItem来自useHasComplementaryAreaMenuItem( scope, name )定义见 packages/interface/src/components/complementary-area-more-menu-item/index.tsx它通过一个observableMap统计当前scope/target下已注册的菜单项数量。由此可以推断当侧边栏isPinnable默认true且没有开发者手动注册的菜单项时界面层会自动注入一个以title为文本的默认菜单项一旦你在插件里通过PluginSidebarMoreMenuItem显式注册了菜单项自动注入的默认项就会被跳过! hasMenuItem为 false从而避免出现两个重复菜单项。这段去重逻辑在源码注释中也有对应说明见 complementary-area-more-menu-item/index.tsx。二、何时需要手动使用该 Slot既然有自动注册那么手动使用PluginSidebarMoreMenuItem的价值在于完全自定义菜单项的展示内容。典型场景自定义菜单项文本不希望菜单项显示为侧边栏的title而是显示更贴合产品语义的文案例如「打开设置面板」而不是「我的侧边栏」自定义图标为菜单项指定与侧边栏不同的图标自定义子元素菜单项标签可以使用任意 React 节点作为children实现富文本或动态内容。这正是官方文档给出的示例所演示的用例「This example shows how customize the text for the menu item instead of using the default text provided by thePluginSidebar /title.」三、Props 说明根据 packages/editor/src/components/plugin-sidebar-more-menu-item/index.jsx 中的 JSDoc 类型注释PluginSidebarMoreMenuItem的核心 props 如下Prop类型必填说明targetstring是标识该菜单项要激活的目标侧边栏必须与对应PluginSidebar /的nameprop 完全一致childrenReact.ReactNode否渲染在菜单项中的内容即菜单项标签文本iconDashicon 字符串或 SVG WP 元素否渲染在菜单项标签左侧的图标默认继承自插件plugin的图标as-否已废弃自 Gutenberg 7.2 起菜单由界面层自行渲染该 prop 会被忽略并触发deprecated警告关于asprop 的废弃源码中有明确的deprecated()调用plugin-sidebar-more-menu-item/index.jsxif ( as ) { deprecated( The as prop of wp.editor.PluginSidebarMoreMenuItem, { since: 7.2, hint: The menu renders the item itself. The prop is ignored., } ); }因此在新代码中请勿再传入as。四、完整示例自定义菜单项文本 插件侧边栏以下示例完整继承自官方参考文档见 plugin-sidebar-more-menu-item.md演示如何自定义菜单项文本同时注册一个包含表单控件的PluginSidebarimport { __ } from wordpress/i18n; import { PluginSidebar, PluginSidebarMoreMenuItem } from wordpress/editor; import { PanelBody, Button, TextControl, SelectControl, } from wordpress/components; import { registerPlugin } from wordpress/plugins; import { useState } from wordpress/element; import { image } from wordpress/icons; const PluginSidebarMoreMenuItemTest () { const [ text, setText ] useState( ); const [ select, setSelect ] useState( a ); return ( PluginSidebarMoreMenuItem targetsidebar-name icon{ image } { __( Custom Menu Item Text ) } /PluginSidebarMoreMenuItem PluginSidebar namesidebar-name icon{ image } titleMy Sidebar PanelBody h2 { __( This is a heading for the PluginSidebar example. ) } /h2 p { __( This is some example text for the PluginSidebar example. ) } /p TextControl label{ __( Text Control ) } value{ text } onChange{ ( newText ) setText( newText ) } / SelectControl label{ __( Select Control ) } value{ select } options{ [ { value: a, label: __( Option A ) }, { value: b, label: __( Option B ) }, { value: c, label: __( Option C ) }, ] } onChange{ ( newSelect ) setSelect( newSelect ) } / Button variantprimary { __( Primary Button ) }{ } /Button /PanelBody /PluginSidebar / ); }; registerPlugin( plugin-sidebar-more-menu-item-example, { render: PluginSidebarMoreMenuItemTest, } );示例关键点解读配对关系PluginSidebarMoreMenuItem的targetsidebar-name必须与PluginSidebar的namesidebar-name一致两者才能建立关联。从源码看target最终会被用作菜单项激活的补充区域标识见 complementary-area-more-menu-item/index.tsx 中menuItems.set(${ scope }/${ target }... )的键值逻辑同时也正是该注册行为让ComplementaryArea不再注入重复的默认菜单项。children 即菜单文本{ __( Custom Menu Item Text ) }会显示为 Options 菜单中该条目的标签取代默认的titleMy Sidebar。文档注释明确说明「The text within the component appears as the menu item label.」见 plugin-sidebar-more-menu-item/index.jsx。图标统一示例中菜单项与侧边栏都使用image图标wordpress/icons导出保持视觉一致若省略菜单项的icon则会继承插件级图标context.icon见 complementary-area/index.tsx。国际化所有面向用户的文本都应使用__()来自wordpress/i18n包裹便于后续翻译。五、底层实现原理5.1 组件结构从 editor 到 interface 的委托PluginSidebarMoreMenuItem本身是一个很薄的包装组件完整实现仅约 14 行核心代码packages/editor/src/components/plugin-sidebar-more-menu-item/index.jsxexport default function PluginSidebarMoreMenuItem( props ) { const { as, ...itemProps } props; if ( as ) { deprecated( The as prop of wp.editor.PluginSidebarMoreMenuItem, { since: 7.2, hint: The menu renders the item itself. The prop is ignored., } ); } return ComplementaryAreaMoreMenuItem scopecore { ...itemProps } /; }它把所有 props 委托给wordpress/interface包中的ComplementaryAreaMoreMenuItemscope 固定为core后者在 packages/interface/src/components/complementary-area-more-menu-item/index.tsx 中通过useLayoutEffect在挂载/卸载时维护menuItemsobservableMap中scope/target的计数器供useHasComplementaryAreaMenuItem查询从而实现「插件自己注册了菜单项就不再自动注入默认项」的去重机制渲染DefaultComplementaryAreaMoreMenuItem它由ComplementaryAreaToggle以rolemenuitemcheckbox呈现支持选中状态反馈包装ActionItem组成ActionItem的名字为${ scope }/plugin-more-menu即最终落入 Options 菜单的 Plugins 分组。5.2 与 PluginSidebar 的自动联动PluginSidebar同样委托给ComplementaryAreapackages/editor/src/components/plugin-sidebar/index.jsx而ComplementaryArea在 packages/interface/src/components/complementary-area/index.tsx 中集中处理了自动菜单项注入第 317-326 行isPinnable默认true且无显式菜单项时注入以title为文本的DefaultComplementaryAreaMoreMenuItem侧边栏主体渲染ComplementaryAreaFill承载Panel与childrenComplementaryAreaHeader显示标题并非移动端视口下提供「Pin to toolbar / Unpin from toolbar」按钮第 350-368 行状态管理通过interfaceStore的enableComplementaryArea/disableComplementaryArea控制激活状态。因此「自动注册的菜单项」与「显式注册的菜单项」最终走的是同一条ComplementaryAreaMoreMenuItem → ActionItem渲染链路只是显式注册时文本与图标可由插件完全掌控。5.3 编程方式打开侧边栏除了点击菜单项侧边栏还可以通过数据层 API 编程式打开见 plugin-sidebar/index.jsx 中的 JSDoc 示例wp.data.dispatch( core/edit-post ).openGeneralSidebar( plugin-name/sidebar-name );注意这里的参数格式为插件名/侧边栏名这与ComplementaryArea计算 identifier 的规则${ context.name }/${ name }一致见 complementary-area/index.tsx。六、适用场景与注意事项适用场景插件提供了PluginSidebar希望 Options 菜单中的入口文案、图标与侧边栏标题不同或希望菜单项展示动态/富文本内容。保持 target 与 name 一致target与对应PluginSidebar的name必须完全一致否则菜单项无法激活目标侧边栏且去重机制也会失效可能出现重复菜单项。避免重复注册既然注册PluginSidebar时已自动生成菜单项只有在确实需要自定义时才显式使用本 Slot界面层会通过计数器跳过自动注入项但你仍需保证target正确。注意isPinnable当PluginSidebar的isPinnable{ false }时自动菜单项不会注入见 complementary-area/index.tsx 的条件isPinnable此时若仍希望在 Options 菜单中提供入口手动使用PluginSidebarMoreMenuItem是唯一途径。兼容性本 Slot 在 Post Editor 与 Site Editor 中均可用参见 docs/reference-guides/slotfills/README.md 中对 SlotFill 可用范围的说明asprop 自 7.2 起废弃不应再使用。七、相关资源官方参考文档docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.mdSlotFills 总览docs/reference-guides/slotfills/README.md姊妹 Slot——PluginSidebardocs/reference-guides/slotfills/plugin-sidebar.md非关联菜单项 Slot——PluginMoreMenuItem不绑定侧边栏仅添加菜单项docs/reference-guides/slotfills/plugin-more-menu-item.md源码实现packages/editor/src/components/plugin-sidebar-more-menu-item/index.jsxpackages/editor/src/components/plugin-sidebar/index.jsxpackages/interface/src/components/complementary-area-more-menu-item/index.tsxpackages/interface/src/components/complementary-area/index.tsxSlotFill 基础概念packages/components/src/slot-fill/README.md【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考