Arco Design React 颜色选择器 ColorPicker 基础用法全解析:从 defaultValue 到源码级取色原理
Arco Design React 颜色选择器 ColorPicker 基础用法全解析:从 defaultValue 到源码级取色原理
本文以 components/ColorPicker/demo/basic.md 中的"基础用法"为主线,结合该组件的完整 API、全部示例与 index.tsx、panel.tsx、hooks/useColorPicker.ts 等源码,系统讲解 ColorPicker 的基本使用方式、核心参数、受控模式、颜色格式、尺寸、禁用、预设/历史颜色、渐变模式与自定义触发器,并深入面板内部的取色与格式化原理。读完本文,你将能够熟练配置并二次开发 Arco Design 的颜色选择器。
ColorPicker(颜色选择器)是 Arco Design React 组件库中用于"选择和展示颜色"的数据输入组件,可输出 Hex 或 RGB 格式的单一颜色,也支持由多个色标组成的渐变颜色。其最小的使用方式只需一行代码:
import { ColorPicker } from '@arco-design/web-react';
const App = () => {
return (
<div>
<ColorPicker defaultValue={'#165DFF'} />
<div style={{ marginTop: 10 }}/>
<ColorPicker defaultValue={'#165DFF'} showText />
</div>
);
};
export default App;
这是官方 基础用法示例 的完整代码:第一个选择器仅展示色块,第二个通过 showText 在色块右侧同步显示当前颜色值。接下来围绕这个最小示例,逐层展开该组件的完整使用与实现原理。
一、基础用法:defaultValue 与 showText
defaultValue 是 ColorPicker 的默认值,类型为 string | GradientColor<a href="https://link.gitcode.com/i/c9101ca63d34f1d56ad4436a00e94c69" target="_blank">](详见 [interface.ts)。传入字符串即表示单一颜色,如 #165DFF;传入 GradientColor[] 数组即表示渐变颜色,数组元素形如 { color: '#165DFFAA', percent: 0 }。
showText 为布尔值,控制是否在输入框区域显示颜色值文本。在源码 index.tsx 中,其渲染逻辑为:
{Boolean(showText) && <div className={`${prefixCls}-value`}>{stringifiedValue}</div>}
其中 stringifiedValue 在单一颜色时取字符串本身,在渐变颜色时通过 getGradientString 拼接为 '#165DFFAA 0%, #00B42AFF 100%' 的形式(见 utils.ts)。
值得注意的是,触发元素内部还隐藏了一个 readOnly 的 input(见 index.tsx),它承载颜色值但不可编辑,实际编辑在展开的面板中完成——这与"点击后弹出取色面板"的交互模型一致。整个触发区域由 Trigger 组件包裹,默认 trigger="click"、弹出位置 position="bl"(见 index.tsx),即点击色块后从下方展开面板。
触发元素的组成
从样式文件 style/index.less 可以看出触发元素是一个 inline-flex 容器,内部包含:
-preview:当前颜色的预览色块;-value:颜色值文本(仅showText开启时渲染);-input:隐藏的只读输入框(display: none)。
容器默认背景为浅灰输入框底色,hover 时变色并出现 pointer 光标,整体视觉与组件库的 Input 风格保持一致。
二、核心 API 全景:配置参数速查表
官方 README.zh-CN.md 将 ColorPicker 归入"数据输入"分类,其完整参数如下(可直接对照源码 interface.ts 使用):
| 参数名 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| defaultPopupVisible | 默认弹出框是打开还是关闭 | boolean | - |
| disabled | 禁用 | boolean | - |
| disabledAlpha | 禁用透明通道 | boolean | - |
| popupVisible | 弹出框是打开还是关闭(受控) | boolean | - |
| showHistory | 显示历史颜色 | boolean | - |
| showPreset | 显示预设颜色 | boolean | - |
| showText | 显示颜色值 | boolean | - |
| unmountOnExit | 隐藏后是否销毁 DOM 结构 | boolean | true |
| format | 颜色值的格式 | 'hex' | 'rgb' |
- |
| size | 输入框的尺寸 | InputProps['size'] |
default |
| className | 节点类名 | string | string[] |
- |
| defaultValue | 默认值 | string | GradientColor[] |
- |
| historyColors | 历史颜色的颜色数组 | string[] |
- |
| mode | 单一颜色或渐变色模式 | ColorPickerMode | ColorPickerMode[] |
single |
| presetColors | 预设颜色的颜色数组 | string[] |
- |
| style | 节点样式 | CSSProperties |
- |
| triggerProps | 可以接受所有 Trigger 组件的 Props | Partial<TriggerProps> |
- |
| value | 颜色值,受控模式 | string | GradientColor[] |
- |
| onChange | 颜色值改变时触发 | (value: string | GradientColor[]) => void |
- |
| onVisibleChange | 下拉框收起展开时触发 | (visible: boolean) => void |
- |
| renderFooter | 自定义面板底部内容(2.62.0+) | () => ReactNode |
- |
| triggerElement | 自定义触发元素(2.60.0+) | ReactNode | ((params: { value }) => ReactNode) |
- |
其中两个衍生类型定义如下(见 interface.ts):
export enum ColorPickerMode {
Single = 'single',
Gradient = 'gradient',
}
export interface GradientColor {
color: string;
percent: number;
}
默认值在源码中的体现
从 index.tsx 可以看到组件的默认配置:
const defaultProps: ColorPickerProps = {
size: 'default' as const,
presetColors: colors,
};
即默认尺寸为 default,且默认携带一份内置预设色板 colors(22 个品牌色,见 colors.ts)。组件的 props 会经过 useMergeProps 合并 ConfigProvider 的全局配置(componentConfig?.ColorPicker)与上下文尺寸 ctxSize,这意味着你可以通过 ConfigProvider 为全站 ColorPicker 统一设置默认尺寸等配置。
三、受控模式:value + onChange
在受控模式下,颜色值由外部 value 决定,并通过 onChange 回传新值。官方 受控模式示例 展示了一个典型场景:面板打开时会同步输入框中的值——即使外部通过按钮修改了 value,再次打开面板也会以最新值初始化取色状态:
import { Button, ColorPicker } from '@arco-design/web-react';
import { useState } from 'react';
const App = () => {
const [value, setValue] = useState('#165DFF');
return (
<div>
<div>
<Button onClick={() => setValue('#165DFF')}>#165DFF</Button>
<Button onClick={() => setValue('#165DFF88')}>#165DFF88</Button>
</div>
<div style={{ marginTop: 10 }}/>
<ColorPicker value={value} onChange={(value)=>setValue(value)} showText />
</div>
);
};
export default App;
在源码 useColorPicker.ts 中,onVisibleChange 会在面板打开时检测 value 与当前取色状态是否一致,不一致则用外部值重新初始化 hsv 与 alpha:
if (newVisible && value !== formatValue) {
const { h, s, v, a } = formatInput;
setHsv({ h, s, v });
setAlpha(a);
}
同时,每次取色状态变化都会触发 onChange,且通过 isEqualsColors(见 utils.ts)对比新旧颜色,避免无变化时重复回调。isEqualsColors 对字符串颜色做全等比较,对渐变数组则逐一对比每段的 RGBA 与百分比。
四、颜色格式:format 切换 Hex 与 RGB
format 参数决定输出的颜色值格式,支持 'hex' 与 'rgb'。官方 颜色格式示例 用 Radio 组动态切换格式:
import { ColorPicker, Radio } from '@arco-design/web-react';
import { useState } from 'react';
const RadioGroup = Radio.Group;
const App = () => {
const [format, setFormat] = useState('hex')
return (
<div>
<RadioGroup
type="button"
mode="fill"
name="size"
value={format}
onChange={setFormat}
style={{ marginBottom: 24 }}
>
{['hex', 'rgb'].map((x) => {
return (
<Radio key={x} value={x}>
{x}
</Radio>
);
})}
</RadioGroup>
<div style={{ marginTop: 10 }}/>
<ColorPicker defaultValue={'#165DFF'} showText format={format} />
</div>
);
};
export default App;
格式化的实现细节
从 useColorPicker.ts 可以看到,格式化通过 formatSingleValue 完成:
format === 'rgb'时使用formatRgba:Alpha 小于 1 输出rgba(r, g, b, a)(a 保留两位小数),否则输出rgb(r, g, b);- 否则使用
formatHex:Alpha 小于 1 输出带 Alpha 的 8 位 Hex,否则输出 6 位 Hex(见 utils.ts)。
需要留意的是,format 只影响对外输出的值;面板内部仍然以 HSV 为核心状态,并在需要时通过 hsvToRgb、rgbToHex 等工具互相转换(这些工具位于 components/_util/color.ts)。另外,面板的输入区还内置了一个可切换 Hex / RGB 的下拉选择器(见 panel.tsx),用于切换手动输入数值的呈现方式——Hex 模式下输入框过滤非十六进制字符并自动大写(见 input-hex.tsx),RGB 模式下则是三个 0~255 范围的数字输入框(见 input-rgb.tsx)。
五、尺寸:四种规格一览
size 支持 mini、small、default、large 四种尺寸,对应触发元素高度分别为 24px、28px、32px、36px(见 尺寸示例):
import { ColorPicker, Radio } from '@arco-design/web-react';
const RadioGroup = Radio.Group;
const App = () => {
return (
<div>
<ColorPicker defaultValue={'#165DFF'} size={'mini'} />
<div style={{ marginTop: 10 }}/>
<ColorPicker defaultValue={'#165DFF'} size={'small'} />
<div style={{ marginTop: 10 }}/>
<ColorPicker defaultValue={'#165DFF'} size={'default'} />
<div style={{ marginTop: 10 }}/>
<ColorPicker defaultValue={'#165DFF'} size={'large'} />
</div>
);
};
export default App;
尺寸类名通过 ${prefixCls}-size-${size} 注入触发元素(见 index.tsx),不同尺寸在 style/index.less 中分别设置 min-height、内边距与预览色块大小。其类型直接复用 Input 组件的 size 类型(InputProps['size']),与表单中其他输入类组件保持一致的尺寸体系。
六、禁用与禁用透明通道
disabled:整体禁用
设置 disabled 后整个选择器不可交互:触发区域显示禁用态背景与 not-allowed 光标(见 style/index.less),同时透传给内部 Trigger 关闭弹出能力(见 index.tsx)。官方 禁用示例 如下:
import { ColorPicker, Radio } from '@arco-design/web-react';
const RadioGroup = Radio.Group;
const App = () => {
return (
<div>
<ColorPicker defaultValue={'#165DFF'} disabled />
<div style={{ marginTop: 10 }}/>
<ColorPicker defaultValue={'#165DFF'} showText disabled />
</div>
) ;
};
export default App;
disabledAlpha:禁用透明通道
disabledAlpha 会隐藏面板中的 Alpha 滑条与 Alpha 数值输入框(对应 panel.tsx 中条件渲染的 Alpha 控制条,以及 input-hex.tsx / input-rgb.tsx 中 !disabledAlpha && <InputAlpha ... /> 的条件输出)。
官方 禁用透明通道示例 特别指出了边界行为:
import { ColorPicker } from '@arco-design/web-react';
const App = () => {
return (
<div>
<ColorPicker defaultValue={'#165DFF'} disabledAlpha />
<br />
<ColorPicker defaultValue={'#165DFF80'} disabledAlpha />
</div>
) ;
};
export default App;
- 若
defaultValue传入的初始色值本身包含 Alpha(如#165DFF80),初次渲染时色块会保留该 Alpha; - 一旦用户在取色板上取色,Alpha 将被重置并锁定为 100。
这一行为在源码中有明确对应:mapValueToGradientColor 初始化时仅在 disabledAlpha 为真时强制 Alpha 为 100(见 utils.ts),而 onHsvChange 在 disabledAlpha && alpha !== 100 时会自动把 Alpha 重置为 100(见 useColorPicker.ts)。
七、预设颜色与历史颜色:showPreset / showHistory / presetColors / historyColors
面板底部可以开启"预设颜色"和"历史颜色"两个区块。官方 预设颜色和历史颜色示例 展示了完整用法,其中历史颜色的内容需要用户自行维护:
import { useState } from 'react';
import { ColorPicker } from '@arco-design/web-react';
const App = () => {
const [color, setColor] = useState('#165DFF')
const [history, setHistory] = useState([]);
const addHistory = (visible) => {
if (!visible) {
const newHistory = [...history.slice(-10), color];
setHistory(newHistory)
}
}
return (
<div>
<div>Preset: </div>
<ColorPicker defaultValue={'#165DFF'} showPreset showText />
<div style={{ marginTop: 10 }} />
<div>History & Preset: </div>
<ColorPicker value={color} historyColors={history} showPreset showHistory showText onChange={setColor}
onVisibleChange={addHistory} />
</div>
);
};
export default App;
实现要点
- 预设色板:默认使用内置的 22 色数组
colors(见 colors.ts),也可通过presetColors完全替换;点击某个预设色块会直接更新当前颜色(onHexInputChange,见 panel.tsx)。 - 历史颜色:
showHistory开启后展示historyColors传入的数组,组件本身不会自动记录历史,需要用户结合onVisibleChange(面板关闭时回调visible === false)自行维护列表。示例中history.slice(-10)控制历史最多保留最近 10 条,并借助Set去重(见 panel.tsx)。 - 当历史区域为空时,面板会显示本地化的"暂无数据"占位文案(
locale.ColorPicker.empty,见 panel.tsx),文案随 locale 语言包自动切换。
八、单一颜色与渐变色模式:mode 详解
mode 是 ColorPicker 最具特色的能力,取值为 'single'、'gradient' 或二者的数组 ['single', 'gradient']:
'single'(默认):仅支持单一颜色;'gradient':仅支持渐变颜色,面板顶部显示渐变控制条;['single', 'gradient']:面板内出现"纯色 / 渐变色"切换标签,用户可自行切换。
官方 渐变色示例 如下:
import { Button, ColorPicker } from '@arco-design/web-react';
import { useState } from 'react';
const App = () => {
const defaultValue = [
{
color: '#165DFFAA',
percent: 0,
},
{
color: '#00B42AFF',
percent: 100,
},
]
return (
<div>
<ColorPicker defaultValue={defaultValue} mode={['single', 'gradient']} showText />
<br />
<ColorPicker defaultValue={defaultValue} mode="gradient" showText />
</div>
);
};
export default App;
模式判定的源码逻辑
在 mode.ts 中,模式相关判定清晰可查:
isSingleMode/isGradientMode:判断当前是否为纯色 / 渐变模式;isMultiMode:判断是否允许用户切换两种模式;getModeByValue:根据传入的value/defaultValue类型自动推断初始模式——值为数组时视为渐变,值为字符串时视为纯色(见 mode.ts)。
在 useColorPicker.ts 中,模式切换时组件会自动构造渐变数据:从纯色切到渐变时会基于当前颜色生成 percent: 0 与 percent: 100 两个端点色标;从渐变切回纯色时会取第一个色标作为当前颜色。
渐变色的数学原理
渐变色的插值计算位于 utils.ts 的 getColorByGradients:当用户在渐变条上某个百分比位置添加新色标时,先找到前后两个相邻色标,再按百分比位置做 RGBA 通道的线性插值(mix 函数),从而生成新色标。所有色标最终会按 percent 升序排序(sortGradientColors),对外输出为 GradientColor<a href="https://link.gitcode.com/i/5f9e7a52386dbf12d93334325f9b4be1" target="_blank">],预览背景则渲染为 linear-gradient(to right, ...)(见 [utils.ts)。渐变控制条的滑块样式(含当前选中色标的高亮描边)由 control-bar.tsx 的 renderHandlerStyle / renderHandlerCenterStyle 提供。
九、自定义触发器:triggerElement
从 2.60.0 版本起,triggerElement 允许完全替换默认的"色块 + 文本"触发元素,此时与颜色输入框相关的属性(如 size、showText、颜色文本样式)将失效。官方 自定义触发器示例:
import { useState } from 'react';
import { Button, ColorPicker } from '@arco-design/web-react';
const App = () => {
const [value, setValue] = useState('#165DFF');
return (
<div>
<ColorPicker defaultValue={'#165DFF'} triggerElement={({ value }) => {
return <Button>Open Color Picker: {value}</Button>
}}>
</ColorPicker>
</div>
);
};
export default App;
源码 index.tsx 的实现为:当 triggerElement 是函数时,以 { value }(当前颜色值)为参数调用并渲染返回值;是节点时直接渲染。只要 triggerElement 非空,默认的输入框渲染(renderInput 中的 preview / value / input)就会被整体替换。
此外,triggerProps 可以透传 Trigger 组件的全部 Props(如 position、popupAlign、classNames 等),用于微调弹出层行为;renderFooter(2.62.0+)可向面板底部追加自定义内容,两者为高级定制提供了充分的扩展点。
十、源码级原理:一次取色操作背后发生了什么
将基础用法落实到实现层面,一次完整的取色交互涉及以下链路(文件均位于 components/ColorPicker 目录):
- 点击触发:用户点击触发元素,Trigger 以
trigger="click"弹出面板(见 index.tsx),面板内容由 panel.tsx 渲染。 - 在取色板选色:palette.tsx 渲染一个带 HSV 亮度/饱和度渐变背景的方形区域,其定位与拖拽逻辑由 hooks/useControlBlock.ts 提供——该 Hook 在
mousedown时向window挂载mousemove/mouseup/contextmenu监听,将鼠标坐标换算为 0~1 的百分比位置,再回调给上层。 - 更新颜色状态:取色板回调
onChange(s, v)更新 HSV;色相条(Hue)与 Alpha 条通过 control-bar.tsx 复用同一套拖拽逻辑。所有状态收敛在 useColorPicker.ts 中:HSV → RGB → Hex 的转换由getColorFromHsv(见 utils.ts)完成。 - 回传与展示:格式化后的值经
setValue/onChange同步到受控或非受控状态,同时更新触发元素中的预览色块与文本。
对于渐变模式,同一套 useControlBlock 还承担了"在渐变条任意位置添加色标""拖动色标调整百分比""点击色标切换选中"三种交互(见 control-bar.tsx 的 multiple 分支)。
组件的质量保障同样体现在测试上:test/demo.test.ts 通过 demoTest('ColorPicker') 逐个渲染并断言 demo 目录下的全部示例(含基础用法),确保官方示例与组件实现保持同步可用。
十一、小结
ColorPicker 以"基础用法"为入口,实际上提供了从单一颜色到渐变色、从非受控到受控、从预设色板到自定义触发器的完整能力矩阵:
- 最小可用:
<ColorPicker defaultValue="#165DFF" />; - 显示数值:追加
showText; - 受控管理:
value+onChange; - 输出格式:
format="hex" | "rgb"; - 尺寸体系:
size="mini | small | default | large"; - 交互约束:
disabled/disabledAlpha; - 快捷色板:
showPreset+presetColors,showHistory+historyColors; - 渐变能力:
mode="gradient" | ['single', 'gradient'],配合GradientColor[]值; - 深度定制:
triggerElement、triggerProps、renderFooter。
在实现层面,HSV 核心状态、RGBA 线性插值、百分比坐标拖拽 Hook 与 Trigger 弹出机制共同构成了其稳定可靠的基础,而这些都可以在 components/ColorPicker 目录下的源码中逐一印证。无论你是表单场景的快速接入,还是需要自定义取色交互的深度集成,以上参数与原理都足以支撑你的实践。