ColorSwatchPicker
color-swatch-picker从一组预设色块里挑一个颜色，方向键可达
用法
基础用法
离散预设色块单选，非受控用 defaultValue 给初始选中。
tsx
const PALETTE = ["#ef4444", "#f97316", "#eab308", "#22c55e", "#06b6d4", "#3b82f6", "#8b5cf6", "#ec4899"];
<ColorSwatchPicker colors={PALETTE} defaultValue="#3b82f6" />尺寸
size 支持 sm / md / lg。
tsx
<>
<ColorSwatchPicker colors={PALETTE} defaultValue="#22c55e" size="sm" />
<ColorSwatchPicker colors={PALETTE} defaultValue="#22c55e" size="lg" />
</>主题 token 色板（带可读名）
色块可以写成 { color, label }：label 作为无障碍名与 hover 提示，选中身份仍是 color。token 色必须给 label，否则读屏念的是 var(--color-primary) 这串变量名。
var(--color-primary)tsx
const TOKENS = [
{ color: "var(--color-primary)", label: "主色" },
{ color: "var(--color-success)", label: "成功" },
{ color: "var(--color-warning)", label: "警告" },
{ color: "var(--color-danger)", label: "危险" },
];
// 回吐的仍是 color 串，不是 label
<ColorSwatchPicker colors={TOKENS} value={v} onValueChange={setV} />禁用
disabled 整组降透明度并屏蔽交互。
tsx
<ColorSwatchPicker colors={PALETTE} defaultValue="#8b5cf6" disabled />何时用
从一组固定预设色（品牌色板、标签颜色）里单选一个时用，本质是 RadioGroup 的色块皮肤，自带方向键漫游。若需自由取任意颜色用 ColorPicker。
导入
ts
import { ColorSwatchPicker, normalizeSwatches } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| colors* | (string | { color: string; label?: string })[] | - | 预设色块列表。字符串 = 任意 CSS 颜色串（hex / rgb / hsl / 具名色 / var(--color-x)）；对象可另给 label 作无障碍名与 hover 提示。两种形态可混写 |
| value | string | - | 受控选中值（须与某个色块的 color 严格相等） |
| defaultValue | string | - | 非受控初始选中值 |
| size | "sm" | "md" | "lg" | "md" | 色块尺寸 |
| disabled | boolean | false | 整组禁用 |
| className | string | - | 透传到容器 |
| aria-label | string | - | 无障碍标签 |
ColorSwatchItem（colors 的对象形态）
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| color * | string | - | 任意 CSS 颜色串，同时是该色块的选中值（与 value 严格相等比较） |
| label | string | 回退到 color 本身 | 无障碍名与 hover 提示。喂 token 色（var(--color-primary)）时务必给，否则读屏会念出变量名 |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onValueChange | (color: string) => void | 选中变更回调，参数始终是色块的 color 而不是 label |
工具函数
| 名称 | 签名 | 说明 |
|---|---|---|
| normalizeSwatches | (colors: (string | ColorSwatchItem)[]) => { color: string; label: string }[] | 把混合数组归一成带可读名的色块；字符串项与缺省/空白 label 一律回退到色值本身 |
禁忌 / 坑
- token 色必须给 `label`。
colors里的裸字符串会直接当色块的aria-label，var(--color-primary)会被读屏原样念成变量名，对屏幕阅读器用户毫无意义；#3b82f6、oklch(...)同理只是一串字符。只有具名色（red/tomato）裸着还能读。 value/onValueChange的身份始终是color字符串，不是label。给了label也别拿它当选中值传回来。- 受控
value必须与某个色块的color严格字符串相等才会高亮；"#FFF"与"#ffffff"、"#3b82f6"与"rgb(59,130,246)"视为不同值。统一大小写与写法。 - 默认无障碍名称跟随
ConfigProvider locale；显式aria-label优先，未包 Provider 时保持中文。 - 仅支持单选；多选场景不在本组件范围内。
相关
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
#3b82f6<ColorSwatchPicker colors={PALETTE} defaultValue="#3b82f6" />