> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/color-picker.html
> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.
# ColorPicker 颜色选择器
选择颜色，为内容和品牌增添个性。
## 选择颜色
点击色块、颜色文字或整行空白区域即可打开选择浮层。
**#20834a当前颜色：#20834a
basic.tsx
复制代码
```tsx lineNumbers file="../../src/examples/color-picker/basic.tsx"
import { ColorPicker, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function ColorPickerBasic() {
const [color, setColor] = useState('#20834a');
return (
当前颜色：{color}
);
}
```
展开代码
## 颜色格式与透明度
HEX**#1677ff
RGB · 半透明**rgba(118, 84, 198, 0.6)
HSL · 不透明**hsl(35, 91%, 55%)
formats.tsx
复制代码
```tsx lineNumbers file="../../src/examples/color-picker/formats.tsx"
import { ColorPicker, Flex, Text } from '@ifhover/leaf-ui';
export function ColorPickerFormats() {
return (
HEX
RGB · 半透明
HSL · 不透明
);
}
```
展开代码
## 预设与状态
自定义预设 · 可清除**#20834a
禁用**#1677ff
presets.tsx
复制代码
```tsx lineNumbers file="../../src/examples/color-picker/presets.tsx"
import type { ColorPreset } from '@ifhover/leaf-ui';
import { ColorPicker, Flex, Text } from '@ifhover/leaf-ui';
const presets: readonly ColorPreset[] = [
{ label: '品牌颜色', colors: ['#20834a', '#1677ff', '#7654c6', '#f49b23'] },
{ label: '中性色', colors: ['#203329', '#6c7c71', '#dce5de', '#ffffff'] },
];
export function ColorPickerPresets() {
return (
自定义预设 · 可清除
禁用
);
}
```
展开代码
## 渐变色
纯色**#20834a
渐变：选择、添加或移除色标**渐变
capabilities.tsx
复制代码
```tsx lineNumbers file="../../src/examples/color-picker/capabilities.tsx"
import { ColorPicker, Flex, Space, Text } from '@ifhover/leaf-ui';
export function Capabilities() {
return (
{'纯色'}
{'渐变：选择、添加或移除色标'}
);
}
```
展开代码
## ColorPicker API
| 属性 | 类型 | 默认值 | 说明 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------- |
| `popupPlacement` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | — | 浮层相对触发控件的位置。 |
| `popupClassName` | `string` | — | 浮层的自定义类名。 |
| `popupStyle` | `CSSProperties` | — | 浮层的自定义样式。 |
| `popupRender` | `(content: ReactNode) => ReactNode` | — | 包装或补充面板内容，保留传入的内容以维持交互。 |
| `getPopupContainer` | `() => Element \| DocumentFragment` | — | 返回浮层的挂载容器，也可返回 ShadowRoot。 |
| `value` | `string` | `'#20834a'` | 受控颜色 / 初始颜色，可使用 HEX、RGB、HSL 或 CSS 命名颜色 |
| `defaultValue` | `string` | `'#20834a'` | 受控颜色 / 初始颜色，可使用 HEX、RGB、HSL 或 CSS 命名颜色 |
| `onChange` | `(color: string) => void` | — | 实时变化 / 一次调色操作结束；清除时返回空字符串 |
| `onChangeComplete` | `(color: string) => void` | — | 实时变化 / 一次调色操作结束；清除时返回空字符串 |
| `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | 颜色文字格式；渐变模式应用于每个色标。 |
| `defaultFormat` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | 初始颜色文字格式。 |
| `onFormatChange` | `(format: 'hex' \| 'rgb' \| 'hsl') => void` | — | 颜色文字格式变化时调用。 |
| `disableAlpha` | `boolean` | `false` | 隐藏透明度并输出不透明颜色 |
| `showText` | `boolean \| ((color: string) => ReactNode)` | `false` | 展示颜色文字或自定义文字 |
| `allowClear` | `boolean` | `false` | 允许清除颜色 |
| `presets` | `readonly `[`ColorPreset`](#colorpreset)`[]` | 内置颜色 | 预设的颜色分组。 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 触发控件尺寸 |
| `status` | `'error' \| 'warning'` | — | 校验反馈 |
| `required` | `boolean` | `false` | 要求整体值非空，复合控件只校验一次。 |
| `readOnly` | `boolean` | — | 锁定业务值，禁止输入、选择、清除和删除。 |
| `popupWidth` | `number \| string` | `280` | 浮层宽度 |
| `onOpenChange` | `(open: boolean) => void` | — | 展开状态变化 |
| `gradient` | `boolean` | `false` | 启用渐变颜色选择。 |
| `mode` | `'solid' \| 'gradient'` | — | 选择展示或编辑模式。 |
| `open` | `boolean` | — | 控制面板是否展开。 |
| `defaultOpen` | `boolean` | — | 面板初始展开状态。 |
| `disabled` | `boolean` | `false` | 禁用交互。 |
| `name` | `string` | — | 原生 FormData 中的字段名。 |
| `form` | `string` | — | 关联的原生表单 ID。 |
## ColorPreset
| 属性 | 类型 | 默认值 | 说明 |
| -------- | ------------------- | --- | --------- |
| `label` | `ReactNode` | — | 必需。分组标题 |
| `colors` | `readonly string[]` | — | 必需。该组的颜色值 |
## 类型
可导入以下类型定义属性、组装数据或处理回调。
```ts
import type { ColorPickerProps, ColorPreset } from '@ifhover/leaf-ui';
```
## 使用说明
颜色值以字符串传递，开启透明度时 HEX 可能为 8 位。格式切换不会修改已提交值，下一次调色按所选格式输出。拖动时触发 `onChange`，释放指针、键盘调整、输入提交或选择预设时触发 `onChangeComplete`。
调色区域支持方向键，按住 Shift 加大调整幅度；左右调整饱和度，上下调整亮度。颜色输入通过 Enter 或移走焦点提交，无效输入保留错误提示。支持 FormData、必填校验与非受控表单 reset；受控字段需同步重置自己的值。
## ColorGradient
| 属性 | 类型 | 默认值 | 说明 |
| ------- | -------------------------------------------------------- | --- | ------------- |
| `angle` | `number` | — | 必需。渐变角度，单位为度。 |
| `stops` | `readonly `[`ColorGradientStop`](#colorgradientstop)`[]` | — | 必需。渐变中的色标。 |
## ColorGradientStop
| 属性 | 类型 | 默认值 | 说明 |
| -------- | -------- | --- | ---------------------- |
| `key` | `string` | — | 稳定且唯一的标识。 |
| `color` | `string` | — | 必需。颜色或语义色。 |
| `offset` | `number` | — | 必需。偏移量；色标为 0–100 的百分比。 |