Gutenberg 渐变工具集解析Gradients 组件的 slug/value 映射与块渐变支持实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergGutenbergWordPress 块编辑器的Gradients组件位于 packages/block-editor/src/components/gradients它向外暴露一组用于操作渐变gradient调色板的纯函数与 React Hook是 Cover、Featured Image特色图片等块实现渐变背景的核心支撑。阅读本文后你将掌握渐变数据的 slug↔value 双向转换原理、__experimentalUseGradient在真实块内的读写链路以及 PHP 端如何为编辑器提供渐变调色板设置。组件定位与导出入口Gradients模块的官方定义只有一句话TheGradientscomponent exposes tools for working with gradients即提供一组操作渐变的工具而非某个具体的 UI 控件。其目录结构十分精简README.mdAPI 文档即本文讲解的主体index.js仅一行export * from ./use-gradient;统一对外出口use-gradient.js全部实现所在。通过 block-editor 包的主 README 可以看出该模块的__experimentalUseGradient、__experimentalGetGradientClass等均以__experimental前缀对外暴露属于实验性 API——意味着其签名在后续版本中可能调整第三方开发者在生产代码中引用时需要评估兼容性风险。核心 APIslug 与 value 的双向转换README 文档收录了两个纯函数它们构成了渐变调色板数据与块属性数据之间的桥梁。理解它们之前先明确两个概念gradient valueCSS 渐变字符串如linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)gradient slug调色板中为渐变定义的唯一标识符如vivid-cyan-blue-to-vivid-purple。块属性中存储的是slug紧凑、可移植、便于生成语义化 class而真正渲染到样式表/CSS 变量中的是value因此两个方向都需要转换函数。getGradientSlugByValue由 value 反查 slugexport function getGradientSlugByValue( gradients, value ) { const gradient __experimentalGetGradientObjectByGradientValue( gradients, value ); return gradient gradient.slug; }参数gradientsArray渐变调色板元素形如{ slug: vivid-cyan-blue-to-vivid-purple, gradient: linear-gradient(...), name: ... }参数valuestring要反查的渐变值返回值string匹配项的slug未命中时返回undefined__experimentalGetGradientObjectByGradientValue通过gradients?.find( ( g ) g.gradient value )做严格相等匹配源码见 use-gradient.js。典型用法用户通过渐变选择器选中一个自定义渐变值组件需要判断它是否命中调色板中的某个预设项——命中则存 slug未命中则作为自定义渐变单独存储详见下文__experimentalUseGradient。getGradientValueBySlug由 slug 反查 valueexport function getGradientValueBySlug( gradients, slug ) { const gradient gradients?.find( ( g ) g.slug slug ); return gradient gradient.gradient; }参数gradientsArray渐变调色板参数slugstring渐变 slug返回值string对应的渐变值未命中时返回undefined。典型用法块属性中已存有gradientslug渲染时需要还原为实际 CSS 渐变值。配套导出__experimentalGetGradientClassuse-gradient.js还导出了一个文档中未单独列出、但被 color 块支持钩子广泛使用的工具函数export function __experimentalGetGradientClass( gradientSlug ) { if ( ! gradientSlug ) { return undefined; } return has-${ gradientSlug }-gradient-background; }它根据 slug 生成语义化 CSS 类名如has-vivid-cyan-blue-to-vivid-purple-gradient-background该 class 由主题或 Gutenberg 的渐变样式表提供实际background渐变声明。源码见 use-gradient.js。__experimentalUseGradient编辑器中读写渐变属性的 HookuseGradient是模块中唯一的 React Hook以__experimentalUseGradient导出它把「从全局设置读取调色板」「从块属性读取当前渐变」「写入属性」三件事封装成一个易于消费的接口。数据来源三源合并的渐变调色板Hook 通过useSettings同时订阅三类来源的渐变设置源码见 use-gradient.jsconst [ userGradientPalette, themeGradientPalette, defaultGradientPalette, ] useSettings( color.gradients.custom, color.gradients.theme, color.gradients.default ); const allGradients useMemo( () [ ...( userGradientPalette || [] ), ...( themeGradientPalette || [] ), ...( defaultGradientPalette || [] ), ], [ userGradientPalette, themeGradientPalette, defaultGradientPalette ] );这三层来源分别对应 WordPress 主题 JSON 中的分级配置color.gradients.default内核默认渐变调色板color.gradients.theme主题定义的渐变调色板color.gradients.custom用户在站点编辑器中自定义的渐变。合并顺序为 custom → theme → default后者兜底。这种「多来源multiple origins」的设计在 block-editor 中也被useMultipleOriginColorsAndGradients组件复用以渲染完整选择器详见 use-multiple-origin-colors-and-gradients.jscolors-gradients 目录为渐变选择 UI 的主战场。读写块属性slug 与自定义渐变的双属性策略const { gradient, customGradient } useSelect( ( select ) { const { getBlockAttributes } select( blockEditorStore ); const attributes getBlockAttributes( clientId ) || {}; return { customGradient: attributes[ customGradientAttribute ], gradient: attributes[ gradientAttribute ], }; }, [ clientId, gradientAttribute, customGradientAttribute ] );Hook 默认读取两个属性可通过gradientAttribute/customGradientAttribute参数覆盖默认分别为gradient与customGradientgradient命中的预设渐变 slugcustomGradient未命中调色板的原始 CSS 渐变字符串。setGradient回调源码见 use-gradient.js体现了完整的写入策略const setGradient useCallback( ( newGradientValue ) { const slug getGradientSlugByValue( allGradients, newGradientValue ); if ( slug ) { updateBlockAttributes( clientId, { [ gradientAttribute ]: slug, [ customGradientAttribute ]: undefined, } ); return; } updateBlockAttributes( clientId, { [ gradientAttribute ]: undefined, [ customGradientAttribute ]: newGradientValue, } ); }, [ allGradients, clientId, updateBlockAttributes ] );即新值能匹配到调色板中的预设项 → 存 slug、清空自定义值匹配不到 → 清空 slug、将原始值存入 customGradient。这种双属性策略让预设渐变保持语义化、可主题化而自定义渐变保留用户原始的 CSS 表达式。返回值Hook 最终返回三个字段gradientClass由__experimentalGetGradientClass( gradient )生成的语义化 classgradientValue优先通过getGradientValueBySlug( allGradients, gradient )把 slug 还原为 value否则回退为customGradient原始值setGradient上述写入回调。由于 hook 内部调用useBlockEditContext()获取当前块的clientId它只能工作于正在编辑的块上下文如块编辑组件内部这与getGradientValueBySlug等纯函数可在任意环境使用的特性互补。真实落地Cover 与 Featured Image 块的集成方式Gradients模块并非孤立的工具代码而是被 block-library 中的多个块深度使用以下选取两个典型场景印证调用链。Cover 块编辑与保存双端使用Cover 块的属性定义中包含gradient与customGradient两个字符串属性并在 block supports 中开启color: { ..., background: false, __experimentalSkipSerialization: [ gradients ] }见 block.json。在编辑端edit/index.jsx 调用const { gradientClass, gradientValue } __experimentalUseGradient();获取当前渐变的 class 与真实值用于渲染编辑器内的预览背景edit/inspector-controls.jsx 调用const { gradientValue, setGradient } __experimentalUseGradient();并把二者绑定到ColorGradientSettingsDropdown用户在选择器中切换渐变时即调用setGradient写入块属性保存端 save.jsx 通过__experimentalGetGradientClass( gradient )生成has-{slug}-gradient-background类名输出到前端 HTML。此外 Cover 块所有历史版本的 deprecated.jsx 也都使用__experimentalGetGradientClass还原旧版本保存结构保证迁移兼容。Featured Image特色图片块覆盖层渐变overlay.jsx 中const { gradientClass, gradientValue } __experimentalUseGradient();读取当前渐变将其应用到图片覆盖层overlay-controls.jsx 别名引入__experimentalUseGradient as useGradient同样配合ColorGradientSettingsDropdown渲染设置 UI。颜色块支持钩子序列化与内联样式Gradients的另一类消费者是 hooks/color.js 与 hooks/use-color-props.jscolor.js 在addSaveProps中调用__experimentalGetGradientClass( gradient )向保存元素注入渐变 class同时通过shouldSkipSerialization控制是否跳过gradients特性的序列化Cover 块的 block.json 正是利用这一点自行处理渐变输出use-color-props.js 中当块属性携带gradientslug 时调用getGradientValueBySlug( gradients, gradient )将 slug 解析为真实 CSS 渐变并强制写入style.background内联样式——注释说明这是为了在主题未加载颜色样式表时编辑器内仍能正确呈现渐变。PHP 侧数据供给渐变调色板如何进入编辑器编辑器端useSettings(color.gradients.*)读取的设置来自 PHP 端对主题 JSON 特性的展开。相关证据在 lib/block-editor-settings.phpif ( isset( $settings[__experimentalFeatures][color][gradients] ) ) { $gradients_by_origin $settings[__experimentalFeatures][color][gradients]; $settings[gradients] $gradients_by_origin[custom] ?? $gradients_by_origin[theme] ?? $gradients_by_origin[default]; }可见 PHP 端按 custom → theme → default 的优先级把三级渐变调色板聚合到settings.gradients与前端allGradients的合并策略保持一致前端按 custom → theme → default 顺序拼接数组PHP 则取最高优先级来源。同时服务端渐变支持逻辑位于 lib/block-supports/colors.php其中$has_gradients_support $color_support[gradients] ?? false;判断块是否开启渐变支持并据此注入gradient属性定义、渲染输出渐变 class。总结与使用建议Gradients模块提供了三层能力能力导出名称适用场景纯函数slug ↔ value 转换getGradientSlugByValue/getGradientValueBySlug任意位置解析渐变调色板数据纯函数生成渐变 class__experimentalGetGradientClass保存端 / 块支持钩子生成has-{slug}-gradient-backgroundReact Hook读写块渐变属性__experimentalUseGradient块编辑组件内联动属性与选择器 UI对第三方块开发者而言若要为自定义块接入渐变背景可遵循 Cover 块的模式在 block.json 中声明gradient/customGradient属性并开启color.gradients支持然后在编辑组件内调用__experimentalUseGradient()绑定选择器 UI。需要留意的是__experimental前缀意味着 API 仍处于实验阶段升级 Gutenberg 版本时应对照 block-editor 包 CHANGELOG 确认签名变更。【免费下载链接】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 渐变工具集解析：Gradients 组件的 slug/value 映射与块渐变支持实现
Gutenberg 渐变工具集解析Gradients 组件的 slug/value 映射与块渐变支持实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergGutenbergWordPress 块编辑器的Gradients组件位于 packages/block-editor/src/components/gradients它向外暴露一组用于操作渐变gradient调色板的纯函数与 React Hook是 Cover、Featured Image特色图片等块实现渐变背景的核心支撑。阅读本文后你将掌握渐变数据的 slug↔value 双向转换原理、__experimentalUseGradient在真实块内的读写链路以及 PHP 端如何为编辑器提供渐变调色板设置。组件定位与导出入口Gradients模块的官方定义只有一句话TheGradientscomponent exposes tools for working with gradients即提供一组操作渐变的工具而非某个具体的 UI 控件。其目录结构十分精简README.mdAPI 文档即本文讲解的主体index.js仅一行export * from ./use-gradient;统一对外出口use-gradient.js全部实现所在。通过 block-editor 包的主 README 可以看出该模块的__experimentalUseGradient、__experimentalGetGradientClass等均以__experimental前缀对外暴露属于实验性 API——意味着其签名在后续版本中可能调整第三方开发者在生产代码中引用时需要评估兼容性风险。核心 APIslug 与 value 的双向转换README 文档收录了两个纯函数它们构成了渐变调色板数据与块属性数据之间的桥梁。理解它们之前先明确两个概念gradient valueCSS 渐变字符串如linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)gradient slug调色板中为渐变定义的唯一标识符如vivid-cyan-blue-to-vivid-purple。块属性中存储的是slug紧凑、可移植、便于生成语义化 class而真正渲染到样式表/CSS 变量中的是value因此两个方向都需要转换函数。getGradientSlugByValue由 value 反查 slugexport function getGradientSlugByValue( gradients, value ) { const gradient __experimentalGetGradientObjectByGradientValue( gradients, value ); return gradient gradient.slug; }参数gradientsArray渐变调色板元素形如{ slug: vivid-cyan-blue-to-vivid-purple, gradient: linear-gradient(...), name: ... }参数valuestring要反查的渐变值返回值string匹配项的slug未命中时返回undefined__experimentalGetGradientObjectByGradientValue通过gradients?.find( ( g ) g.gradient value )做严格相等匹配源码见 use-gradient.js。典型用法用户通过渐变选择器选中一个自定义渐变值组件需要判断它是否命中调色板中的某个预设项——命中则存 slug未命中则作为自定义渐变单独存储详见下文__experimentalUseGradient。getGradientValueBySlug由 slug 反查 valueexport function getGradientValueBySlug( gradients, slug ) { const gradient gradients?.find( ( g ) g.slug slug ); return gradient gradient.gradient; }参数gradientsArray渐变调色板参数slugstring渐变 slug返回值string对应的渐变值未命中时返回undefined。典型用法块属性中已存有gradientslug渲染时需要还原为实际 CSS 渐变值。配套导出__experimentalGetGradientClassuse-gradient.js还导出了一个文档中未单独列出、但被 color 块支持钩子广泛使用的工具函数export function __experimentalGetGradientClass( gradientSlug ) { if ( ! gradientSlug ) { return undefined; } return has-${ gradientSlug }-gradient-background; }它根据 slug 生成语义化 CSS 类名如has-vivid-cyan-blue-to-vivid-purple-gradient-background该 class 由主题或 Gutenberg 的渐变样式表提供实际background渐变声明。源码见 use-gradient.js。__experimentalUseGradient编辑器中读写渐变属性的 HookuseGradient是模块中唯一的 React Hook以__experimentalUseGradient导出它把「从全局设置读取调色板」「从块属性读取当前渐变」「写入属性」三件事封装成一个易于消费的接口。数据来源三源合并的渐变调色板Hook 通过useSettings同时订阅三类来源的渐变设置源码见 use-gradient.jsconst [ userGradientPalette, themeGradientPalette, defaultGradientPalette, ] useSettings( color.gradients.custom, color.gradients.theme, color.gradients.default ); const allGradients useMemo( () [ ...( userGradientPalette || [] ), ...( themeGradientPalette || [] ), ...( defaultGradientPalette || [] ), ], [ userGradientPalette, themeGradientPalette, defaultGradientPalette ] );这三层来源分别对应 WordPress 主题 JSON 中的分级配置color.gradients.default内核默认渐变调色板color.gradients.theme主题定义的渐变调色板color.gradients.custom用户在站点编辑器中自定义的渐变。合并顺序为 custom → theme → default后者兜底。这种「多来源multiple origins」的设计在 block-editor 中也被useMultipleOriginColorsAndGradients组件复用以渲染完整选择器详见 use-multiple-origin-colors-and-gradients.jscolors-gradients 目录为渐变选择 UI 的主战场。读写块属性slug 与自定义渐变的双属性策略const { gradient, customGradient } useSelect( ( select ) { const { getBlockAttributes } select( blockEditorStore ); const attributes getBlockAttributes( clientId ) || {}; return { customGradient: attributes[ customGradientAttribute ], gradient: attributes[ gradientAttribute ], }; }, [ clientId, gradientAttribute, customGradientAttribute ] );Hook 默认读取两个属性可通过gradientAttribute/customGradientAttribute参数覆盖默认分别为gradient与customGradientgradient命中的预设渐变 slugcustomGradient未命中调色板的原始 CSS 渐变字符串。setGradient回调源码见 use-gradient.js体现了完整的写入策略const setGradient useCallback( ( newGradientValue ) { const slug getGradientSlugByValue( allGradients, newGradientValue ); if ( slug ) { updateBlockAttributes( clientId, { [ gradientAttribute ]: slug, [ customGradientAttribute ]: undefined, } ); return; } updateBlockAttributes( clientId, { [ gradientAttribute ]: undefined, [ customGradientAttribute ]: newGradientValue, } ); }, [ allGradients, clientId, updateBlockAttributes ] );即新值能匹配到调色板中的预设项 → 存 slug、清空自定义值匹配不到 → 清空 slug、将原始值存入 customGradient。这种双属性策略让预设渐变保持语义化、可主题化而自定义渐变保留用户原始的 CSS 表达式。返回值Hook 最终返回三个字段gradientClass由__experimentalGetGradientClass( gradient )生成的语义化 classgradientValue优先通过getGradientValueBySlug( allGradients, gradient )把 slug 还原为 value否则回退为customGradient原始值setGradient上述写入回调。由于 hook 内部调用useBlockEditContext()获取当前块的clientId它只能工作于正在编辑的块上下文如块编辑组件内部这与getGradientValueBySlug等纯函数可在任意环境使用的特性互补。真实落地Cover 与 Featured Image 块的集成方式Gradients模块并非孤立的工具代码而是被 block-library 中的多个块深度使用以下选取两个典型场景印证调用链。Cover 块编辑与保存双端使用Cover 块的属性定义中包含gradient与customGradient两个字符串属性并在 block supports 中开启color: { ..., background: false, __experimentalSkipSerialization: [ gradients ] }见 block.json。在编辑端edit/index.jsx 调用const { gradientClass, gradientValue } __experimentalUseGradient();获取当前渐变的 class 与真实值用于渲染编辑器内的预览背景edit/inspector-controls.jsx 调用const { gradientValue, setGradient } __experimentalUseGradient();并把二者绑定到ColorGradientSettingsDropdown用户在选择器中切换渐变时即调用setGradient写入块属性保存端 save.jsx 通过__experimentalGetGradientClass( gradient )生成has-{slug}-gradient-background类名输出到前端 HTML。此外 Cover 块所有历史版本的 deprecated.jsx 也都使用__experimentalGetGradientClass还原旧版本保存结构保证迁移兼容。Featured Image特色图片块覆盖层渐变overlay.jsx 中const { gradientClass, gradientValue } __experimentalUseGradient();读取当前渐变将其应用到图片覆盖层overlay-controls.jsx 别名引入__experimentalUseGradient as useGradient同样配合ColorGradientSettingsDropdown渲染设置 UI。颜色块支持钩子序列化与内联样式Gradients的另一类消费者是 hooks/color.js 与 hooks/use-color-props.jscolor.js 在addSaveProps中调用__experimentalGetGradientClass( gradient )向保存元素注入渐变 class同时通过shouldSkipSerialization控制是否跳过gradients特性的序列化Cover 块的 block.json 正是利用这一点自行处理渐变输出use-color-props.js 中当块属性携带gradientslug 时调用getGradientValueBySlug( gradients, gradient )将 slug 解析为真实 CSS 渐变并强制写入style.background内联样式——注释说明这是为了在主题未加载颜色样式表时编辑器内仍能正确呈现渐变。PHP 侧数据供给渐变调色板如何进入编辑器编辑器端useSettings(color.gradients.*)读取的设置来自 PHP 端对主题 JSON 特性的展开。相关证据在 lib/block-editor-settings.phpif ( isset( $settings[__experimentalFeatures][color][gradients] ) ) { $gradients_by_origin $settings[__experimentalFeatures][color][gradients]; $settings[gradients] $gradients_by_origin[custom] ?? $gradients_by_origin[theme] ?? $gradients_by_origin[default]; }可见 PHP 端按 custom → theme → default 的优先级把三级渐变调色板聚合到settings.gradients与前端allGradients的合并策略保持一致前端按 custom → theme → default 顺序拼接数组PHP 则取最高优先级来源。同时服务端渐变支持逻辑位于 lib/block-supports/colors.php其中$has_gradients_support $color_support[gradients] ?? false;判断块是否开启渐变支持并据此注入gradient属性定义、渲染输出渐变 class。总结与使用建议Gradients模块提供了三层能力能力导出名称适用场景纯函数slug ↔ value 转换getGradientSlugByValue/getGradientValueBySlug任意位置解析渐变调色板数据纯函数生成渐变 class__experimentalGetGradientClass保存端 / 块支持钩子生成has-{slug}-gradient-backgroundReact Hook读写块渐变属性__experimentalUseGradient块编辑组件内联动属性与选择器 UI对第三方块开发者而言若要为自定义块接入渐变背景可遵循 Cover 块的模式在 block.json 中声明gradient/customGradient属性并开启color.gradients支持然后在编辑组件内调用__experimentalUseGradient()绑定选择器 UI。需要留意的是__experimental前缀意味着 API 仍处于实验阶段升级 Gutenberg 版本时应对照 block-editor 包 CHANGELOG 确认签名变更。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考