Arco Design React 颜色选择器 ColorPicker 基础用法全解析:从 defaultValue 到源码级取色原理

原创2026-10-12 15:08:111,370 阅读
文章标签:UI组件前端设计系统

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 目录):

  1. 点击触发:用户点击触发元素,Trigger 以 trigger="click" 弹出面板(见 index.tsx),面板内容由 panel.tsx 渲染。
  2. 在取色板选色:palette.tsx 渲染一个带 HSV 亮度/饱和度渐变背景的方形区域,其定位与拖拽逻辑由 hooks/useControlBlock.ts 提供——该 Hook 在 mousedown 时向 window 挂载 mousemove / mouseup / contextmenu 监听,将鼠标坐标换算为 0~1 的百分比位置,再回调给上层。
  3. 更新颜色状态:取色板回调 onChange(s, v) 更新 HSV;色相条(Hue)与 Alpha 条通过 control-bar.tsx 复用同一套拖拽逻辑。所有状态收敛在 useColorPicker.ts 中:HSV → RGB → Hex 的转换由 getColorFromHsv(见 utils.ts)完成。
  4. 回传与展示:格式化后的值经 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 目录下的源码中逐一印证。无论你是表单场景的快速接入,还是需要自定义取色交互的深度集成,以上参数与原理都足以支撑你的实践。

登录后查看全文
arco-design