Gutenberg 插件 BlockControls 指南为 WordPress 区块自定义工具栏的组件原理与实战【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg在 GutenbergWordPress 块编辑器中BlockControls是开发者向选中区块的浮动工具栏注入自定义控件的官方入口。本文以packages/block-editor/src/components/block-controls/README.md为骨架结合仓库内block-controls目录的源码实现、block-toolbar的 Slot 装配逻辑与单元测试完整讲解BlockControls的使用方式、Props 语义、六大分组机制以及底层 Slot/Fill 渲染原理帮助你在自定义区块的edit函数中快速落地工具栏按钮、对齐控件等交互。一、BlockControls 是什么当用户在编辑器画布中选中某个区块时区块上方会浮现一条工具栏其中按需渲染一组控制按钮。某些区块级控件会在特定条件下被自动加入该工具栏——例如「转换为其他区块类型」的转换控件或当焦点元素是RichText组件时出现的格式控件参考 block-toolbar/README.md。BlockControls允许你定制这条工具栏只要你的区块类型edit函数返回的 JSX 中包含了BlockControls元素嵌套在其中的控件就会出现在该区块被选中时的工具栏上。下图展示了段落区块工具栏中控件的外观从源码看BlockControls本质上是一个「填充Fill」组件它在声明位置把子控件渲染到由工具栏提供的「插槽Slot」中。index.jsx 中BlockControls BlockControlsFill并挂载了BlockControls.Slot作为配套插槽同时保留了向后兼容的BlockFormatControls别名它等价于groupinline的BlockControlsexport const BlockFormatControls ( props ) { return BlockControlsFill groupinline { ...props } /; };二、快速上手在 edit 函数中使用 BlockControlsBlockControls需要与useBlockProps、BlockAlignmentMatrixControl等配合使用。以下示例来自 README.md演示了如何在自定义区块中渲染一个「内容对齐矩阵」控件并将结果写回区块属性import { BlockControls, __experimentalBlockAlignmentMatrixControl as BlockAlignmentMatrixControl, useBlockProps, } from wordpress/block-editor; import { __ } from wordpress/i18n; export default function MyBlockEdit( { attributes, setAttributes } ) { const blockProps useBlockProps( { className: my-block__custom-class, } ); const { contentPosition } attributes; return ( div { ...blockProps } { BlockControls BlockAlignmentMatrixControl label{ __( Change content position ) } value{ contentPosition } onChange{ ( nextPosition ) setAttributes( { contentPosition: nextPosition, } ) } / /BlockControls } /div ); }要点解读控件声明在edit函数返回的 JSX 内、BlockControls标签之间BlockControls本身不渲染任何可见 DOM它只是把内部控件「传送」到工具栏插槽。BlockAlignmentMatrixControl是实验性 API__experimental前缀演示了「受控组件」模式value绑定属性onChange调用setAttributes更新属性保持单数据源。更完整的自定义区块 工具栏控件教程见 docs/getting-started/fundamentals/block-in-the-editor.mdblock-editor包内各组件以及components包的 README 也大量使用BlockControls可作为参考样例。三、Props 完整说明BlockControls接受以下 Propsgroup控件所属的分组用于在同一工具栏中创建并渲染多组区块控件。类型string默认值default必填否group的合法取值由 groups.js 定义共六个分组default、block、inline、other、parent、style-state。若传入未注册的分组名slot.jsx 会调用warning( \Unknown BlockControls group ${ group } provided. )并在控制台给出警告同时返回null 不渲染任何内容。controls当使用default分组时允许覆盖默认的controls一组以{ icon, title, ... }形式描述的按钮配置。这些配置会被 fill.jsx 转换为ToolbarGroup controls{ controls } /渲染成按钮组。类型array示例元素结构{ icon: alignLeft, title: Align left, align: left }见测试文件 test/index.jsdom.test.jsxchildren额外的控件组件会作为BlockControls的子节点被渲染到工具栏。实际开发中更常见的做法是把ToolbarButton、ToolbarDropdownMenu、ToolbarGroup等直接作为children传入。类型Element必填否注意当group default时children与controls会同时被渲染前者作为 JSX 子节点后者包装成ToolbarGroup。__experimentalShareWithChildBlocks是否将这些额外的区块控件同时添加到子区块的工具栏中。类型boolean默认值false启用后当当前区块的mayDisplayControls为假、但mayDisplayParentControls为真时控件会改用parent分组的 Fill 渲染到父级插槽详见下文原理小节。四、底层原理Slot/Fill 与六分组机制BlockControls的渲染链路由四个文件协作完成采用 WordPresswordpress/components提供的 Slot/Fill 模式实现跨组件树传送内容index.jsx导出BlockControls即BlockControlsFill并挂载.Slot静态属性同时提供向后兼容的BlockFormatControls。fill.jsxBlockControlsFill组件。它根据group和__experimentalShareWithChildBlocks通过useBlockControlsFill钩子选出目标Fill组件若钩子返回null当前上下文不允许显示控件则整体返回null不渲染。渲染时group default会额外包装一层ToolbarGroup controls{ controls } /随后把内容放入StyleProvider document{ document }并通过fillProps.forwardedContext将ToolbarContext与ComponentsContext的 Provider 逐层包裹在填充内容外部确保工具栏上下文如导航状态正确传递。slot.jsxBlockControlsSlot组件。它通过useSlotFills查询当前分组下的 Fill 数量无填充时返回nullgroup default直接渲染Slot其余分组再用ToolbarGroup包裹插槽实现同组控件的视觉聚合。groups.js用createSlotFill注册六个插槽并导出分组映射const BlockControlsDefault createSlotFill( BlockControls ); const BlockControlsBlock createSlotFill( BlockControlsBlock ); const BlockControlsInline createSlotFill( BlockFormatControls ); const BlockControlsOther createSlotFill( BlockControlsOther ); const BlockControlsParent createSlotFill( BlockControlsParent ); const BlockControlsStyleState createSlotFill( BlockControlsStyleState ); const groups { default: BlockControlsDefault, block: BlockControlsBlock, inline: BlockControlsInline, other: BlockControlsOther, parent: BlockControlsParent, style-state: BlockControlsStyleState, };六个分组在工具栏中的落点由 block-toolbar/index.jsx 装配parent、block、default、inline依序渲染在工具栏主区域style-state紧随其后other组则位于工具栏靠后位置、紧邻「最后一项」插槽__unstableBlockToolbarLastItem.Slot。这也解释了为什么非default分组的 Slot 需要再包一层ToolbarGroup——便于把同一分组的多个填充在视觉上归并。五、条件渲染mayDisplayControls 与共享子区块控件BlockControls是否真正渲染取决于区块编辑上下文block-edit/context.js中的两个 Symbol 键mayDisplayControlsKey与mayDisplayParentControlsKey。BlockEdit组件会把这些标志写入上下文见 block-edit/index.jsx。hook.js 的决策逻辑如下export default function useBlockControlsFill( group, shareWithChildBlocks ) { const context useBlockEditContext(); if ( context[ mayDisplayControlsKey ] ) { return groups[ group ]?.Fill; } if ( context[ mayDisplayParentControlsKey ] shareWithChildBlocks ) { return groups.parent.Fill; } return null; }即当前区块允许显示控件mayDisplayControls为真时按group选择对应分组的Fill否则若区块允许显示父级控件mayDisplayParentControls为真且__experimentalShareWithChildBlocks为真则回退到parent分组的Fill——这正是「把控件共享给子区块工具栏」的实现路径两种情况都不满足时返回nullBlockControls静默不渲染。这也解释了 README 中__experimentalShareWithChildBlocks默认false的原因共享行为会改变控件的展示层级属于显式开启的实验性能力。六、测试验证仓库为BlockControls提供了完整的 jsdom 单元测试test/index.jsdom.test.jsx通过testing-library/react在SlotFillProviderBlockEdit传入mayDisplayControls环境下注册一个core/test-block并断言controls属性会渲染出动态按钮组按钮数量与controls.length一致且每个按钮携带title、align等自定义属性children内容会被渲染到插槽中把ToolbarGroup作为children传入时同样能渲染出动态工具栏。这些用例验证了「BlockControls内容最终出现在BlockControls.Slot中」这一核心契约是复现组件行为、理解 Slot/Fill 交互的最小可运行示例。七、小结BlockControls是 Gutenberg 区块工具栏扩展的核心组件从「在edit中声明控件」到「经 Slot/Fill 传送到工具栏」再到「按上下文条件决定是否渲染」整条链路清晰且可测试。实际开发建议工具栏中直接可见的按钮优先用children组合ToolbarButton/ToolbarGroup需要按图标配置批量生成按钮时用controls数组需要把控件分享给子区块工具栏时谨慎开启__experimentalShareWithChildBlocks深入理解分组语义后可参照 docs/getting-started/fundamentals/block-in-the-editor.md 与 block-toolbar/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），仅供参考
