Arco Design ColorPicker 的 mode 属性实战:单一颜色与渐变色的切换与数据模型
Arco Design ColorPicker 的 mode 属性实战:单一颜色与渐变色的切换与数据模型
导读
本文围绕 Arco Design React 组件库(@arco-design/web-react)中 ColorPicker 颜色选择器的 mode 属性展开,讲解如何通过 mode 在「单一颜色」与「渐变色」两种模式之间切换,并深入剖析其底层的值类型(string | GradientColor[])、默认值结构、受控回调以及源码实现原理。读完本文,你将掌握 ColorPicker 渐变模式下的完整配置方法,并能依据源码理解模式切换、色标编辑与颜色值输出的完整链路。
mode 属性:三种取值形态
在 ColorPicker 接口定义 中,mode 属性的类型定义如下:
mode?: 'single' | 'gradient' | ['single', 'gradient'];
它支持三种取值形态:
| 取值 | 行为 |
|---|---|
'single' |
仅支持单一颜色模式(这也是默认值,见 interface.ts 中的 @defaultValue single 注释) |
'gradient' |
仅支持渐变色模式,面板直接展示渐变色条 |
['single', 'gradient'] |
双模式:面板顶部出现「单色 / 渐变色」切换标签(RadioGroup),允许用户在两种模式间自由切换 |
源码中用 ColorPickerMode 枚举对取值做了统一建模(interface.ts):
export enum ColorPickerMode {
Single = 'single',
Gradient = 'gradient',
}
模式判定工具函数
components/ColorPicker/mode.ts 中封装了模式判定的核心工具函数,用于判断当前配置属于单色、渐变还是双模式:
export const getMode = (mode: ColorPickerMode | ColorPickerMode[]) => {
if (Array.isArray(mode) && mode.length === 1) {
return mode[0];
}
return mode;
};
export const isSingleMode = (mode) => getMode(mode) === ColorPickerMode.Single;
export const isGradientMode = (mode) => getMode(mode) === ColorPickerMode.Gradient;
export const isMultiMode = (mode) => Array.isArray(getMode(mode));
从源码结构可以推断出:当 mode 传 ['single', 'gradient'] 时,isMultiMode 返回 true,面板因此渲染切换标签;当只有一个元素(如 ['gradient'])时会被归一化为单值模式处理。
渐变模式的核心数据模型:GradientColor
渐变模式下,ColorPicker 的 value / defaultValue 不再是字符串,而是一个渐变节点数组。其结构在 interface.ts 中定义:
export interface GradientColor {
color: string;
percent: number;
}
其中:
color:色标的颜色值,支持带透明通道的格式,如'#165DFFAA'(Arco 设计令牌主色 #165DFF 附加 AA 透明度);percent:色标在渐变条上的位置百分比,取值范围 0~100。
组件内部还会将其扩展为带唯一 id、解析后的 Color 对象与 alpha 的 InternalGradientColor(interface.ts),用于面板编辑与去重渲染。
官方示例解析:单一/渐变双模式与纯渐变模式
官方演示文档 components/ColorPicker/demo/mode.md 给出的完整示例:
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={<a href="https://link.gitcode.com/i/2be90725256c9c3542e7e47b19267edf" target="_blank">'single', 'gradient']}时,面板顶部会渲染一个「单色 / 渐变色」的按钮组切换器(见 [panel.tsx 中的renderModeTag,内部使用Radio.Group实现),同时defaultValue传渐变节点数组,因此首次打开时activeMode会优先取渐变模式; - 纯渐变模式:
mode="gradient"时,面板直接进入渐变色编辑态,不显示切换标签(见 panel.tsx 的条件渲染逻辑:仅isMultiMode(mode)时渲染renderModeTag())。
初始模式由值驱动
值得注意的一点是:组件的初始 activeMode 并不是简单地等于 mode,而是优先由 value / defaultValue 的类型推导。在 useColorPicker.ts 中:
const [activeMode, setActiveMode] = useState<ColorPickerMode>(
getModeByValue(props.value, defaultValue, mode)
);
getModeByValue 的判定顺序为:若 value 是数组 → 渐变模式;若 value 是字符串 → 单色模式;否则回退看 defaultValue 的类型;最后才回退到 mode 自身。这意味着即使 mode 配置为双模式,传入数组形式的 defaultValue 时面板也会自动定位到渐变色编辑态,这也是示例中第一个 ColorPicker 打开即呈现渐变条的原因。
渐变色的编辑交互与底层实现
渐变条的色标操作
在渐变模式下,面板渲染一个支持多个色标的 ControlBar(panel.tsx):
- 点击渐变条空白区域:新增色标,新增位置的颜色由相邻色标线性插值计算得出(见 utils.ts 的
getColorByGradients,内部通过mix函数对 RGB 与 alpha 通道做线性插值,随后sortGradientColors按percent升序排列); - 拖动色标:实时更新该色标的
percent(handleChange中Math.round(x * 100)转换为整数百分比); - 点击已有色标:将其激活为当前编辑对象(
handleActive会同步该色标的 HSV 与透明度到主色板/透明度条)。
多色标能力由 control-bar.tsx 的 multiple 模式与 useControlBlock.ts 的鼠标事件处理共同支撑:在 multiple 模式下,点击容器空白处触发 onAdd,点击手柄(携带 data-key)触发 onActive。
渐变预览与文本输出
预览区与文本展示使用 utils.ts 中的工具函数生成 CSS 渐变:
export const getGradientString = (value: GradientColor[]) =>
value.map(({ color, percent }) => `${color} ${percent}%`).join(', ');
export const renderGradientBackground = (value: GradientColor[]) => {
return `linear-gradient(to right, ${getGradientString(value)})`;
};
例如示例中的默认值会渲染为 linear-gradient(to right, #165DFFAA 0%, #00B42AFF 100%)。当 showText 开启时,输入框与文本区展示的就是这个可读的渐变字符串(见 index.tsx)。
渐变模式下的值输出与受控回调
输出结构
渐变模式下,onChange 回调与受控 value 收到的值不再是字符串,而是 GradientColor<a href="https://link.gitcode.com/i/a396dd5c967d9638d068cab2f5dfa16b" target="_blank">]。在 [useColorPicker.ts 中,formatValue 会根据 activeMode 决定输出形态:
const formatValue = useMemo(() => {
if (isSingleMode(activeMode)) {
const { r, g, b } = color.rgb;
return formatSingleValue(r, g, b, alpha);
}
return gradientColors.map((item) => {
const { r, g, b } = item.color.rgb;
return {
color: formatSingleValue(r, g, b, item.alpha),
percent: item.percent,
};
});
}, [activeMode, gradientColors, color.rgb, formatSingleValue, alpha]);
即:单色模式输出字符串,渐变模式输出 { color, percent } 数组。因此在使用时需注意同一个 ColorPicker 在双模式下 onChange 的入参类型可能随模式切换而改变,业务侧需要做相应的类型分支处理。
与 format 属性的配合
format 属性('hex' | 'rgb')同样作用于渐变模式下的色值:渐变节点中每个 color 都会按 format 输出为 Hex(含透明通道时为 8 位 hex)或 RGB/RGBA 格式(见 useColorPicker.ts 与 utils.ts 的 formatHex / formatRgba)。面板右下角的下拉框可随时在 Hex / RGB 输入格式间切换(panel.tsx),但需注意该下拉框仅影响面板输入展示,受控值格式由 format 属性最终决定。
模式切换的内部流转
在双模式下点击「单色 / 渐变色」标签时,onActiveModeChange(useColorPicker.ts)会执行状态转换:
- 切换到 单色:将当前激活色标作为单色值来源(
setActiveColorId(gradientColors[0]?.id)),并同步输出为字符串; - 切换到 渐变:以当前单色值生成两个色标(
percent: 0与percent: 100),构成初始渐变,之后可继续增删色标。
这种「单色 ↔ 渐变」的双向转换设计,使得 mode={['single', 'gradient']} 的用法在交互上非常顺滑——用户在拾色时可以先以单色快速选定主色,再切换渐变模式微调过渡。
组件集成与测试验证
基本引入
ColorPicker 从 @arco-design/web-react 导出,渐变模式的完整 API 可参考组件 README(components/ColorPicker/README.zh-CN.md),相关属性还包括:
disabledAlpha:禁用透明通道,开启后渐变节点 alpha 恒为 100(见 useColorPicker.ts);showText:展示当前值文本,渐变模式下展示渐变字符串;value/onChange:受控模式,渐变下为GradientColor[];defaultValue:非受控初始值,支持字符串或渐变节点数组;showHistory/showPreset/historyColors/presetColors:历史色与预设色区域(面板中点击色块即选中该色,见 panel.tsx);renderFooter:自定义面板底部内容(2.62.0+)。
单色与渐变的面板差异
从 panel.tsx 的面板结构可以看出:单色模式面板由「色板 Palette + 色相条 + 透明度条 + 预览 + 输入区」组成;渐变模式在色板上方额外增加一条多色标渐变条(renderGradientBar),并将面板包裹类名扩展为 -panel-control-gradient。渐变模式下选中的色标会成为色板与色相条的编辑对象,实现「先选色标、再调颜色」的联动编辑。
测试与示例运行
该组件由 demoTest 统一驱动快照测试,见 components/ColorPicker/test/demo.test.ts,其中 demoTest('ColorPicker') 会自动渲染 __demo__ 目录下所有示例(包括本主题的 mode.md),确保渐变模式示例的渲染结果稳定。你可以在本地运行 yarn test ColorPicker(或仓库 scripts 中配置的 jest 命令)复现该验证。
本地预览
在仓库根目录(本项目为 arco-design)执行依赖安装与站点启动命令后,即可在站点文档的「数据输入 → ColorPicker」章节找到「渐变色」示例进行交互体验;示例源码即 components/ColorPicker/demo/mode.md 中的代码块,可直接复制到业务项目中使用(需已安装 @arco-design/web-react 及其 peer 依赖 react / react-dom)。
小结
mode 属性让 ColorPicker 从单一颜色选择器扩展为支持多色标渐变的完整取色工具:
'single'(默认):输出string颜色值;'gradient':输出GradientColor[]({ color, percent }数组),面板提供渐变条增删/拖动色标编辑;['single', 'gradient']:面板内可通过「单色 / 渐变色」标签自由切换,且初始模式由value/defaultValue类型自动推导。
理解 mode.ts 的模式判定、useColorPicker.ts 的值驱动状态与 utils.ts 的渐变插值/字符串化逻辑,即可在生产项目中游刃有余地组合 mode、defaultValue、format 与 onChange,实现自定义渐变预设、渐变色表单控件等场景。