# 颜色选择器

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/color-picker
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

用于选择颜色。


## 何时使用 {#when-to-use}

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

## 代码演示 {#examples}


- 基本使用 · `base`
- 触发器尺寸大小 · `size`
- 受控模式 · `controlled`
- 渐变色 · `line-gradient`
- 渲染触发器文本 · `text-render`
- 禁用 · `disabled`
- 禁用透明度 · `disabled-alpha`
- 清除颜色 · `allowClear`
- 自定义触发器 · `trigger`
- 自定义触发事件 · `trigger-event`
- 颜色编码 · `format`
- 预设颜色 · `presets`

- 自定义面板 · `panel-render`
- 自定义语义结构的样式和类 · `style-class`


## API

通用属性参考：[通用属性](#jguang-common-props)

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


| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| :-- | :-- | :-- | :-- | :-- | --- |
| allowClear | 允许清除选择的颜色 | boolean | false |  | × |
| arrow | 配置弹出的箭头 | `boolean \| { pointAtCenter: boolean }` | true |  | 6.3.0 |
| children | 颜色选择器的触发器 | React.ReactNode | - |  | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  | 6.0.0 |
| defaultValue | 颜色默认的值 | [ColorType](#colortype) | - |  | × |
| defaultFormat | 颜色格式默认的值 | `rgb` \| `hex` \| `hsb` | `hex` | 5.9.0 | × |
| disabled | 禁用颜色选择器 | boolean | - |  | × |
| disabledAlpha | 禁用透明度 | boolean | - | 5.8.0 | × |
| disabledFormat | 禁用选择颜色格式 | boolean | - | 5.22.0 | × |
| ~~destroyTooltipOnHide~~ | 关闭后是否销毁弹窗 | `boolean` | false | 5.7.0 | × |
| destroyOnHidden | 关闭后是否销毁弹窗 | `boolean` | false | 5.25.0 | × |
| format | 颜色格式 | `rgb` \| `hex` \| `hsb` | - |  | × |
| mode | 选择器模式，用于配置单色与渐变 | `'single' \| 'gradient' \| ('single' \| 'gradient')[]` | `single` | 5.20.0 | × |
| open | 是否显示弹出窗口 | boolean | - |  | × |
| presets | 预设的颜色 | [PresetColorType](#presetcolortype) | - |  | × |
| placement | 弹出窗口的位置 | 同 `Tooltips` 组件的 [placement](/components/tooltip/#api) 参数设计 | `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` \| `small` | `medium` | 5.7.0 | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - |  | 6.0.0 |
| trigger | 颜色选择器的触发模式 | `hover` \| `click` | `click` |  | × |
| value | 颜色的值 | [ColorType](#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

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

#### PresetColorType

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

### Color


| 参数 | 说明 | 类型 | 版本 |
| :-- | :-- | :-- | :-- |
| toCssString | 转换成 CSS 支持的格式 | `() => string` | 5.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

### 关于颜色赋值的问题 {#faq-color-assignment}

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


## 原生通用属性 {#jguang-common-props}


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

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


## 安装并复现示例

```bash
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 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt