Gutenberg 块编辑器用 BlockControls 与 InspectorControls 构建块级设置界面【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读本文面向所有使用 GutenbergWordPress 块编辑器开发自定义块的开发者系统讲解块在编辑器中的渲染机制块通过edit属性中的 React 组件呈现在编辑器中开发者可以借助BlockControls块工具栏与InspectorControls设置侧边栏为块定义定制化的设置界面。读完本文你将掌握块Edit组件的props设计、两大内置设置区域的正确用法与适用边界、常用内置组件选型以及块属性从block.json定义、JSX 交互到数据库序列化的完整链路。块在编辑器中的渲染React SPA 与 edit 组件Gutenberg 块编辑器本质上是一个 React 单页应用SPA编辑器中的每一个块都通过一个 React 组件来展示这个组件定义在块类型block type的设置对象settings object的edit属性中。也就是说块在前端/保存端的输出由save决定而块在编辑器里的编辑态预览则由edit决定。块的EditReact 组件接收的props对象至少包含以下核心成员attributes包含该块全部属性的对象数据来自块标记block markup与block.json中attributes的声明类型、默认值、source来源等。setAttributes用于更新attributes对象的方法。它接收一个部分属性对象将变更合并进块的当前属性是驱动编辑交互的核心 API。isSelected布尔值表示块当前是否被选中常用于按选中态渲染不同的 UI例如仅在选中时显示额外控件。WordPress 还内置了大量标准组件可以通过wordpress/components与wordpress/block-editor两个包引入用于快速搭建块编辑界面。Gutenberg 项目还使用 Storybook 对 WordPress 包中可用的 UI 组件进行文档化展示对应文档配置位于仓库的 storybook 目录适合在动手写代码前快速浏览组件的交互效果与 API。一个最小可运行的 Edit 组件在实际项目中块类型通过registerBlockType注册edit函数返回的 JSX 即编辑器中的渲染结果。一个最小可运行的Edit组件形态如下import { useBlockProps } from wordpress/block-editor; export default function Edit( { className, attributes, setAttributes } ) { return ( div { ...useBlockProps() } { /* 块的编辑界面 */ } /div ); }useBlockProps负责把块属性如自定义 class、锚点合并到根元素上保证编辑态标记与保存态标记的一致性。自定义设置界面的两大入口块工具栏与设置侧边栏为了简化块的自定义并保证用户体验一致Gutenberg 提供了若干内置 UI 模式来生成块的编辑器预览。其中最重要的一对是Block Toolbar块工具栏块被选中时在块上方浮现的一排控制按钮。Settings Sidebar设置侧边栏编辑器右侧的设置面板用于承载块级设置。如果块类型的Edit函数返回值中包含了BlockControls元素其内部嵌套的控件就会显示在选中块的工具栏中同理如果返回值中包含InspectorControls元素这些控件就会显示在设置侧边栏区域。当多个同类型的块同时被选中时工具栏与侧边栏中渲染的块控件同样可用。BlockControls 与块工具栏BlockControls位于 packages/block-editor/src/components/block-controls它基于wordpress/components的 Slot/Fill 机制实现BlockControls的index.jsx导出 Fill 组件并挂载Slot工具栏区域通过同名 Slot 接收内容。其内部的groups.js定义了多个分组default、block、inline、other、parent、style-state分别对应工具栏中的不同位置与场景例如inline分组即向后兼容的BlockFormatControls用于行内格式控件。通过BlockControls给块添加对齐控件等工具栏设置的示例export default function Edit( { className, attributes: attr, setAttributes } ) { const onChangeContent ( newContent ) { setAttributes( { content: newContent } ); }; const onChangeAlignment ( newAlignment ) { setAttributes( { alignment: newAlignment undefined ? none : newAlignment, } ); }; return ( div { ...useBlockProps() } BlockControls ToolbarGroup AlignmentToolbar value{ attr.alignment } onChange{ onChangeAlignment } / /ToolbarGroup /BlockControls RichText className{ className } style{ { textAlign: attr.alignment } } tagNamep onChange{ onChangeContent } value{ attr.content } / /div ); }BlockControls的常用 props 包括groupstring默认default控件分组用于创建并渲染多组块控件。controlsarray在使用default分组时覆盖默认控件。childrenElement要渲染的额外控件组件。__experimentalShareWithChildBlocksboolean默认false是否把额外块控件同时添加到子块的工具栏中。需要注意的是BlockControls仅在块当前被选中且处于可视化编辑模式时可见在 HTML 编辑模式下编辑块时工具栏控件不会显示。仓库中 block-controls 的测试用例 验证了动态工具栏的渲染行为通过SlotFillProvider包裹、BlockEdit声明mayDisplayControls最终断言所有对齐按钮可见且携带正确的align属性同时也验证了通过children传入ToolbarGroup controls的另一种写法。InspectorControls 与设置侧边栏设置侧边栏用于展示那些使用频率较低、或者需要更大屏幕空间的设置。设置侧边栏应当只承载块级设置block-level settings且仅在块被选中时显示。如果某个设置只影响块内选中的内容例如加粗文本绝不能放进设置侧边栏而应该使用工具栏。原因在于设置侧边栏即使在 HTML 编辑模式下也会显示因此它只应包含对整个块生效的设置。通过InspectorControls在设置侧边栏中渲染颜色等设置控件的示例export default function Edit( { attributes, setAttributes } ) { const onChangeBGColor ( hexColor ) { setAttributes( { bg_color: hexColor } ); }; const onChangeTextColor ( hexColor ) { setAttributes( { text_color: hexColor } ); }; return ( div { ...useBlockProps() } InspectorControls keysetting div fieldset legend classNameblocks-base-control__label { __( Background color, block-development-examples ) } /legend ColorPalette // Element Tag for Gutenberg standard color selector onChange{ onChangeBGColor } // onChange event callback / /fieldset fieldset legend classNameblocks-base-control__label { __( Text color, block-development-examples ) } /legend ColorPalette onChange{ onChangeTextColor } / /fieldset /div /InspectorControls TextControl value{ attributes.message } onChange{ ( val ) setAttributes( { message: val } ) } style{ { backgroundColor: attributes.bg_color, color: attributes.text_color, } } / /div ); }InspectorControls位于 packages/block-editor/src/components/inspector-controls同样基于 Slot/Fill 实现。与块工具栏类似它的 groups.js 定义了丰富的分组default、advanced、background、border、color、content、dimensions、layout、position、typography、viewport等其中advanced分组即向后兼容导出的InspectorAdvancedControls用于在设置侧边栏的高级Advanced面板中追加 HTML 锚点、自定义 CSS 类等普通用户很少接触的设置。这些分组与block.json中supports生成的面板一一对应是核心块与自定义块设置界面的统一归宿。InspectorAdvancedControls的典型用法如下import { TextControl } from wordpress/components; import { InspectorControls, InspectorAdvancedControls, } from wordpress/block-editor; function MyBlockEdit( { attributes, setAttributes } ) { return ( div{ /* Block markup goes here */ }/div InspectorControls { /* Regular control goes here */ } /InspectorControls InspectorAdvancedControls TextControl labelHTML anchor value{ attributes.anchor } onChange{ ( nextValue ) { setAttributes( { anchor: nextValue } ); } } / /InspectorAdvancedControls / ); }内置组件库wordpress/components 与 wordpress/block-editorwordpress/components通用 UI 元素库packages/components 是wordpress/components包的源码所在地它提供了用于构建块编辑器与 WordPress 后台通用 UI 元素的组件库全部组件都可以在 Storybook 中交互预览。最常用的组件包括TextControl单行文本输入框用于文本类属性如消息内容。Panel/PanelBody可折叠面板容器用于把设置侧边栏中的控件分组收纳InspectorControls中常见的PanelBody title设置即由此而来。ToggleControl开关控件用于布尔属性。ExternalLink带外部链接图标的链接组件。在 InspectorControls 的 README 示例 中CheckboxControl、RadioControl、TextControl、ToggleControl、SelectControl与PanelBody一起构成了完整的设置面板每种控件都以控件标签 value读取属性 onChange回写setAttributes的模式工作。wordpress/block-editor块编辑专用组件与 hookspackages/block-editor 是wordpress/block-editor包的源码所在地提供块编辑器专用的组件与 hooks其中既包括上文的自定义设置控件BlockControls、InspectorControls也提供创建和使用独立块编辑器的工具。最常用的组件包括RichText富文本contenteditable输入为用户提供内容格式化能力。其核心 props 包括必填的value可编辑的 HTML 字符串与onChange以及tagName默认div、placeholder、identifier绑定块属性名用于正确维护选区、allowedFormats限制允许的格式如[ core/bold, core/italic ]、onReplace/onMerge/onRemove块级替换、合并、删除行为等。在save函数中应使用RichText.Content正确保存富文本内容。BlockControls块工具栏容器见上文。InspectorControls设置侧边栏容器见上文。InnerBlocks用于在块中启用嵌套内容如列、组、导航等容器块。edit中渲染InnerBlocks /save中渲染InnerBlocks.Content /即会被嵌套块的序列化内容自动替换。常用 props 有allowedBlockstrue允许全部、false禁止全部、数组则仅允许数组内列出的块类型如[ core/image, core/paragraph ]、orientationhorizontal/vertical等。需要注意一个块在edit和save中分别只能渲染一个InnerBlocks/InnerBlocks.Content。使用内置组件的推荐工作流将组件应用于块编辑器时推荐遵循如下工作流从 WordPress 包导入组件如import { BlockControls } from wordpress/block-editor;与import { ToggleControl } from wordpress/components;。以 JSX 形式把对应代码添加到项目中将组件放入Edit函数的返回值中并用useBlockProps包裹块根元素。在block.json中定义必要属性并创建事件处理器大多数内置组件都用于设置块属性因此需要先在block.json的attributes中声明属性类型、默认值、source再在组件上通过onChange等事件处理器调用setAttributes更新属性。例如attributes中声明content、alignment然后在RichText的onChange中调用setAttributes( { content: newContent } )。按需让代码序列化并存入数据库save函数输出的静态标记与block.json中属性的source/selector共同决定内容如何被序列化存储对于富文本使用RichText.Content对于嵌套块使用InnerBlocks.Content。从源码结构看这一工作流与仓库中的实现路径完全吻合wordpress/components的控件负责交互输入wordpress/block-editor的BlockControls/InspectorControls通过 Slot/Fill 把控件注入到编辑器预定义区域setAttributes把新值写回块状态最终由save生成持久化标记。优先使用 block supports 而非自定义控件对于常见的自定义设置——包括颜色color、边框border、间距spacing等——可以依赖block supports而非自行实现控件。在block.json中通过supports声明即可为块启用对应的 UI 设置面板例如{ supports: { color: { background: true, text: true }, border: true, spacing: { margin: true, padding: true } } }block supports 提供的 UI 与核心块保持一致既能保证体验统一又能显著减少自定义代码量。仓库中 lib/block-supports 下的colors.php、border.php、spacing.php、typography.php等文件实现了这些 supports 在服务端的样式解析逻辑而客户端的面板则经由InspectorControls的各分组color、border、dimensions 等渲染。当 supports 无法覆盖需求时再回到BlockControls与InspectorControls编写自定义控件。常见误区与最佳实践小结工具栏与侧边栏的分工工具栏放高频操作与选中内容级设置如加粗、对齐侧边栏只放块级设置HTML 编辑模式下工具栏控件不可见而侧边栏仍然可见这是判断设置归属的关键依据。每个属性都要有归属凡是写入块的状态都应先在block.json的attributes中声明再通过setAttributes更新避免编辑态与保存态数据不一致。优先内建能力颜色、边框、间距、排版等通用设置优先使用 block supports自定义控件只用于业务特有的设置。善用 Storybook 与包内 READMEwordpress/components与wordpress/block-editor中每个组件的 README如 RichText、InnerBlocks、BlockControls、InspectorControls都附有可运行的完整示例是最贴近源码的参考资料。延伸阅读Storybook for WordPress componentswordpress/block-editor 包源码wordpress/components 包源码InspectorControls 实现与 READMEBlockControls 实现与 READMEblock supports 服务端实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gutenberg 块编辑器：用 BlockControls 与 InspectorControls 构建块级设置界面
Gutenberg 块编辑器用 BlockControls 与 InspectorControls 构建块级设置界面【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读本文面向所有使用 GutenbergWordPress 块编辑器开发自定义块的开发者系统讲解块在编辑器中的渲染机制块通过edit属性中的 React 组件呈现在编辑器中开发者可以借助BlockControls块工具栏与InspectorControls设置侧边栏为块定义定制化的设置界面。读完本文你将掌握块Edit组件的props设计、两大内置设置区域的正确用法与适用边界、常用内置组件选型以及块属性从block.json定义、JSX 交互到数据库序列化的完整链路。块在编辑器中的渲染React SPA 与 edit 组件Gutenberg 块编辑器本质上是一个 React 单页应用SPA编辑器中的每一个块都通过一个 React 组件来展示这个组件定义在块类型block type的设置对象settings object的edit属性中。也就是说块在前端/保存端的输出由save决定而块在编辑器里的编辑态预览则由edit决定。块的EditReact 组件接收的props对象至少包含以下核心成员attributes包含该块全部属性的对象数据来自块标记block markup与block.json中attributes的声明类型、默认值、source来源等。setAttributes用于更新attributes对象的方法。它接收一个部分属性对象将变更合并进块的当前属性是驱动编辑交互的核心 API。isSelected布尔值表示块当前是否被选中常用于按选中态渲染不同的 UI例如仅在选中时显示额外控件。WordPress 还内置了大量标准组件可以通过wordpress/components与wordpress/block-editor两个包引入用于快速搭建块编辑界面。Gutenberg 项目还使用 Storybook 对 WordPress 包中可用的 UI 组件进行文档化展示对应文档配置位于仓库的 storybook 目录适合在动手写代码前快速浏览组件的交互效果与 API。一个最小可运行的 Edit 组件在实际项目中块类型通过registerBlockType注册edit函数返回的 JSX 即编辑器中的渲染结果。一个最小可运行的Edit组件形态如下import { useBlockProps } from wordpress/block-editor; export default function Edit( { className, attributes, setAttributes } ) { return ( div { ...useBlockProps() } { /* 块的编辑界面 */ } /div ); }useBlockProps负责把块属性如自定义 class、锚点合并到根元素上保证编辑态标记与保存态标记的一致性。自定义设置界面的两大入口块工具栏与设置侧边栏为了简化块的自定义并保证用户体验一致Gutenberg 提供了若干内置 UI 模式来生成块的编辑器预览。其中最重要的一对是Block Toolbar块工具栏块被选中时在块上方浮现的一排控制按钮。Settings Sidebar设置侧边栏编辑器右侧的设置面板用于承载块级设置。如果块类型的Edit函数返回值中包含了BlockControls元素其内部嵌套的控件就会显示在选中块的工具栏中同理如果返回值中包含InspectorControls元素这些控件就会显示在设置侧边栏区域。当多个同类型的块同时被选中时工具栏与侧边栏中渲染的块控件同样可用。BlockControls 与块工具栏BlockControls位于 packages/block-editor/src/components/block-controls它基于wordpress/components的 Slot/Fill 机制实现BlockControls的index.jsx导出 Fill 组件并挂载Slot工具栏区域通过同名 Slot 接收内容。其内部的groups.js定义了多个分组default、block、inline、other、parent、style-state分别对应工具栏中的不同位置与场景例如inline分组即向后兼容的BlockFormatControls用于行内格式控件。通过BlockControls给块添加对齐控件等工具栏设置的示例export default function Edit( { className, attributes: attr, setAttributes } ) { const onChangeContent ( newContent ) { setAttributes( { content: newContent } ); }; const onChangeAlignment ( newAlignment ) { setAttributes( { alignment: newAlignment undefined ? none : newAlignment, } ); }; return ( div { ...useBlockProps() } BlockControls ToolbarGroup AlignmentToolbar value{ attr.alignment } onChange{ onChangeAlignment } / /ToolbarGroup /BlockControls RichText className{ className } style{ { textAlign: attr.alignment } } tagNamep onChange{ onChangeContent } value{ attr.content } / /div ); }BlockControls的常用 props 包括groupstring默认default控件分组用于创建并渲染多组块控件。controlsarray在使用default分组时覆盖默认控件。childrenElement要渲染的额外控件组件。__experimentalShareWithChildBlocksboolean默认false是否把额外块控件同时添加到子块的工具栏中。需要注意的是BlockControls仅在块当前被选中且处于可视化编辑模式时可见在 HTML 编辑模式下编辑块时工具栏控件不会显示。仓库中 block-controls 的测试用例 验证了动态工具栏的渲染行为通过SlotFillProvider包裹、BlockEdit声明mayDisplayControls最终断言所有对齐按钮可见且携带正确的align属性同时也验证了通过children传入ToolbarGroup controls的另一种写法。InspectorControls 与设置侧边栏设置侧边栏用于展示那些使用频率较低、或者需要更大屏幕空间的设置。设置侧边栏应当只承载块级设置block-level settings且仅在块被选中时显示。如果某个设置只影响块内选中的内容例如加粗文本绝不能放进设置侧边栏而应该使用工具栏。原因在于设置侧边栏即使在 HTML 编辑模式下也会显示因此它只应包含对整个块生效的设置。通过InspectorControls在设置侧边栏中渲染颜色等设置控件的示例export default function Edit( { attributes, setAttributes } ) { const onChangeBGColor ( hexColor ) { setAttributes( { bg_color: hexColor } ); }; const onChangeTextColor ( hexColor ) { setAttributes( { text_color: hexColor } ); }; return ( div { ...useBlockProps() } InspectorControls keysetting div fieldset legend classNameblocks-base-control__label { __( Background color, block-development-examples ) } /legend ColorPalette // Element Tag for Gutenberg standard color selector onChange{ onChangeBGColor } // onChange event callback / /fieldset fieldset legend classNameblocks-base-control__label { __( Text color, block-development-examples ) } /legend ColorPalette onChange{ onChangeTextColor } / /fieldset /div /InspectorControls TextControl value{ attributes.message } onChange{ ( val ) setAttributes( { message: val } ) } style{ { backgroundColor: attributes.bg_color, color: attributes.text_color, } } / /div ); }InspectorControls位于 packages/block-editor/src/components/inspector-controls同样基于 Slot/Fill 实现。与块工具栏类似它的 groups.js 定义了丰富的分组default、advanced、background、border、color、content、dimensions、layout、position、typography、viewport等其中advanced分组即向后兼容导出的InspectorAdvancedControls用于在设置侧边栏的高级Advanced面板中追加 HTML 锚点、自定义 CSS 类等普通用户很少接触的设置。这些分组与block.json中supports生成的面板一一对应是核心块与自定义块设置界面的统一归宿。InspectorAdvancedControls的典型用法如下import { TextControl } from wordpress/components; import { InspectorControls, InspectorAdvancedControls, } from wordpress/block-editor; function MyBlockEdit( { attributes, setAttributes } ) { return ( div{ /* Block markup goes here */ }/div InspectorControls { /* Regular control goes here */ } /InspectorControls InspectorAdvancedControls TextControl labelHTML anchor value{ attributes.anchor } onChange{ ( nextValue ) { setAttributes( { anchor: nextValue } ); } } / /InspectorAdvancedControls / ); }内置组件库wordpress/components 与 wordpress/block-editorwordpress/components通用 UI 元素库packages/components 是wordpress/components包的源码所在地它提供了用于构建块编辑器与 WordPress 后台通用 UI 元素的组件库全部组件都可以在 Storybook 中交互预览。最常用的组件包括TextControl单行文本输入框用于文本类属性如消息内容。Panel/PanelBody可折叠面板容器用于把设置侧边栏中的控件分组收纳InspectorControls中常见的PanelBody title设置即由此而来。ToggleControl开关控件用于布尔属性。ExternalLink带外部链接图标的链接组件。在 InspectorControls 的 README 示例 中CheckboxControl、RadioControl、TextControl、ToggleControl、SelectControl与PanelBody一起构成了完整的设置面板每种控件都以控件标签 value读取属性 onChange回写setAttributes的模式工作。wordpress/block-editor块编辑专用组件与 hookspackages/block-editor 是wordpress/block-editor包的源码所在地提供块编辑器专用的组件与 hooks其中既包括上文的自定义设置控件BlockControls、InspectorControls也提供创建和使用独立块编辑器的工具。最常用的组件包括RichText富文本contenteditable输入为用户提供内容格式化能力。其核心 props 包括必填的value可编辑的 HTML 字符串与onChange以及tagName默认div、placeholder、identifier绑定块属性名用于正确维护选区、allowedFormats限制允许的格式如[ core/bold, core/italic ]、onReplace/onMerge/onRemove块级替换、合并、删除行为等。在save函数中应使用RichText.Content正确保存富文本内容。BlockControls块工具栏容器见上文。InspectorControls设置侧边栏容器见上文。InnerBlocks用于在块中启用嵌套内容如列、组、导航等容器块。edit中渲染InnerBlocks /save中渲染InnerBlocks.Content /即会被嵌套块的序列化内容自动替换。常用 props 有allowedBlockstrue允许全部、false禁止全部、数组则仅允许数组内列出的块类型如[ core/image, core/paragraph ]、orientationhorizontal/vertical等。需要注意一个块在edit和save中分别只能渲染一个InnerBlocks/InnerBlocks.Content。使用内置组件的推荐工作流将组件应用于块编辑器时推荐遵循如下工作流从 WordPress 包导入组件如import { BlockControls } from wordpress/block-editor;与import { ToggleControl } from wordpress/components;。以 JSX 形式把对应代码添加到项目中将组件放入Edit函数的返回值中并用useBlockProps包裹块根元素。在block.json中定义必要属性并创建事件处理器大多数内置组件都用于设置块属性因此需要先在block.json的attributes中声明属性类型、默认值、source再在组件上通过onChange等事件处理器调用setAttributes更新属性。例如attributes中声明content、alignment然后在RichText的onChange中调用setAttributes( { content: newContent } )。按需让代码序列化并存入数据库save函数输出的静态标记与block.json中属性的source/selector共同决定内容如何被序列化存储对于富文本使用RichText.Content对于嵌套块使用InnerBlocks.Content。从源码结构看这一工作流与仓库中的实现路径完全吻合wordpress/components的控件负责交互输入wordpress/block-editor的BlockControls/InspectorControls通过 Slot/Fill 把控件注入到编辑器预定义区域setAttributes把新值写回块状态最终由save生成持久化标记。优先使用 block supports 而非自定义控件对于常见的自定义设置——包括颜色color、边框border、间距spacing等——可以依赖block supports而非自行实现控件。在block.json中通过supports声明即可为块启用对应的 UI 设置面板例如{ supports: { color: { background: true, text: true }, border: true, spacing: { margin: true, padding: true } } }block supports 提供的 UI 与核心块保持一致既能保证体验统一又能显著减少自定义代码量。仓库中 lib/block-supports 下的colors.php、border.php、spacing.php、typography.php等文件实现了这些 supports 在服务端的样式解析逻辑而客户端的面板则经由InspectorControls的各分组color、border、dimensions 等渲染。当 supports 无法覆盖需求时再回到BlockControls与InspectorControls编写自定义控件。常见误区与最佳实践小结工具栏与侧边栏的分工工具栏放高频操作与选中内容级设置如加粗、对齐侧边栏只放块级设置HTML 编辑模式下工具栏控件不可见而侧边栏仍然可见这是判断设置归属的关键依据。每个属性都要有归属凡是写入块的状态都应先在block.json的attributes中声明再通过setAttributes更新避免编辑态与保存态数据不一致。优先内建能力颜色、边框、间距、排版等通用设置优先使用 block supports自定义控件只用于业务特有的设置。善用 Storybook 与包内 READMEwordpress/components与wordpress/block-editor中每个组件的 README如 RichText、InnerBlocks、BlockControls、InspectorControls都附有可运行的完整示例是最贴近源码的参考资料。延伸阅读Storybook for WordPress componentswordpress/block-editor 包源码wordpress/components 包源码InspectorControls 实现与 READMEBlockControls 实现与 READMEblock supports 服务端实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考