★ FEATURED ARTICLE Gutenberg PanelColorSettings 组件完全指南在 WordPress 块编辑器中构建颜色设置面板【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读PanelColorSettings是 GutenbergWordPress 块编辑器核心wordpress/block-editor包中用于管理颜色设置界面的 React 组件。它可以在一处集中渲染文本色、背景色等多个颜色选择器本质上是PanelColorGradientSettings的简化包装自动关闭渐变Gradient功能。本指南将以 PanelColorSettings 官方文档 为主体结合仓库源码与真实块实现带你掌握该组件的用法、全部 Props 语义、内部工作链路以及在实际块如导航块中的落地模式。组件概览与定位PanelColorSettings渲染一个用于管理多种颜色设置的 UI。从源码看它位于 packages/block-editor/src/components/panel-color-settings/index.jsx整个实现非常精简import PanelColorGradientSettings from ../colors-gradients/panel-color-gradient-settings; const PanelColorSettings ( { colorSettings, ...props } ) { const settings colorSettings.map( ( setting ) { if ( ! setting ) { return setting; } const { value, onChange, ...otherSettings } setting; return { ...otherSettings, colorValue: value, onColorChange: onChange, }; } ); return ( PanelColorGradientSettings settings{ settings } gradients{ [] } disableCustomGradients { ...props } / ); }; export default PanelColorSettings;关键信息一目了然它是纯包装组件内部调用PanelColorGradientSettings将colorSettings数组中每项的value/onChange重命名为底层组件期望的colorValue/onColorChange该逻辑见 panel-color-gradient-settings.jsx。它强制禁用渐变始终传入gradients{ [] }与disableCustomGradients这正是文档所说specifically disables the gradient features的源码依据——PanelColorSettings是一个纯粹的仅颜色面板。从源码结构还可以推断colorSettings数组中的每一项都会被原样透传因此你可以在单个设置项上叠加额外字段例如colors、disableCustomColors、enableAlpha、clearable等这些字段会被合并进最终的控件配置见下文ColorGradientControl的{ ...setting }展开。基础用法与完整示例PanelColorSettings从wordpress/block-editor导出配合wordpress/i18n的__()做文案国际化。官方文档给出的最小可用示例README.md如下import { useState } from react; import { PanelColorSettings } from wordpress/block-editor; import { __ } from wordpress/i18n; // ... const MyPanelColorSettings () { const [ textColor, setTextColor ] useState( { color: #000 } ); const [ backgroundColor, setBackgroundColor ] useState( { color: #fff, } ); const [ overlayTextColor, setOverlayTextColor ] useState( { color: #000, } ); const [ overlayBackgroundColor, setOverlayBackgroundColor ] useState( { color: #eee, } ); return ( PanelColorSettings __experimentalIsRenderedInSidebar title{ __( Color ) } colorSettings{ [ { value: textColor.color, onChange: setTextColor, label: __( Text ), }, { value: backgroundColor.color, onChange: setBackgroundColor, label: __( Background ), }, { value: overlayTextColor.color, onChange: setOverlayTextColor, label: __( Submenu overlay text ), }, { value: overlayBackgroundColor.color, onChange: setOverlayBackgroundColor, label: __( Submenu overlay background ), }, ] } / ); }; /// ... MyPanelColorSettings /;用法要点每个颜色设置项由value当前颜色值CSS 颜色字符串、onChange颜色变更回调、label设置项标题三元组构成title是面板标题与块设置侧栏Inspector中的常规面板如颜色对应__experimentalIsRenderedInSidebar用于声明面板渲染在侧栏中影响弹出层的定位策略见下文。Props 完整说明组件接受两类 Props专属的colorSettings以及一组直接透传给底层PanelColorGradientSettings的 Props。colorSettings用户提供的颜色设置集合类型为Array非必填。每个设置项遵循如下 SchemaREADME.md属性说明类型value该设置项当前的颜色值stringonChange颜色变化时的回调Functionlabel该设置项的标签string值得补充的是从 index.jsx 的{ ...otherSettings }展开可见每个设置项除这三元组外还可以携带任意扩展字段例如clearable、enableAlpha、colors、disableCustomColors、resetAllFilter等它们会被合并进底层ColorGradientControl的controlProps见 dropdown.jsx 中的...setting展开实现按项定制。另外源码对空项做了容错colorSettings.map中if ( ! setting ) return setting;即数组中可以存在null/undefined占位项渲染时也会被setting 短路跳过见 dropdown.jsx。透传给 PanelColorGradientSettings 的 Props以下 Props 会被原样传递到底层组件实例具体语义如下README.mdProp说明className追加到底层ToolsPanel实例的 class 上colors可供选择的颜色数组gradients不建议使用——PanelColorSettings会将其重置为[]disableCustomColors是否允许用户添加自定义颜色disableCustomGradients不建议使用——PanelColorSettings会强制设置它children渲染在底层PanelColorGradientSettings实例下方的子元素settings不建议使用——PanelColorSettings会依据colorSettings自行构建title底层ToolsPanel的标题showTitle是否显示ToolsPanel标题__experimentalIsRenderedInSidebar标记渲染位置在侧栏enableAlpha指定颜色时是否启用透明度opacity设置源码印证gradients/disableCustomGradients被硬编码覆盖见 index.jsx 中的gradients{ [] }与disableCustomGradientsclassName会通过clsx( block-editor-panel-color-gradient-settings, className )合并到底层ToolsPanel见 panel-color-gradient-settings.jsxtitle/showTitle最终作用于ToolsPanel的label属性showTitle为false时不传label。关于更多细节文档明确建议参考PanelColorGradientSettings组件本身panel-color-gradient-settings.jsx。源码级原理从 colorSettings 到颜色选择器为了让你理解每个 Props 背后发生了什么这里梳理完整的调用链对应文件均在 packages/block-editor/src/components/colors-gradients 目录下PanelColorSettingsindex.jsx将colorSettings归一化为{ colorValue, onColorChange, ... }结构强制gradients{ [] }、disableCustomGradients然后调用PanelColorGradientSettings。PanelColorGradientSettingspanel-color-gradient-settings.jsx通过useMultipleOriginColorsAndGradients()见 use-multiple-origin-colors-and-gradients.js读取主题/默认/自定义三来源的调色板并计算disableCustomColors/disableCustomGradients对应 theme.json 的color.custom、color.palette.*等设置渲染一个__experimentalToolsPanel为每个设置项生成ToolsPanelItemresetAll回调使用useRegistry().batch批量执行所有onColorChange()/onGradientChange()实现一键重置全部颜色。ColorGradientSettingsDropdowndropdown.jsx将每个设置项渲染为带ColorIndicator颜色指示器 标签的Button触发器点击后弹出Dropdownclearable项在已有颜色值时额外显示重置按钮当__experimentalIsRenderedInSidebar为真时弹出层采用placement: left-start、offset: 36、shift: true的定位策略避免溢出侧栏。ColorGradientControlcontrol.jsx在弹出层中渲染ColorPalette颜色与GradientPicker渐变双 Tab。由于PanelColorSettings禁用了渐变这里只会展示颜色面板。空渲染守卫如果没有任何可用的颜色既无预设调色板、又禁用了自定义颜色、且每个设置项也没有自己的colorsPanelColorGradientSettingsInner会直接返回null整块面板不渲染。该逻辑见 panel-color-gradient-settings.jsx 第 33-49 行。测试用例与行为契约组件测试位于 packages/block-editor/src/components/panel-color-settings/test/index.jsdom.test.jsx它界定了几个关键行为可作为你使用时的行为契约无可用颜色时不渲染任何内容当colors{ [] }且disableCustomColors即使colorSettings有两项组件也输出空 DOMcontainer为空元素任一设置项开启自定义颜色时渲染在colorSettings的某一项设置disableCustomColors: false面板即可渲染任一设置项自带颜色列表时渲染在设置项中提供colors: [ { slug, name, color } ]与 theme.json 调色板结构一致面板即可渲染全部设置项都无颜色可选时不渲染即使面板级disableCustomColors{ false }只要每个设置项自身colors: []且disableCustomColors: true同样不渲染。这些用例直接对应上述空渲染守卫逻辑说明面板是否可见取决于面板级设置与每个设置项级设置的综合结果。真实世界应用导航块的颜色面板PanelColorSettings并非孤立组件它的设计理念在仓库真实块中得到了直接应用。以导航块Navigation为例packages/block-library/src/navigation/edit/index.jsx 中的NavigationMenuInspectorControls使用ColorGradientSettingsDropdown即PanelColorSettings的底层组件构建了完全一致的四色设置Text、Background、Submenu overlay text、Submenu overlay background。该真实实现展示了设置项可以携带比文档三元组更丰富的字段与PanelColorSettings的{ ...otherSettings }透传机制兼容const colorSettings [ { colorValue: textColor.color, label: __( Text ), onColorChange: setTextColor, resetAllFilter: () setTextColor(), clearable: true, enableAlpha: true, }, { colorValue: backgroundColor.color, label: __( Background ), onColorChange: setBackgroundColor, resetAllFilter: () setBackgroundColor(), clearable: true, enableAlpha: true, }, // 仅在非 overlay 模板中追加 overlay 相关颜色项 ];同时它使用useMultipleOriginColorsAndGradients()读取三来源调色板并在hasColorsOrGradients为假时直接返回null与空渲染守卫思路一致。实践启示如果你的自定义块需要类似文本色 背景色 子菜单色的多色管理面板直接照搬这一模式即可。版本兼容性与弃用提示仓库中 packages/editor/src/components/deprecated.jsx 显示wordpress/editor曾导出过同名的PanelColorSettings但从 5.3 版本起已被标记为deprecated官方建议改用wp.blockEditor.PanelColorSettings即从wordpress/block-editor导入。在编写新代码时请务必从wordpress/block-editor导入。最佳实践小结纯色管理场景首选不需要渐变时用PanelColorSettings比直接操作PanelColorGradientSettings更简洁它自动关掉渐变状态驱动颜色值颜色值应存放在块属性或本地 state 中value与onChange一一对应保持单向数据流善用按项定制通过设置项内嵌colors/disableCustomColors/enableAlpha/clearable等字段可以实现某些项用主题色板、某些项开放自定义的精细控制注意空面板行为面板在无任何可用颜色时自动隐藏无需你手动做条件渲染国际化所有label与title均通过__()包裹保证多语言站点可用侧栏渲染在 Inspector 中使用时始终带上__experimentalIsRenderedInSidebar以获得正确的弹出层定位。通过本文你应能直接在自定义块中使用PanelColorSettings构建专业的多颜色设置面板并理解其与底层PanelColorGradientSettings、ToolsPanel、ColorPalette的协作机制必要时还能深入 packages/block-editor/src/components/colors-gradients 目录自行扩展。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
