Gutenberg 插件开发使用 PluginDocumentSettingPanel 扩展文档设置侧栏面板【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergPluginDocumentSettingPanel 是 GutenbergWordPress 块编辑器通过wordpress/editor包暴露的一个 SlotFill 组件用于在文档设置侧栏Document Sidebar中注册自定义设置面板。本文基于 plugin-document-setting-panel.md 完整讲解其 Props、注册方式、面板命名空间规则以及如何通过wordpress/data以编程方式展开、启用或移除面板并结合packages/editor源码深入剖析其底层实现原理。什么是 PluginDocumentSettingPanelSlot 和 Fill 是 Gutenberg 暴露给开发者的一组组件用于把自定义内容注入到 Gutenberg 管理界面中预先定义好的位置。使用它们需要借助wordpress/plugins的registerPluginAPI 注册一个插件插件渲染的内容被 SlotFill 组件包裹后即可出现在目标位置参见 SlotFills 总览 与 SlotFill 组件文档。PluginDocumentSettingPanel对应的插槽位于编辑器文档设置侧栏中。从 sidebar/index.jsx 可以看到核心编辑器在文档标签页内直接渲染了PluginDocumentSettingPanel.Slot /所有注册到该插槽的 Fill 都会在此处呈现与「状态与可见性」Status Availability面板同属一个侧栏区域。可用 PropsPluginDocumentSettingPanel接受以下 Props与文档一致Prop类型必填说明namestring是标识该面板的机器友好名称用于唯一标识与编程访问classNamestring否追加到侧栏面板主体上的可选 CSS 类名titlestring否显示在面板顶部的标题iconstring \| Element否Dashicon 图标 slug 字符串或一个 SVG 的 WP Element当侧栏固定到工具栏时用于渲染图标从源码实现看plugin-document-setting-panel/index.jsx当name为undefined时组件会通过wordpress/warning输出一条开发警告PluginDocumentSettingPanel requires a name property.。这四个 Props 最终被透传给PanelBodyclassName、title、icon、opened、onToggle而children则作为面板内容渲染。基础用法注册一个自定义文档设置面板完整的最小示例与文档示例一致import { registerPlugin } from wordpress/plugins; import { PluginDocumentSettingPanel } from wordpress/editor; const PluginDocumentSettingPanelDemo () ( PluginDocumentSettingPanel namecustom-panel titleCustom Panel classNamecustom-panel Custom Panel Contents /PluginDocumentSettingPanel ); registerPlugin( plugin-document-setting-panel-demo, { render: PluginDocumentSettingPanelDemo, icon: palmtree, } );要点组件来自wordpress/editor而非wordpress/components插件必须通过registerPlugin( plugin-name, { render } )注册icon与文档设置面板无直接关系它决定插件在「更多」菜单等处展示的图标name属性必填且实际生效的面板名并非name本身而是「插件名 / name」组成的带命名空间名称见下文。如果插件环境不支持 ESNext 语法也可以使用 ES5 写法通过全局变量wp.editor.PluginDocumentSettingPanel与wp.plugins.registerPlugin获取组件源码 JSDoc 中给出了完整的 ES5 示例见 plugin-document-setting-panel/index.jsx。面板名称的命名空间规则自定义面板并不是以传入的name直接注册。源码中使用usePluginContext取到插件名然后拼出完整的面板名称const { name: pluginName } usePluginContext(); const panelName ${ pluginName }/${ name };也就是说上面示例中真正被编辑器数据层识别的面板名称是plugin-document-setting-panel-demo/custom-panel这一点在编程访问面板时至关重要任何通过toggleEditorPanelOpened、toggleEditorPanelEnabled、removeEditorPanel等函数操作面板的调用都必须拼接上插件名这个命名空间前缀否则将无法命中对应面板。以编程方式访问面板核心面板名称核心编辑器的内置面板拥有固定的名称可在文档设置侧栏中按名称定位面板面板名称摘要面板Summary Panelpost-status分类面板Categories Paneltaxonomy-panel-category标签面板Tags Paneltaxonomy-panel-post_tag特色图片面板Featured Image Panelfeatured-image摘要/摘要文字面板Excerpt Panelpost-excerpt讨论面板DiscussionPaneldiscussion-panel以特色图片面板与讨论面板为例其常量在源码中均有对应定义例如 post-featured-image/panel.jsx 中const PANEL_NAME featured-imagepost-discussion/panel.jsx 中const PANEL_NAME discussion-panel与文档列出的名称完全一致。展开 / 收起面板toggleEditorPanelOpened通过useDispatch从wordpress/data获取editorStore的 action即可在运行时切换面板的展开状态import { useDispatch } from wordpress/data; import { store as editorStore } from wordpress/editor; const Example () { const { toggleEditorPanelOpened } useDispatch( editorStore ); return ( Button variantprimary onClick{ () { // Toggle the Summary panel toggleEditorPanelOpened( post-status ); // Toggle the Custom Panel introduced in the example above. toggleEditorPanelOpened( plugin-document-setting-panel-demo/custom-panel ); } } Toggle Panels /Button ); };注意自定义面板必须使用带命名空间的名称pluginName/name。从 actions.js 的实现看toggleEditorPanelOpened实际维护的是wordpress/preferences中core作用域下的openPanels数组面板当前若在数组中则移除收起否则追加展开状态持久化于用户偏好设置。启用 / 停用面板toggleEditorPanelEnabled与之对应toggleEditorPanelEnabled( panelName )用于切换面板的启用状态底层维护inactivePanels数组面板处于停用列表则移出启用否则加入停用详见 actions.js。面板的启用状态同时受「是否被移除」与「是否在停用列表」两个条件约束见选择器isEditorPanelEnabledselectors.js。从编辑器移除面板removeEditorPanel也可以直接把某个已注册面板从编辑器中彻底移除import { useDispatch } from wordpress/data; import { store as editorStore } from wordpress/editor; const Example () { const { removeEditorPanel } useDispatch( editorStore ); return ( Button variantprimary onClick{ () { // Remove the Featured Image panel. removeEditorPanel( featured-image ); // Remove the Custom Panel introduced in the example above. removeEditorPanel( plugin-document-setting-panel-demo/custom-panel ); } } Toggle Panels /Button ); };removeEditorPanel向数据层派发一个REMOVE_PANELaction将面板名写入state.removedPanelsactions.js。对应选择器isEditorPanelRemoved判断面板是否在此列表中selectors.js。由于isEditorPanelEnabled首先检查「是否被移除」被移除的面板将不再渲染需要说明的是移除操作不可逆若后续仍需展示该面板应改用toggleEditorPanelEnabled进行停用而非移除。源码级原理Fill、Slot 与 PanelBodyPluginDocumentSettingPanel的完整实现位于 packages/editor/src/components/plugin-document-setting-panel/index.jsx核心逻辑如下使用createSlotFill( PluginDocumentSettingPanel )创建一对Fill/Slot组件并将Slot挂到组件静态属性上PluginDocumentSettingPanel.Slot Slot供核心侧栏在固定位置渲染通过useSelect读取isEditorPanelOpened( panelName )与isEditorPanelEnabled( panelName )前者决定面板初始是否展开后者决定面板是否渲染渲染结构上除Fill外还渲染了一个EnablePluginDocumentSettingPanelOption label{ title } panelName{ panelName } /它通过createSlotFill( EnablePluginDocumentSettingPanelOption )把「启用面板」开关注入到编辑器的偏好设置弹窗中见 enable-plugin-document-setting-panel.jsx。因此即使用户在「偏好设置 → 面板」中停用了该面板面板本体也会正确隐藏当isEnabled为真时Fill 内容是一个PanelBody其opened与onToggle被绑定到toggleEditorPanelOpened( panelName )实现点击面板头部时的展开/收起交互。从 packages/editor/src/components/index.js 可以看到该组件作为wordpress/editor的公开导出项export { default as PluginDocumentSettingPanel }因此插件代码中直接import { PluginDocumentSettingPanel } from wordpress/editor即可。条件渲染控制面板在哪些编辑器出现除PluginDocumentSettingPanel之外的多数 SlotFill 在文章编辑器Post Editor与站点编辑器Site Editor中都会同时渲染。若希望面板只在特定场景出现可通过wordpress/core-data查询当前文章类型对象的viewable属性进行判断详见 SlotFills 总览的条件渲染章节仅限文章编辑器viewable为true的文章类型才拥有独立的编辑文章界面据此可把面板限制在文章编辑器import { registerPlugin } from wordpress/plugins; import { PluginDocumentSettingPanel, store as editorStore, } from wordpress/editor; import { store as coreStore } from wordpress/core-data; import { useSelect } from wordpress/data; import { __ } from wordpress/i18n; const EditPostDocumentSettingPanel () { const isViewable useSelect( ( select ) { const postTypeName select( editorStore ).getCurrentPostType(); const postTypeObject select( coreStore ).getPostType( postTypeName ); return postTypeObject?.viewable; }, [] ); if ( ! isViewable ) { return null; } return ( PluginDocumentSettingPanel namecustom-panel title{ __( Post Editor Example ) } classNamecustom-panel p{ __( Only appears in the Edit Post screen ) }/p /PluginDocumentSettingPanel ); }; registerPlugin( example-post-edit-only, { render: EditPostDocumentSettingPanel, } );仅限特定文章类型在上例基础上增加允许列表例如仅在编辑页面page时渲染import { registerPlugin } from wordpress/plugins; import { PluginDocumentSettingPanel, store as editorStore, } from wordpress/editor; import { store as coreStore } from wordpress/core-data; import { useSelect } from wordpress/data; import { __, sprintf } from wordpress/i18n; const RestrictPostTypes () { const { isViewable, postTypeName } useSelect( ( select ) { const postType select( editorStore ).getCurrentPostType(); const postTypeObject select( coreStore ).getPostType( postType ); return { isViewable: postTypeObject?.viewable, postTypeName: postType, }; }, [] ); const allowedPostTypes [ page ]; if ( ! isViewable || ! allowedPostTypes.includes( postTypeName ) ) { return null; } return ( PluginDocumentSettingPanel namecustom-panel title{ __( Restrict Post Types Example ) } classNamecustom-panel p { sprintf( __( Only appears on Post Types that are in the allowed list. %s ), allowedPostTypes.join( , ) ) } /p /PluginDocumentSettingPanel ); }; registerPlugin( example-restrict-post-types, { render: RestrictPostTypes, } );仅限站点编辑器站点编辑器中的内部文章类型如模板wp_template、模板部件wp_template_part通常不设置viewable因此采用反向判断即可把面板限制在站点编辑器并可进一步用允许列表圈定具体屏幕。完整示例同样收录于 SlotFills 总览。进一步阅读SlotFills 参考总览含条件渲染完整示例PluginDocumentSettingPanel 组件实现编辑器侧栏 Slot 挂载位置面板相关数据 Action 实现面板相关数据 Selector 实现wordpress/plugins 注册 APISlotFill 组件机制【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
