JGuang
EN

颜色选择器

ColorPicker · Ant Design

交互预览
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

颜色选择器

用于选择颜色。

何时使用

当用户需要自定义颜色选择的时候使用。

代码演示

  • 基本使用 · base

  • 触发器尺寸大小 · size

  • 受控模式 · controlled

  • 渐变色 · line-gradient

  • 渲染触发器文本 · text-render

  • 禁用 · disabled

  • 禁用透明度 · disabled-alpha

  • 清除颜色 · allowClear

  • 自定义触发器 · trigger

  • 自定义触发事件 · trigger-event

  • 颜色编码 · format

  • 预设颜色 · presets

  • 自定义面板 · panel-render

  • 自定义语义结构的样式和类 · style-class

API

通用属性参考：通用属性

自 antd@5.5.0 版本开始提供该组件。

参数说明类型默认值版本全局配置
allowClear允许清除选择的颜色booleanfalse×
arrow配置弹出的箭头boolean | { pointAtCenter: boolean }true6.3.0
children颜色选择器的触发器React.ReactNode-×
classNames用于自定义组件内部各语义化结构的 class，支持对象或函数Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string>-6.0.0
defaultValue颜色默认的值ColorType-×
defaultFormat颜色格式默认的值rgb | hex | hsbhex5.9.0×
disabled禁用颜色选择器boolean-×
disabledAlpha禁用透明度boolean-5.8.0×
disabledFormat禁用选择颜色格式boolean-5.22.0×
destroyTooltipOnHide关闭后是否销毁弹窗booleanfalse5.7.0×
destroyOnHidden关闭后是否销毁弹窗booleanfalse5.25.0×
format颜色格式rgb | hex | hsb-×
mode选择器模式，用于配置单色与渐变'single' | 'gradient' | ('single' | 'gradient')[]single5.20.0×
open是否显示弹出窗口boolean-×
presets预设的颜色PresetColorType-×
placement弹出窗口的位置同 Tooltips 组件的 placement 参数设计bottomLeft×
panelRender自定义渲染面板(panel: React.ReactNode, extra: { components: { Picker: FC; Presets: FC } }) => React.ReactNode-5.7.0×
showText显示颜色文本boolean | (color: Color) => React.ReactNode-5.7.0×
size设置触发器大小large | medium | smallmedium5.7.0×
styles用于自定义组件内部各语义化结构的行内 style，支持对象或函数Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties>-6.0.0
trigger颜色选择器的触发模式hover | clickclick×
value颜色的值ColorType-×
onChange颜色变化的回调(value: Color, css: string) => void-×
onChangeComplete颜色选择完成的回调，通过 onChangeComplete 对 value 受控时拖拽不会改变展示颜色(value: Color) => void-5.7.0×
onFormatChange颜色格式变化的回调(format: 'hex' | 'rgb' | 'hsb') => void-×
onOpenChange当 open 被改变时的回调(open: boolean) => void-×
onClear清除的回调() => void-5.6.0×

ColorType

type ColorType =
  | string
  | Color
  | {
      color: string;
      percent: number;
    }[];

PresetColorType

type PresetColorType = {
  label: React.ReactNode;
  defaultOpen?: boolean;
  key?: React.Key;
  colors: ColorType[];
};

Color

参数说明类型版本
toCssString转换成 CSS 支持的格式() => string5.20.0
toHex转换成 hex 格式字符，返回格式如：1677ff() => string-
toHexString转换成 hex 格式颜色字符串，返回格式如：#1677ff() => string-
toHsb转换成 hsb 对象() => ({ h: number, s: number, b: number, a: number })-
toHsbString转换成 hsb 格式颜色字符串，返回格式如：hsb(215, 91%, 100%)() => string-
toRgb转换成 rgb 对象() => ({ r: number, g: number, b: number, a: number })-
toRgbString转换成 rgb 格式颜色字符串，返回格式如：rgb(22, 119, 255)() => string-

Semantic DOM

语义节点原生说明版本
root触发器容器，包含边框样式、过渡动画、尺寸控制等样式，显示颜色块和文本内容—
body色块容器，包含底色、边框等样式—
content色块颜色元素，包含实际选择的颜色样式—
description描述文本内容，包含字体样式、颜色等样式—
popup.root弹出面板根容器，包含背景色、阴影效果、色彩选择面板、滑块控制和预设颜色等样式—

语义说明来源: vendor/components/color-picker/demo/_semantic.tsx

FAQ

关于颜色赋值的问题

颜色选择器的值同时支持字符串色值和选择器生成的 Color 对象，但由于不同格式的颜色字符串互相转换会有精度误差问题，所以受控场景推荐使用选择器生成的 Color 对象来进行赋值操作，这样可以避免精度问题，保证取值是精准的，选择器也可以按照预期工作。

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

参数说明类型默认值
style自定义样式CSSProperties-
className自定义类名string-
rootClassName添加在组件最外层的 classNamestring-
autoFocus自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效booleanfalse

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

  • vendor/components/color-picker/ColorPicker.tsx
  • vendor/components/color-picker/ColorPickerPanel.tsx
  • vendor/components/color-picker/color.ts
  • vendor/components/color-picker/components/ColorAlphaInput.tsx
  • vendor/components/color-picker/components/ColorClear.tsx
  • vendor/components/color-picker/components/ColorHexInput.tsx
  • vendor/components/color-picker/components/ColorHsbInput.tsx
  • vendor/components/color-picker/components/ColorInput.tsx
  • vendor/components/color-picker/components/ColorPresets.tsx
  • vendor/components/color-picker/components/ColorRgbInput.tsx
  • vendor/components/color-picker/components/ColorSlider.tsx
  • vendor/components/color-picker/components/ColorSteppers.tsx
  • vendor/components/color-picker/components/ColorTrigger.tsx
  • vendor/components/color-picker/components/PanelPicker/GradientColorBar.tsx
  • vendor/components/color-picker/components/PanelPicker/index.tsx
  • vendor/components/color-picker/context.ts
  • vendor/components/color-picker/hooks/useModeColor.ts
  • vendor/components/color-picker/interface.ts
  • vendor/components/color-picker/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。