Ant Design ColorPicker 颜色选择器实战指南API 全解析、渐变模式与 Color 对象实现原理【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designColorPicker颜色选择器是 Ant Design 自5.5.0起内置的数据录入组件用于用户在界面中自定义选择颜色底层基于rc-component/color-picker并在外层封装了 Popover 弹出、模式切换、预设色板与透明度控制。读完本文你将掌握其全部 Props 的取值与默认值、Color对象的格式转换方法、受控场景下的正确赋值方式以及单色/渐变5.20.0模式的实现原理与源码位置。何时使用与组件定位组件文档index.zh-CN.md给出的使用场景非常直接当用户需要自定义颜色选择的时候使用。它归属于 Ant Design 组件体系中的数据录入分组与Select、DatePicker一样支持受控value/onChange与非受控defaultValue两种用法可嵌入Form中参与校验。从源码结构看组件由三部分拼装而成见 ColorPicker.tsx触发器默认渲染 ColorTrigger一个展示当前颜色块的按钮也可通过children传入自定义触发元素弹出层直接使用 Ant Design 的Popover见ColorPicker.tsx中popoverProps的组装因此继承placement、trigger、getPopupContainer、autoAdjustOverflow等 Popover 能力选择面板ColorPickerPanel 内部由PanelPicker色板、滑杆、输入框与PanelPresets预设色组成二者通过 Context 共享状态并支持panelRender二次定制。官方提供 15 个可运行 Demo覆盖基本用法到 Pure Render 的全部场景源码位于 components/color-picker/demo/Demo说明base.tsx基本使用size.tsx触发器尺寸大小controlled.tsx受控模式change-completed.tsx颜色完成选择onChangeCompleteline-gradient.tsx渐变色5.20.0text-render.tsx渲染触发器文本disabled.tsx禁用disabled-alpha.tsx禁用透明度allowClear.tsx清除颜色trigger.tsx自定义触发器trigger-event.tsx自定义触发事件format.tsx颜色编码presets.tsx预设颜色panel-render.tsx自定义面板pure-panel.tsxPure Render基本使用与受控模式最简用法只需一个defaultValueimport React from react; import { ColorPicker } from antd; const Demo () ColorPicker defaultValue#1677ff /; export default Demo;受控模式则配合value与onChange。由于onChange回调的第一个参数是Color对象而非字符串官方 Democontrolled.tsx演示了推荐的类型写法import { useState } from react; import { ColorPicker } from antd; import type { ColorPickerProps, GetProp } from antd; type Color GetPropColorPickerProps, value; const Demo: React.FC () { const [color, setColor] useStateColor(#1677ff); return ColorPicker value{color} onChange{setColor} /; };在受控组件中颜色值同时接受字符串如#1677ff、hsb(215, 91%, 100%)和Color对象。源码中任何传入值都会经过 generateColor 统一包装为AggregationColor实例见 color.ts因此两种写法都能工作——但官方 FAQ 特别提醒不同格式的颜色字符串互相转换会有精度误差受控场景推荐使用选择器生成的Color对象来赋值以保证取值精准、选择器按预期工作。组件的公开导出index.tsx也印证了这一点它把AggregationColor以Color的类型名对外导出ColorPickerProps也同步导出方便业务侧声明状态类型。颜色编码format 与 Color 对象的方法族format默认hex决定面板中显示哪种输入框hex显示单行 HEX 输入rgb显示三通道加透明度的输入组hsb显示 HSB 输入组。非受控场景可用defaultFormat5.9.0设置初始格式受控场景用formatonFormatChange同步状态。format.tsx 对三种格式分别给出完整示例const [colorHex, setColorHex] useStateColor(#1677ff); const [formatHex, setFormatHex] useStateFormat | undefined(hex); const hexString React.useMemostring( () (typeof colorHex string ? colorHex : colorHex?.toHexString()), [colorHex], ); ColorPicker format{formatHex} value{colorHex} onChange{setColorHex} onFormatChange{setFormatHex} / spanHEX: {hexString}/span测试用例 index.test.tsx 中的Should format change work验证了面板内格式下拉框在 HEX → HSB → RGB 之间切换时DOM 会相应渲染.ant-color-picker-hsb-input与.ant-color-picker-rgb-input。Color对象AggregationColor类提供了完整的格式转换 API方法说明返回示例toCssString转换成 CSS 支持的格式5.20.0rgb(22, 119, 255)或渐变linear-gradient(...)toHex转换成hex格式字符不带#1677fftoHexString转换成hex格式颜色字符串#1677fftoHsb转换成hsb对象({ h, s, b, a })toHsbString转换成hsb格式颜色字符串hsb(215, 91%, 100%)toRgb转换成rgb对象({ r, g, b, a })toRgbString转换成rgb格式颜色字符串rgb(22, 119, 255)从源码实现看color.ts这些方法大部分是对rc-component/color-picker中RcColor的透传toHex额外经过 color.ts 中toHexFormat的正则清洗value.replace(/[^\w/]/gi, ).slice(0, alpha ? 8 : 6)因此带透明度的颜色会返回 8 位 hex。toCssString则是渐变特性的关键当对象承载渐变内部colors数组存在且未被清除时它把各停靠点拼接为linear-gradient(90deg, rgb(...) x%, rgb(...) y%)单色时直接返回toRgbString()。触发器定制children、showText 与 size不传children时触发器是内置的颜色块ColorTrigger内部由showText控制是否显示当前颜色文本。showText支持布尔或函数两种形式// 布尔显示当前格式的颜色字符串 ColorPicker defaultValue#1677ff showText / // 函数完全自定义文本text-render demo ColorPicker defaultValue#1677ff showText{(color) spanCustom Text ({color.toHexString()})/span} /showText函数形式在测试中得到了明确验证传入#1677ff且面板打开时切换格式后触发器文本会跟随变为hsb(215, 91%, 100%)、rgb(22,119,255)、#1677FF当值为null且开启showText时显示Transparent见 index.test.tsx 中Should showText work与showText with transparent两个用例。size5.7.0控制触发器大小取值large/middle默认/small对应类名ant-color-picker-lg/ant-color-picker-sm未显式指定时还会继承ConfigProvider的size与Space.Compact的紧凑尺寸useSize((ctx) customizeSize ?? compactSize ?? ctx)见 ColorPicker.tsx。自定义触发器则是把任意节点放进children触发器本身的样式交给该节点颜色选择面板照常弹出。trigger.tsx 展示了用按钮作为触发器的完整写法const btnStyle: React.CSSProperties { backgroundColor: typeof color string ? color : color!.toHexString(), }; ColorPicker value{color} onChange{setColor} Button typeprimary style{btnStyle}open/Button /ColorPicker弹出行为方面trigger控制触发模式hover或click默认clickplacement控制弹出位置默认bottomLeft与 Tooltip 组件的placement参数设计相同arrow可关闭弹出箭头或配置{ pointAtCenter: true }让箭头指向中心openonOpenChange提供受控显隐destroyTooltipOnHide5.7.0控制关闭后是否销毁弹层。ColorPicker.tsx中有一个细节值得注意useMergedState的postState会确保禁用状态下强制不弹出(openData) !mergedDisabled openData且禁用后点击不会打开面板测试Should not show popup when disabled覆盖了动态禁用场景。禁用、透明度与清除disabled禁用触发器渲染ant-color-picker-trigger-disabled类名且不响应点击。ColorPicker还支持从ConfigProvider的disabled上下文继承禁用态mergedDisabled disabled ?? contextDisabled。disabledAlpha5.8.0隐藏透明度滑杆与透明度输入框测试断言.ant-color-picker-slider-alpha与.ant-color-picker-alpha-input不再存在且滑杆组带ant-color-picker-slider-group-disabled-alpha类名。源码里它还有一个补偿逻辑当当前值本身是带透明度的颜色时onInternalChange与onChangeComplete会用 genAlphaColor 强制把 alpha 置为 1hsba.a 1并在开发环境通过devUseWarning输出usage警告提示disabledAlphawill make the alpha to be 100% when use alpha color见 ColorPicker.tsx L194-L203。allowClear默认false在面板右上角及触发器内显示清除按钮点击后触发onClear5.6.0回调颜色进入cleared状态。测试用例Should allowClear and onClear work验证了清除后 alpha 输入框变为0%、再次输入 HEX 后恢复100%的完整链路。值可为null/空defaultValue{null}表示初始透明色透明度为 0从面板拖动色相滑杆后会自动填充一个合理的初始色——PanelPicker 的onInternalChange检测到原值为0/0/0且来自 hue/alpha 滑杆时会构造hsb(0, 100%, 100%)或保留拖动的 alpha 值来避免用户看不到颜色测试transparent to valuable系列用例专门覆盖了这一体验优化。预设颜色 presetspresets传入分组预设色板每项结构为{ label: ReactNode, colors: Arraystring | Color, defaultOpen?: boolean }其中defaultOpen5.11.0控制该分组是否默认展开默认展开。官方 Demopresets.tsx展示了与ant-design/colors的结合import { generate, green, presetPalettes, red } from ant-design/colors; import { ColorPicker, theme } from antd; const genPresets (presets presetPalettes) Object.entries(presets).mapPresets(([label, colors]) ({ label, colors })); const Demo () { const { token } theme.useToken(); const presets genPresets({ primary: generate(token.colorPrimary), red, green }); return ColorPicker presets{presets} defaultValue#1677ff /; };面板中预设区由PanelPresets渲染每个分组是一个可折叠面板内部是Collapse结构colors为空数组时显示空态ant-color-picker-presets-empty深色背景下浅色预设块会加ant-color-picker-presets-color-bright类名以便辨识测试Should work at dark mode验证了深色模式下不标记亮色块。选中预设色会触发onChange并给对应色块加ant-color-picker-presets-color-checked。自定义面板 panelRender 与 Pure RenderpanelRender5.7.0接收(panel, extra)两个参数panel是默认完整面板色板 预设extra.components则提供Picker与Presets两个独立子组件允许完全重写布局。ColorPickerPanel.tsx 中的实现清晰展示了这条分支{typeof panelRender function ? panelRender(innerPanel, { components: { Picker: PanelPicker, Presets: PanelPresets }, }) : innerPanel}panel-render.tsx 演示了两种典型用法——包一层标题、以及把预设与色板做成左右分栏配合styles{{ popupOverlayInner: { width: 480 } }}加宽弹层const customPanelRender: ColorPickerProps[panelRender] (_, { components: { Picker, Presets } }) ( Row justifyspace-between wrap{false} Col span{12}Presets //Col Divider typevertical style{{ height: auto }} / Col flexautoPicker //Col /Row );若只渲染面板本体如需要把色板嵌入自定义弹层或 SSR 场景可以使用组件附带的ColorPicker._InternalPanelDoNotUseOrYouWillBeFired由 PurePanel 通用工具生成对应 Demo pure-panel.tsx它会以placement: bottom且关闭自动溢出调整的方式直接呈现面板。渐变模式 mode5.20.0mode参数5.20.0决定选择器支持单色或线性渐变类型为(single | gradient)[]默认[single]。传入[single, gradient]时面板顶部会出现一个Segmented切换器文案来自国际化词条singleColor/gradientColor用户可在两种模式间来回切换。渐变值的数据结构是停靠点数组value/defaultValue可传const DEFAULT_COLOR [ { color: rgb(16, 142, 233), percent: 0 }, { color: rgb(135, 208, 104), percent: 100 }, ]; ColorPicker defaultValue{DEFAULT_COLOR} allowClear showText mode{[single, gradient]} onChangeComplete{(color) console.log(color.toCssString())} /即 line-gradient.tsx 的写法。渐变交互由 GradientColorBar 实现一条带多个可拖拽手柄的色条拖动手柄即调整对应停靠点颜色与位置取色位置的颜色通过 getGradientPercentColor 按百分比在相邻停靠点之间用RcColor.mix插值计算。从源码结构看模式与颜色的状态同步由 useModeColor hook 负责当外部value是渐变数组时自动切换到gradient模式反之切回single。ColorPicker.tsx中还维护了一个cachedGradientColor缓存——从渐变切回单色时先取渐变的第一个颜色作为当前色若用户未修改单色就再切回渐变则恢复缓存的渐变避免数据丢失。切换模式的具体实现见onInternalModeChangesingle → gradient时用当前色或带 alpha 的版本生成 0%/100% 双停靠点gradient → single时取getColors()[0]。渐变模式的输出通过Color.toCssString()得到可直接用于样式的linear-gradient(90deg, ...)字符串实现见 color.ts 的toCssString渐变行为的端到端回归由 gradient.test.tsx 覆盖。onChange 与 onChangeComplete 的分工两个回调的触发时机不同测试用例Should onChangeComplete work给出了精确断言onChange颜色值发生任何变化即触发签名(value: Color, hex: string) void第二个参数实际是color.toCssString()见 ColorPicker.tsx 的onInternalChange拖动色板时持续触发onChangeComplete5.7.0一次选色动作完成时触发拖拽结束、输入确认、点击预设/清除等签名(value: Color) void拖动过程中不触发。官方推荐模式change-completed.tsx是用onChangeComplete作为受控值的提交点避免拖动过程中高频 setStateColorPicker value{value} onChangeComplete{(color) { setValue(color); message.success(The selected color is ${color.toHexString()}); }} /API 完整参考通用属性参考 Ant Design 的通用属性文档。自antd5.5.0版本开始提供该组件。参数说明类型默认值版本allowClear允许清除选择的颜色booleanfalsearrow配置弹出的箭头boolean \| { pointAtCenter: boolean }truechildren颜色选择器的触发器React.ReactNode-defaultValue颜色默认的值string |Color-defaultFormat颜色格式默认的值rgb|hex|hsb-5.9.0disabled禁用颜色选择器boolean-disabledAlpha禁用透明度boolean-5.8.0destroyTooltipOnHide关闭后是否销毁弹窗booleanfalse5.7.0format颜色格式rgb|hex|hsbhexmode选择器模式用于配置单色与渐变(single \| gradient)[]single5.20.0open是否显示弹出窗口boolean-presets预设的颜色{ label: ReactNode, colors: Arraystring \| Color, defaultOpen?: boolean }[]-defaultOpen: 5.11.0placement弹出窗口的位置同 Tooltip 组件的 placement 参数设计bottomLeftpanelRender自定义渲染面板(panel, extra: { components: { Picker: FC; Presets: FC } }) ReactNode-5.7.0showText显示颜色文本boolean |(color: Color) React.ReactNode-5.7.0size设置触发器大小large|middle|smallmiddle5.7.0trigger颜色选择器的触发模式hover|clickclickvalue颜色的值string |Color-onChange颜色变化的回调(value: Color, hex: string) void-onChangeComplete颜色选择完成的回调(value: Color) void-5.7.0onFormatChange颜色格式变化的回调(format: hex \| rgb \| hsb) void-onOpenChange当open被改变时的回调(open: boolean) void-onClear清除的回调() void5.6.0补充说明value/defaultValue在渐变场景下还可传{ color, percent }[]停靠点数组见 interface.ts 中ColorValueType的定义接口层通过Omit复用了rc-component/color-picker的部分 Props 并覆盖了onChange等签名因此本文表格即为对外契约内部类型变更不影响使用者。与 Form 的配合及常见陷阱ColorPicker可直接作为Form.Item的子控件参与校验测试用例should support valid in form验证了必填规则未满足时触发器会带ant-color-picker-status-error类名并显示错误文案。弹出面板外层还包了一层ContextIsolator隔离 form 上下文避免面板内的Select等控件意外注册进表单。几个源码确认过的使用要点受控值优先用Color对象字符串在 hex/rgb/hsb 之间互转存在精度损耗来回赋值可能导致颜色漂移官方 FAQ 原话disabledAlpha搭配透明色值会打开发警告当前值为带 alpha 的颜色时开启该属性alpha 会被强制归一为 100%开发环境会输出usage警告请知悉这一行为清除后再点清除不会重复触发onChange测试Should not trigger onChange when click clear after clearing明确断言了幂等性RTL 与挂载回归组件测试挂载了mountTest与rtlTestindex.test.tsx 顶部direction来自ConfigProvider对应ant-color-picker-rtl类名。仓库文件索引内容路径组件主逻辑Popover 组装、状态合并、模式切换ColorPicker.tsxAggregationColor颜色类格式转换、渐变 CSS 生成color.ts对外 Props 与类型定义interface.ts颜色工具函数generateColor、genAlphaColor、渐变插值util.ts面板组合与 panelRender 分支ColorPickerPanel.tsx色板/滑杆/预设面板基于 rc-component/color-pickercomponents/PanelPicker/index.tsx模式与颜色状态同步 hookhooks/useModeColor.ts功能回归测试格式、预设、禁用透明度、渐变、Form 校验等tests/index.test.tsx、tests/gradient.test.tsx全部示例demo/【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ant Design ColorPicker 颜色选择器实战指南：API 全解析、渐变模式与 Color 对象实现原理
Ant Design ColorPicker 颜色选择器实战指南API 全解析、渐变模式与 Color 对象实现原理【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designColorPicker颜色选择器是 Ant Design 自5.5.0起内置的数据录入组件用于用户在界面中自定义选择颜色底层基于rc-component/color-picker并在外层封装了 Popover 弹出、模式切换、预设色板与透明度控制。读完本文你将掌握其全部 Props 的取值与默认值、Color对象的格式转换方法、受控场景下的正确赋值方式以及单色/渐变5.20.0模式的实现原理与源码位置。何时使用与组件定位组件文档index.zh-CN.md给出的使用场景非常直接当用户需要自定义颜色选择的时候使用。它归属于 Ant Design 组件体系中的数据录入分组与Select、DatePicker一样支持受控value/onChange与非受控defaultValue两种用法可嵌入Form中参与校验。从源码结构看组件由三部分拼装而成见 ColorPicker.tsx触发器默认渲染 ColorTrigger一个展示当前颜色块的按钮也可通过children传入自定义触发元素弹出层直接使用 Ant Design 的Popover见ColorPicker.tsx中popoverProps的组装因此继承placement、trigger、getPopupContainer、autoAdjustOverflow等 Popover 能力选择面板ColorPickerPanel 内部由PanelPicker色板、滑杆、输入框与PanelPresets预设色组成二者通过 Context 共享状态并支持panelRender二次定制。官方提供 15 个可运行 Demo覆盖基本用法到 Pure Render 的全部场景源码位于 components/color-picker/demo/Demo说明base.tsx基本使用size.tsx触发器尺寸大小controlled.tsx受控模式change-completed.tsx颜色完成选择onChangeCompleteline-gradient.tsx渐变色5.20.0text-render.tsx渲染触发器文本disabled.tsx禁用disabled-alpha.tsx禁用透明度allowClear.tsx清除颜色trigger.tsx自定义触发器trigger-event.tsx自定义触发事件format.tsx颜色编码presets.tsx预设颜色panel-render.tsx自定义面板pure-panel.tsxPure Render基本使用与受控模式最简用法只需一个defaultValueimport React from react; import { ColorPicker } from antd; const Demo () ColorPicker defaultValue#1677ff /; export default Demo;受控模式则配合value与onChange。由于onChange回调的第一个参数是Color对象而非字符串官方 Democontrolled.tsx演示了推荐的类型写法import { useState } from react; import { ColorPicker } from antd; import type { ColorPickerProps, GetProp } from antd; type Color GetPropColorPickerProps, value; const Demo: React.FC () { const [color, setColor] useStateColor(#1677ff); return ColorPicker value{color} onChange{setColor} /; };在受控组件中颜色值同时接受字符串如#1677ff、hsb(215, 91%, 100%)和Color对象。源码中任何传入值都会经过 generateColor 统一包装为AggregationColor实例见 color.ts因此两种写法都能工作——但官方 FAQ 特别提醒不同格式的颜色字符串互相转换会有精度误差受控场景推荐使用选择器生成的Color对象来赋值以保证取值精准、选择器按预期工作。组件的公开导出index.tsx也印证了这一点它把AggregationColor以Color的类型名对外导出ColorPickerProps也同步导出方便业务侧声明状态类型。颜色编码format 与 Color 对象的方法族format默认hex决定面板中显示哪种输入框hex显示单行 HEX 输入rgb显示三通道加透明度的输入组hsb显示 HSB 输入组。非受控场景可用defaultFormat5.9.0设置初始格式受控场景用formatonFormatChange同步状态。format.tsx 对三种格式分别给出完整示例const [colorHex, setColorHex] useStateColor(#1677ff); const [formatHex, setFormatHex] useStateFormat | undefined(hex); const hexString React.useMemostring( () (typeof colorHex string ? colorHex : colorHex?.toHexString()), [colorHex], ); ColorPicker format{formatHex} value{colorHex} onChange{setColorHex} onFormatChange{setFormatHex} / spanHEX: {hexString}/span测试用例 index.test.tsx 中的Should format change work验证了面板内格式下拉框在 HEX → HSB → RGB 之间切换时DOM 会相应渲染.ant-color-picker-hsb-input与.ant-color-picker-rgb-input。Color对象AggregationColor类提供了完整的格式转换 API方法说明返回示例toCssString转换成 CSS 支持的格式5.20.0rgb(22, 119, 255)或渐变linear-gradient(...)toHex转换成hex格式字符不带#1677fftoHexString转换成hex格式颜色字符串#1677fftoHsb转换成hsb对象({ h, s, b, a })toHsbString转换成hsb格式颜色字符串hsb(215, 91%, 100%)toRgb转换成rgb对象({ r, g, b, a })toRgbString转换成rgb格式颜色字符串rgb(22, 119, 255)从源码实现看color.ts这些方法大部分是对rc-component/color-picker中RcColor的透传toHex额外经过 color.ts 中toHexFormat的正则清洗value.replace(/[^\w/]/gi, ).slice(0, alpha ? 8 : 6)因此带透明度的颜色会返回 8 位 hex。toCssString则是渐变特性的关键当对象承载渐变内部colors数组存在且未被清除时它把各停靠点拼接为linear-gradient(90deg, rgb(...) x%, rgb(...) y%)单色时直接返回toRgbString()。触发器定制children、showText 与 size不传children时触发器是内置的颜色块ColorTrigger内部由showText控制是否显示当前颜色文本。showText支持布尔或函数两种形式// 布尔显示当前格式的颜色字符串 ColorPicker defaultValue#1677ff showText / // 函数完全自定义文本text-render demo ColorPicker defaultValue#1677ff showText{(color) spanCustom Text ({color.toHexString()})/span} /showText函数形式在测试中得到了明确验证传入#1677ff且面板打开时切换格式后触发器文本会跟随变为hsb(215, 91%, 100%)、rgb(22,119,255)、#1677FF当值为null且开启showText时显示Transparent见 index.test.tsx 中Should showText work与showText with transparent两个用例。size5.7.0控制触发器大小取值large/middle默认/small对应类名ant-color-picker-lg/ant-color-picker-sm未显式指定时还会继承ConfigProvider的size与Space.Compact的紧凑尺寸useSize((ctx) customizeSize ?? compactSize ?? ctx)见 ColorPicker.tsx。自定义触发器则是把任意节点放进children触发器本身的样式交给该节点颜色选择面板照常弹出。trigger.tsx 展示了用按钮作为触发器的完整写法const btnStyle: React.CSSProperties { backgroundColor: typeof color string ? color : color!.toHexString(), }; ColorPicker value{color} onChange{setColor} Button typeprimary style{btnStyle}open/Button /ColorPicker弹出行为方面trigger控制触发模式hover或click默认clickplacement控制弹出位置默认bottomLeft与 Tooltip 组件的placement参数设计相同arrow可关闭弹出箭头或配置{ pointAtCenter: true }让箭头指向中心openonOpenChange提供受控显隐destroyTooltipOnHide5.7.0控制关闭后是否销毁弹层。ColorPicker.tsx中有一个细节值得注意useMergedState的postState会确保禁用状态下强制不弹出(openData) !mergedDisabled openData且禁用后点击不会打开面板测试Should not show popup when disabled覆盖了动态禁用场景。禁用、透明度与清除disabled禁用触发器渲染ant-color-picker-trigger-disabled类名且不响应点击。ColorPicker还支持从ConfigProvider的disabled上下文继承禁用态mergedDisabled disabled ?? contextDisabled。disabledAlpha5.8.0隐藏透明度滑杆与透明度输入框测试断言.ant-color-picker-slider-alpha与.ant-color-picker-alpha-input不再存在且滑杆组带ant-color-picker-slider-group-disabled-alpha类名。源码里它还有一个补偿逻辑当当前值本身是带透明度的颜色时onInternalChange与onChangeComplete会用 genAlphaColor 强制把 alpha 置为 1hsba.a 1并在开发环境通过devUseWarning输出usage警告提示disabledAlphawill make the alpha to be 100% when use alpha color见 ColorPicker.tsx L194-L203。allowClear默认false在面板右上角及触发器内显示清除按钮点击后触发onClear5.6.0回调颜色进入cleared状态。测试用例Should allowClear and onClear work验证了清除后 alpha 输入框变为0%、再次输入 HEX 后恢复100%的完整链路。值可为null/空defaultValue{null}表示初始透明色透明度为 0从面板拖动色相滑杆后会自动填充一个合理的初始色——PanelPicker 的onInternalChange检测到原值为0/0/0且来自 hue/alpha 滑杆时会构造hsb(0, 100%, 100%)或保留拖动的 alpha 值来避免用户看不到颜色测试transparent to valuable系列用例专门覆盖了这一体验优化。预设颜色 presetspresets传入分组预设色板每项结构为{ label: ReactNode, colors: Arraystring | Color, defaultOpen?: boolean }其中defaultOpen5.11.0控制该分组是否默认展开默认展开。官方 Demopresets.tsx展示了与ant-design/colors的结合import { generate, green, presetPalettes, red } from ant-design/colors; import { ColorPicker, theme } from antd; const genPresets (presets presetPalettes) Object.entries(presets).mapPresets(([label, colors]) ({ label, colors })); const Demo () { const { token } theme.useToken(); const presets genPresets({ primary: generate(token.colorPrimary), red, green }); return ColorPicker presets{presets} defaultValue#1677ff /; };面板中预设区由PanelPresets渲染每个分组是一个可折叠面板内部是Collapse结构colors为空数组时显示空态ant-color-picker-presets-empty深色背景下浅色预设块会加ant-color-picker-presets-color-bright类名以便辨识测试Should work at dark mode验证了深色模式下不标记亮色块。选中预设色会触发onChange并给对应色块加ant-color-picker-presets-color-checked。自定义面板 panelRender 与 Pure RenderpanelRender5.7.0接收(panel, extra)两个参数panel是默认完整面板色板 预设extra.components则提供Picker与Presets两个独立子组件允许完全重写布局。ColorPickerPanel.tsx 中的实现清晰展示了这条分支{typeof panelRender function ? panelRender(innerPanel, { components: { Picker: PanelPicker, Presets: PanelPresets }, }) : innerPanel}panel-render.tsx 演示了两种典型用法——包一层标题、以及把预设与色板做成左右分栏配合styles{{ popupOverlayInner: { width: 480 } }}加宽弹层const customPanelRender: ColorPickerProps[panelRender] (_, { components: { Picker, Presets } }) ( Row justifyspace-between wrap{false} Col span{12}Presets //Col Divider typevertical style{{ height: auto }} / Col flexautoPicker //Col /Row );若只渲染面板本体如需要把色板嵌入自定义弹层或 SSR 场景可以使用组件附带的ColorPicker._InternalPanelDoNotUseOrYouWillBeFired由 PurePanel 通用工具生成对应 Demo pure-panel.tsx它会以placement: bottom且关闭自动溢出调整的方式直接呈现面板。渐变模式 mode5.20.0mode参数5.20.0决定选择器支持单色或线性渐变类型为(single | gradient)[]默认[single]。传入[single, gradient]时面板顶部会出现一个Segmented切换器文案来自国际化词条singleColor/gradientColor用户可在两种模式间来回切换。渐变值的数据结构是停靠点数组value/defaultValue可传const DEFAULT_COLOR [ { color: rgb(16, 142, 233), percent: 0 }, { color: rgb(135, 208, 104), percent: 100 }, ]; ColorPicker defaultValue{DEFAULT_COLOR} allowClear showText mode{[single, gradient]} onChangeComplete{(color) console.log(color.toCssString())} /即 line-gradient.tsx 的写法。渐变交互由 GradientColorBar 实现一条带多个可拖拽手柄的色条拖动手柄即调整对应停靠点颜色与位置取色位置的颜色通过 getGradientPercentColor 按百分比在相邻停靠点之间用RcColor.mix插值计算。从源码结构看模式与颜色的状态同步由 useModeColor hook 负责当外部value是渐变数组时自动切换到gradient模式反之切回single。ColorPicker.tsx中还维护了一个cachedGradientColor缓存——从渐变切回单色时先取渐变的第一个颜色作为当前色若用户未修改单色就再切回渐变则恢复缓存的渐变避免数据丢失。切换模式的具体实现见onInternalModeChangesingle → gradient时用当前色或带 alpha 的版本生成 0%/100% 双停靠点gradient → single时取getColors()[0]。渐变模式的输出通过Color.toCssString()得到可直接用于样式的linear-gradient(90deg, ...)字符串实现见 color.ts 的toCssString渐变行为的端到端回归由 gradient.test.tsx 覆盖。onChange 与 onChangeComplete 的分工两个回调的触发时机不同测试用例Should onChangeComplete work给出了精确断言onChange颜色值发生任何变化即触发签名(value: Color, hex: string) void第二个参数实际是color.toCssString()见 ColorPicker.tsx 的onInternalChange拖动色板时持续触发onChangeComplete5.7.0一次选色动作完成时触发拖拽结束、输入确认、点击预设/清除等签名(value: Color) void拖动过程中不触发。官方推荐模式change-completed.tsx是用onChangeComplete作为受控值的提交点避免拖动过程中高频 setStateColorPicker value{value} onChangeComplete{(color) { setValue(color); message.success(The selected color is ${color.toHexString()}); }} /API 完整参考通用属性参考 Ant Design 的通用属性文档。自antd5.5.0版本开始提供该组件。参数说明类型默认值版本allowClear允许清除选择的颜色booleanfalsearrow配置弹出的箭头boolean \| { pointAtCenter: boolean }truechildren颜色选择器的触发器React.ReactNode-defaultValue颜色默认的值string |Color-defaultFormat颜色格式默认的值rgb|hex|hsb-5.9.0disabled禁用颜色选择器boolean-disabledAlpha禁用透明度boolean-5.8.0destroyTooltipOnHide关闭后是否销毁弹窗booleanfalse5.7.0format颜色格式rgb|hex|hsbhexmode选择器模式用于配置单色与渐变(single \| gradient)[]single5.20.0open是否显示弹出窗口boolean-presets预设的颜色{ label: ReactNode, colors: Arraystring \| Color, defaultOpen?: boolean }[]-defaultOpen: 5.11.0placement弹出窗口的位置同 Tooltip 组件的 placement 参数设计bottomLeftpanelRender自定义渲染面板(panel, extra: { components: { Picker: FC; Presets: FC } }) ReactNode-5.7.0showText显示颜色文本boolean |(color: Color) React.ReactNode-5.7.0size设置触发器大小large|middle|smallmiddle5.7.0trigger颜色选择器的触发模式hover|clickclickvalue颜色的值string |Color-onChange颜色变化的回调(value: Color, hex: string) void-onChangeComplete颜色选择完成的回调(value: Color) void-5.7.0onFormatChange颜色格式变化的回调(format: hex \| rgb \| hsb) void-onOpenChange当open被改变时的回调(open: boolean) void-onClear清除的回调() void5.6.0补充说明value/defaultValue在渐变场景下还可传{ color, percent }[]停靠点数组见 interface.ts 中ColorValueType的定义接口层通过Omit复用了rc-component/color-picker的部分 Props 并覆盖了onChange等签名因此本文表格即为对外契约内部类型变更不影响使用者。与 Form 的配合及常见陷阱ColorPicker可直接作为Form.Item的子控件参与校验测试用例should support valid in form验证了必填规则未满足时触发器会带ant-color-picker-status-error类名并显示错误文案。弹出面板外层还包了一层ContextIsolator隔离 form 上下文避免面板内的Select等控件意外注册进表单。几个源码确认过的使用要点受控值优先用Color对象字符串在 hex/rgb/hsb 之间互转存在精度损耗来回赋值可能导致颜色漂移官方 FAQ 原话disabledAlpha搭配透明色值会打开发警告当前值为带 alpha 的颜色时开启该属性alpha 会被强制归一为 100%开发环境会输出usage警告请知悉这一行为清除后再点清除不会重复触发onChange测试Should not trigger onChange when click clear after clearing明确断言了幂等性RTL 与挂载回归组件测试挂载了mountTest与rtlTestindex.test.tsx 顶部direction来自ConfigProvider对应ant-color-picker-rtl类名。仓库文件索引内容路径组件主逻辑Popover 组装、状态合并、模式切换ColorPicker.tsxAggregationColor颜色类格式转换、渐变 CSS 生成color.ts对外 Props 与类型定义interface.ts颜色工具函数generateColor、genAlphaColor、渐变插值util.ts面板组合与 panelRender 分支ColorPickerPanel.tsx色板/滑杆/预设面板基于 rc-component/color-pickercomponents/PanelPicker/index.tsx模式与颜色状态同步 hookhooks/useModeColor.ts功能回归测试格式、预设、禁用透明度、渐变、Form 校验等tests/index.test.tsx、tests/gradient.test.tsx全部示例demo/【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
