ColorPicker
选择或输入颜色。中文惯用名：颜色选择器。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.color-picker |
| 名称 | ColorPicker |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 选择或输入颜色 |
| 描述 | 中文惯用名：颜色选择器。 |
预览
静态结构：ColorPicker 为 input 风格触发器（data-slot="colorpicker-trigger"，前置 data-slot="colorpicker-swatch" 棋盘格色板 + 当前 hex 文本）+ 受控 Popover 弹层（data-slot="colorpicker-panel"）。弹层为 react-color Sketch 风格面板：饱和度 / 明度二维面板（data-slot="colorpicker-saturation"）、色相与透明度滑杆（colorpicker-hue / colorpicker-alpha，透明度滑杆叠棋盘格）、当前色预览块（colorpicker-preview）、hex 文本输入（Enter 提交，非法值显示 data-slot="colorpicker-error" 错误行）与 R / G / B / A 四通道数字输入（Enter 或失焦提交）、presets 预设色板（colorpicker-presets，命中当前值加 ring 高亮）。拖拽过程实时提交 onChange；Form 内声明 name 时外层包 FieldShell（label + 校验错误）。
DSL 结构
{
"type": "ColorPicker",
"props": {
"name": "brandColor",
"value": "#1677ff",
"presets": [
"#1677ff",
"#52c41a",
"#faad14",
"#ff4d4f"
]
}
}何时用
何时使用
- 允许用户自由选色：主题色、标签色、图表配色、富文本文字色。
- 需要透明度（alpha）的颜色：遮罩、高亮底色，a<1 时值自动为 8 位 hex。
- 提供 presets 预设色板收敛可选范围（如品牌色 + 功能色）。
何时不用
- 有限的固定色集合选择（如 8 个标签色）：使用 RadioGroup / Select 配合色块更轻量。
- 只需展示颜色而不允许修改：使用色块展示，不使用取色器。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 基础取色（无预设） | 完整 Sketch 面板：二维面板 + 双滑杆 + 通道输入 | 自由选色，如自定义主题色 |
| presets 预设色板 | 面板底部追加预设色块行 | 收敛到品牌 / 功能色集合，兼顾自定义 |
| 透明度取色 | 透明度滑杆与棋盘格底纹，值输出 8 位 hex | 遮罩、半透明高亮等需要 alpha 的颜色 |
| placeholder 空态 | 未选时触发器显示弱提示（缺省「请选择颜色」） | 非必填颜色字段 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（FieldShell 呈现） |
rules | FieldRule[] | — | 校验规则 |
value | string | — | 受控值（hex 颜色，支持 3/4/6/8 位，如 #1677ff、#1677ffcc）；Form 内作为字段初始值 |
presets | string[] | — | 预设色板（hex 数组），面板底部渲染色块行 |
placeholder | string | '请选择颜色' | 空态提示文案 |
disabled | boolean | false | 禁用触发器 |
onChange | (value: string) => void | — | 颜色变化事件，传出 hex 字符串（透明度小于 1 时为 8 位 hex，DSL 语义值） |
className | string | — | 根节点 class（Form 内为 form-item 容器，独立渲染时为触发器） |
style | CSSProperties | — | 根节点内联样式（同 className 的挂载规则） |
使用规范
- 值统一为 hex 字符串：6 位（a=1）或 8 位（a<1）；消费方按长度判断透明度，不要再拼 rgb()。
- 输入值宽容（3/4/6/8 位 hex 均可解析并归一化为小写展开），但输出始终是 6/8 位规范形。
- 面板内拖拽为实时提交：onChange 会高频触发，联动重活（如接口保存）需自行节流。
- presets 用于收敛选择范围；纯固定集合场景改用 RadioGroup / Select 色块更合适。
- 含透明度的颜色展示时叠棋盘格底纹表达透明区域，消费端回显也应如此。
正例
- ✓ 主题设置：presets 给品牌色板，用户也可在二维面板自定义，onChange 高频更新实时预览。
- ✓ 高亮遮罩：拖透明度滑杆得到 8 位 hex（如 #1677ff80），直接用于样式。
- ✓ Form 内声明 name + 必填 rules，未选色提交时提示。
反例
- ✕ 用 ColorPicker 让用户在 8 个固定标签色中选一个（应使用 RadioGroup / Select 色块）。
- ✕ 把 8 位 hex 截断成 6 位存储，透明度信息被静默丢弃。
- ✕ 在 onChange 里每次触发都直接请求保存接口，拖拽一次发出数十个请求。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。