ColorPicker 颜色选择器
在色域中自由选取一个颜色：触发按钮显示当前色，浮层内包含取色面、色相与透明度两条滑块、数值框、屏幕取色与预设色板。它是颜色家族的组合件：两条滑块是颜色滑块，预设色板是颜色色块选择器，触发按钮内的色块与颜色色块同族；只需要其中一件时不使用完整的选择器。
用法
取色面选择饱和度与明度，下方一条色相滑块；滑块是内嵌的颜色滑块组件，Vue / React 的挂载点不写子节点即自动铺开
组件结构
加粗的是必需部件。
data-scope="color-picker"：root · label · control · tag-list · trigger · clear-trigger · value-text · swatch · positioner · content · saturation-area · area-thumb · hue-slider · alpha-slider · channel-input · eye-dropper-trigger · swatch-picker · recent-swatch-picker · confirm-trigger · hidden-input
示例
预设色板
swatches 提供一组常用颜色，浮层中内嵌一台色块选择器：方向键在格子间移动、按颜色比较选中
禁用
禁止更改颜色
透明度
alpha 开启后值串带透明度，浮层中多一条透明度滑块；两条滑块共用同一份工作色，调节色相不会把透明度归 1
精确输入
输入色值或使用屏幕取色
oklch 写法
format="oklch" 让值串与主题令牌同一色空间，取到的颜色可以直接写回令牌；工作色在 sRGB 内，超出 sRGB 的 oklch 值按通道夹回
常驻形态
inline 让取色面直接铺在页面里，与浮层形态同一台机器、同一组部件，只是不写 control、trigger 与 positioner；取色面不抢焦点，也不因点外或 Esc 收起
当前：#3b82f6
最近使用色
一轮取色结束（浮层收起，或常驻形态下焦点离开取色面）且颜色变了，就记进最近使用色，最新的在最前、同色只留一份；受控写回由宿主保存，刷新后还在
多选成标签
selectionMode="multiple" 时浮层里调出的颜色是草稿，按「添加」收进值、浮层不收，可以接着添；预设色板点一下切换选中。选中的颜色在输入行里排成带色点的标签，点叉或在展开钮上按退格摘掉
#00a98e#3b82f6
设计指引
何时使用
- 用户需要自定义主题色、标注色或画布颜色，且不限于固定选项。
- 需要挑出一组颜色（配色方案、图表系列色）时，用多选把它们收成一排标签。
- 既需要可视化挑选（取色面、滑块）也需要精确输入（十六进制、分量框）。
- 需要从屏幕取色。
何时不用
特性
- 工作色始终是 HSVA：取色面两轴是饱和度与明度，纯黑与灰度处的色相由锚点保持，拖到黑色再拉回时色相不丢失。
format决定值串写法（hex / rgba / hsla / oklch），alpha决定是否带透明度；关闭时透明度滑块与输入框整体禁用。oklch 与令牌同一色空间，便于把取到的颜色写回主题；工作色在 sRGB 内，超出 sRGB 的 oklch 值按通道夹回。HSB 不是 CSS 颜色写法，不作值串格式，需要 HSB 数值时读hsva。- 色相与透明度两条滑块是内嵌的颜色滑块：整份工作色交给它们，调整色相不会把透明度归 1；键盘（方向键、PageUp / PageDown、Home / End、Shift 大步）与拖动都由滑块自身处理。
- 预设色板是内嵌的色块选择器：方向键在格子间移动并选中，当前颜色所在格按颜色比较（写法不同也能匹配）。
- 数值框输入只保留草稿，可解析时立即取值；不可解析时保留原文并报输入错误，回车同时拦截表单提交。
- 屏幕取色通过浮层内的按钮触发，环境不提供 EyeDropper 时始终禁用；取到的颜色与色板、外部 setValue 走同一条取值路径。
- 格式、输入、颜色解析与屏幕取色四路错误相互独立，修正一路不影响其他路。
- 值恒为颜色串数组：单选是一项，宿主可以写裸串；
onValueChange的value恒为数组。 - 单选给空数组是未选：色块不画颜色、画一道斜线，值文字显示
placeholder（缺省取translations.placeholder），表单影子是空串，required据此拦下；打开浮层从#000000起调，选定一个颜色才有值。value与defaultValue都不给时照旧从#000000起、算作已选。 - 单选有值时盒里露出清空钮（
clear-trigger）：按下清回未选，先发onValueChange（value为空数组）再发onClear，不碰开合；未选、多选、禁用、只读与常驻形态时收起。setValue([])同样清回未选，不发onClear。 - 受控
value与open：宿主不写回时界面不变化，回调照常发出；表单出口经hidden-input提交选中的值串。 - 多选（
selectionMode="multiple"）时浮层里调出的工作色是草稿，按「添加」（confirm-trigger）收进值，浮层不收、工作色留着，接着调就能添下一个；预设色板点一下切换选中，格子本身不再标选中。工作色解析不出、已经选过（按颜色比较，写法不同也算同一个）或到了maxSelected时「添加」不可按。 - 多选的选中值在输入行里排成标签（与选择器多选同一套库内标签），按加入先后：每枚标签前一个该颜色的色点，值文字收起，触发钮只剩一颗显示工作色的色块并成为键盘入口，在它上面按退格摘掉最后一个，点标签上的叉摘掉那一个；标签不截短、一行放不下就折行，超过
maxTagCount（默认 3）的折进 +N；表单一个选中值一份同名隐藏输入。 inline是常驻形态：取色面直接铺在页面里，与浮层形态同一台机器、同一组部件，只是不写control/trigger/positioner。取色面是静态内容面（surface 圆角、描边、不落影），不抢焦点、不入层栈，点外与 Escape 都不收起。- 最近使用色：一轮取色结束且颜色变了就记一笔，最新的在最前、同色只留一份、最多留
maxRecentColors个（缺省 8）。浮层形态以收起为一轮，常驻形态以焦点离开取色面为一轮；只经setValue改的不记。recentColors可受控，由宿主持久化；recent-swatch-picker挂载点渲染它们，还没有时收起。
组合
- 四个挂载点
hue-slider/alpha-slider/swatch-picker/recent-swatch-picker同时充当内嵌组件的根节点，内部放置的是颜色滑块与颜色色块选择器自己的部件；不写子节点时自动铺开最简结构。 - 放入表单字段承接标题、说明与错误信息，
disabled/readOnly随字段下发。 - 与颜色字段并排：选择器挑颜色，字段显示并微调该值。
最佳实践
- 通过
swatches提供常用色，多数用户从这里即可完成选择。 - 触发按钮内同时放色块与值串，读屏与视觉各有一路。
- 多选时在浮层末尾放「添加」，并配上预设色板：常用色点一下就进出，自定义色调好再添。
- 需要精确输入时放数值框；一个十六进制框比四个分量框更节省空间。
反模式
- 只显示颜色不显示数值，颜色不能是唯一的信息通道。
- 有对比度要求的场景不提供校验反馈。
- 关闭
alpha后仍保留透明度滑块，整条禁用的控件只会造成困惑。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-color-picker> |
| Vue 组件 | XhColorPickerAlphaSlider XhColorPickerAreaThumb XhColorPickerChannelInput XhColorPickerClearTrigger XhColorPickerConfirmTrigger XhColorPickerContent XhColorPickerControl XhColorPickerEyeDropperTrigger XhColorPickerHiddenInput XhColorPickerHueSlider XhColorPickerItemDeleteTrigger XhColorPickerLabel XhColorPickerOverflowTag XhColorPickerPositioner XhColorPickerRecentSwatchPicker XhColorPickerRoot XhColorPickerSaturationArea XhColorPickerSwatch XhColorPickerSwatchPicker XhColorPickerTag XhColorPickerTagLabel XhColorPickerTagList XhColorPickerTrigger XhColorPickerValueText |
| 组合式函数 | useColorPicker |
| 状态机 | colorPickerMachine |
| 皮肤 | @xihan-ui/styles/color-picker.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
labelled | boolean | 作者渲染了 label 部件时置真，由适配器统计而不是判断标题文字是否有值。 为假时可聚焦部件不把 label 的 id 写进 aria-labelledby：指向未渲染的 id 是无效引用，作者写在控件上的 aria-label 也会被它压住。 | |
ariaLabel | string | 不显示出来的名字，写成 aria-label 落在与字段标签同一个部件上。 放进字段（字段接线）或渲染了 label 部件时名字以它们为准，aria-labelledby 盖过它。 | |
value | string | string[] | 选中的颜色，值串数组。提供即受控：写入只发 onValueChange 不落内部值。 单选可写裸串，内部一律归一为数组；单选给空数组时是未选：色块不画颜色、值文字显示 placeholder， 取色面从 #000000 起调，选定一个颜色才有值。value 与 defaultValue 都不给时从 #000000 起、算作已选。 | |
defaultValue | string | string[] | ||
selectionMode | ColorPickerSelectionMode | 选择模式，默认 single。 | |
maxSelected | number | multiple 下最多选几个颜色：选满后「添加」不可按、色块只能点掉已选的。非整数向下取整，小于 1 或不是有限数时不设上限。 | |
maxTagCount | number | 多选时输入行最多摆几枚标签，其余折进 +N 那一枚；默认 3。 | |
format | ColorFormat | 值串的写法，默认 hex。修改它只改变对外的序列化，工作色恒为 HSVA。 | |
open | boolean | 展开态。提供即受控：内部不再自行修改，只发 onOpenChange。 | |
defaultOpen | boolean | ||
disabled | boolean | 整个控件禁用：trigger 与两个按钮使用原生 disabled，取色区与滑杆退出 Tab 序列。 | |
readOnly | boolean | 只读：浮层照常展开（可查看当前颜色），但任何改值的动作都不发生。 | |
invalid | boolean | 校验失败标注：触发钮写 aria-invalid，各部件写 data-invalid，字段外壳按它描红。 | |
required | boolean | 必填：各部件写 data-required（标题据此画星号），表单影子写原生 required；触发钮是按钮，不收 aria-required。 | |
swatches | string[] | 预设色板：交给内嵌的色块选择器铺格，选中的格按颜色比较。 | |
inline | boolean | 常驻形态：取色面直接铺在页面里，不经触发钮与浮层，与浮层形态共用同一台机器与同一组部件。 开着时恒为展开态，open / defaultOpen / onOpenChange 不起作用，也不接管焦点与点外关闭。 | |
recentColors | string[] | 最近使用色（最新的在最前）。提供即受控：内部只发 onRecentColorsChange，由宿主写回（也由宿主持久化）。 一次取色结束时记一笔：浮层形态在收起那一刻，常驻形态在焦点离开取色面那一刻； 这一轮里颜色没变、或只经 api.setValue 改过就不记。 | |
defaultRecentColors | string[] | ||
maxRecentColors | number | 最近使用色最多留几个，默认 8；写 0 即不记。 | |
name | string | 表单字段名；提供后表单影子才带 name 并参与提交。 | |
placeholder | string | 单选未选时值文字显示的提示；缺省取 translations.placeholder。 | |
alpha | boolean | 带透明度，默认关闭。关闭时值串恒为不透明，透明度滑杆与输入框整条禁用。 | |
size | Size | 尺寸：sm / md / lg。 | |
variant | ControlVariant | 盒的形态：outline / subtle / ghost，默认 outline，与同族字段同一套字段外壳。 | |
dir | Direction | 文字方向。只改写横轴（取色区的饱和度、通道滑杆）上左右两键与指针的语义。 | |
placement | Placement | ||
offset | number | ||
translations | Partial<ColorPickerTranslations> | ||
onValueChange | (details: ColorPickerValueChangeDetails) => void | value 变化意图回调；受控时是唯一出口，非受控时随内部写入一并通知。 | |
onClear | () => void | 用户按清空钮清掉了值：先发 onValueChange（value 为空数组），再发它。程序化的 setValue 不发。 | |
onOpenChange | (details: ColorPickerOpenChangeDetails) => void | open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。 | |
onRecentColorsChange | (details: ColorPickerRecentColorsChangeDetails) => void | 最近使用色变化意图回调；受控时是唯一出口。 | |
onColorError | (details: ColorPickerErrorDetails) => void | 格式、文本、颜色解析或屏幕取色失败；与 value / open 事件独立。 |
事件
自定义元素将载荷放在 detail；Vue 使用同名 emit。
| 事件 | 载荷 | 说明 |
|---|---|---|
value-change | ColorPickerValueChangeDetails | 选中的颜色变化；detail 为 { value: string[] }，单选恒为一项 |
open-change | ColorPickerOpenChangeDetails | open 状态变化；detail 为 { open: boolean } |
color-error | ColorPickerErrorDetails | 格式、输入、颜色解析或屏幕取色失败；detail 为判别式错误对象 |
recent-colors-change | ColorPickerRecentColorsChangeDetails | 一轮取色结束、颜色变了，最近使用色随之变化；detail 为 { recentColors: string[] } |
clear | `` | 用户按清空钮（clear-trigger）清掉了值；先发值变化（value 为空数组），再发它。程序化的 setValue([]) 不发。 |
插槽
仅列出带载荷的插槽。
| Vue 组件 | 插槽 | 载荷 | 说明 |
|---|---|---|---|
XhColorPickerRoot | default | ColorPickerRootSlotProps | |
XhColorPickerRoot | label | — |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhColorPickerChannelInput | channel | ColorPickerInputChannel | 该输入框编辑的通道：hex 是整串，r/g/b 是分量，a 是透明度百分数；默认或无法识别时按 hex 处理。 | |
XhColorPickerPositioner | container | () => Element | null | 浮层挂载的容器；未提供时按全局配置，再未提供时挂载到 body。 | |
XhColorPickerRoot | label | ReactNode | 标题。不给 children 时铺 label 部件。 | |
XhColorPickerRoot | children | SlotChildren<ColorPickerRootSlotProps> | ||
XhColorPickerTag | value | string | 是 | 它代表哪个选中颜色。 |
状态
公开状态写入 data-state。
| 部件 | 取值 |
|---|---|
root | 'open' | 'closed' |
label | 'open' | 'closed' |
control | 'open' | 'closed' |
trigger | 'open' | 'closed' |
value-text | 'open' | 'closed' |
swatch | 'open' | 'closed' |
positioner | 'open' | 'closed' |
content | 'open' | 'closed' |
saturation-area | 'open' | 'closed' |
area-thumb | 'open' | 'closed' |
channel-input | 'open' | 'closed' |
eye-dropper-trigger | 'picking' | 'open' | 'closed' |
以下名称仅用于内部状态机。
状态：closed · open · open.idle · open.dragging · open.picking
事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · VALUE.SET · SELECTED.SET · VALUE.CLEAR · VALUE.ADD · VALUE.REMOVE · VALUE.TOGGLE · TAG_LIST.TRACKED · AREA.SET · AREA.STEP · AREA.TO_EDGE · HSVA.SET · INPUT.CHANGE · INPUT.COMMIT · DRAG.START · DRAG.MOVE · DRAG.END · EYE_DROPPER.OPEN · EYE_DROPPER.RESULT · EYE_DROPPER.CANCEL · EYE_DROPPER.ERROR · ERROR.CLEAR · SESSION.END · RECENT.CLEAR · INLINE.SYNC · INLINE.CLOSE · FORM.RESET · PRESS.START · PRESS.END
判据：isOpenControlled · canInteract · canPick · isInline
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
open | boolean | |
value | string[] | 选中的颜色，值串数组（与 onValueChange 发出的是同一个）：单选是一项、未选时为空，多选按加入先后。 |
selectionMode | ColorPickerSelectionMode | |
color | string | 工作色的值串：取色面从它调起；单选时就是选中值，多选时是浮层里调着的草稿。单选未选时是取色面的起调色 #000000。 |
empty | boolean | 单选还没选颜色：色块不画颜色，值文字显示 placeholder，清空钮收起。 |
valueText | string | 值文字显示的内容：工作色的值串；单选未选时是 placeholder。 |
rgba | ColorRgba | |
hsva | ColorHsva | 工作色。取色区与色相滑杆读取的都是它。 |
format | ColorFormat | |
alpha | boolean | |
disabled | boolean | |
readOnly | boolean | |
invalid | boolean | |
required | boolean | |
dragging | boolean | 指针正在拖动某一部位。 |
picking | boolean | 屏幕取色正在进行。 |
eyeDropperSupported | boolean | |
errors | ColorPickerErrors | 格式、文本、颜色解析与屏幕取色四路互不覆盖的错误。 |
swatches | string[] | 预设色板（原样透传 swatches prop，默认为空数组）。 |
inline | boolean | 常驻形态。 |
recentColors | string[] | 最近使用色，最新的在最前。 |
canAdd | boolean | 多选时「添加」此刻可按：工作色还没选过、也没到 maxSelected。 |
tags | ColorPickerTagMeta[] | 多选时可见的标签（受 maxTagCount 截断），与 value 同序；单选恒为空数组。 |
translations | ColorPickerTranslations | 合上作者覆盖后的文案。 |
overflowCount | number | 被 maxTagCount 折叠的标签数。 |
overflowText | string | +N 标签显示的文字（由 translations.overflowTag 计算）；没有折叠的标签时为空串。 |
hueSlider | ColorSliderApi<T> | 色相颜色滑块的 api：部件属性与取值都从这里获取，DOM 带 data-scope="color-slider"。 |
alphaSlider | ColorSliderApi<T> | 透明度颜色滑块的 api。 |
swatchPicker | ColorSwatchPickerApi<T> | 预设色板的 api，DOM 带 data-scope="color-swatch-picker"。 |
recentSwatchPicker | ColorSwatchPickerApi<T> | 最近使用色那台色块选择器的 api。 |
inputText | (channel: ColorPickerInputChannel) => string | 某个数值框当前应显示的文字（有草稿显示草稿，否则显示规范文本）。 |
setOpen | (next: boolean) => void | |
setValue | (next: string[]) => void | 改选中值：单选取首项改工作色、给空数组清回未选（不发 onClear），多选整份替换。 |
add | () => void | 多选：把工作色收进值（与按「添加」同一条路）。 |
deselect | (value: string) => void | 多选：摘掉一个选中值。 |
clearError | () => void | 清除四路显式错误；屏幕取色重试也会先清除自己那一路。 |
clearRecentColors | () => void | 清空最近使用色。 |
getRootProps | () => T['element'] | |
getLabelProps | () => T['label'] | |
getControlProps | () => T['element'] | |
getTagListProps | () => T['element'] | 标签行：多选时放在盒里、触发钮之前，收纳可见标签与 +N 标签；单选时整体 hidden。 |
getTagProps | (props: ColorPickerTagProps) => T['element'] | 标签：一个选中值一个，即库内 tag 的 root（data-scope="tag"），另带 data-value 与画色点用的颜色。 |
getTagLabelProps | () => T['element'] | 标签文字所在的块（tag 的 label）；标签与 +N 共用。 |
getOverflowTagProps | () => T['element'] | 被折叠的标签合成的一个：同样是 tag 的 root，显示 overflowText、带 data-count；没有折叠的标签时 hidden。 |
getItemDeleteTriggerProps | (props: ColorPickerTagProps) => T['button'] | 标签删除按钮：即所在标签那份 tag 的 close-trigger，可及名使用 translations.deleteItem；不占 Tab 位、按下不夺焦。 |
getTriggerProps | () => T['button'] | |
getClearTriggerProps | () => T['button'] | 清空钮：触发钮的兄弟节点（按钮不能套按钮），单选有值时才显示，按下清回未选、不碰开合； 不占 Tab 位，可及名使用 translations.clearTrigger。多选与未选时 hidden。 |
getValueTextProps | () => T['element'] | |
getSwatchProps | () => T['element'] | |
getPositionerProps | () => T['element'] | |
getContentProps | () => T['element'] | |
getSaturationAreaProps | () => T['element'] | |
getAreaThumbProps | () => T['element'] | |
getHueSliderProps | () => T['element'] | 色相滑块的挂载点，同时充当该滑块的根节点：滑块 root 的状态标记同步写在它身上。 |
getAlphaSliderProps | () => T['element'] | 透明度滑块的挂载点，同上。 |
getChannelInputProps | (props: ColorPickerInputProps) => T['input'] | |
getEyeDropperTriggerProps | () => T['button'] | |
getSwatchPickerProps | () => T['element'] | 预设色板的挂载点，同时充当色板的根节点（role=radiogroup 与键盘处理都在它身上）。 |
getRecentSwatchPickerProps | () => T['element'] | 最近使用色的挂载点，同上；还没有最近使用色时收起。 |
getConfirmTriggerProps | () => T['button'] | 「添加」：多选时把工作色收进值，浮层不收；单选时 hidden。文字由作者写。 |
getHiddenInputProps | (props?: ColorPickerHiddenInputProps) => T['input'] | 表单影子：值随表单提交。提供 name 后才带 name，未提供时不参与提交。 多选时一个选中值一份同名输入：传 { value } 产出那一份，不传是首个选中值那一份。 |
无障碍
键盘
规格出处：W3C APG
| 按键 | 生效条件 | 行为 |
|---|---|---|
Backspace | focus in trigger, multiple, 有选中值, not disabled/readOnly | 摘掉最后一个选中值（标签行末尾那一枚） |
ArrowRight / ArrowLeft | focus in area-thumb, not disabled/readOnly | 按 1 调饱和度；RTL 下左右对调，语义恒是"朝饱和走一格" |
ArrowUp / ArrowDown | focus in area-thumb, not disabled/readOnly | 按 1 调明度，屏幕向上恒是变亮，与 dir 无关 |
Shift+ArrowRight / Shift+ArrowLeft / Shift+ArrowUp / Shift+ArrowDown | focus in area-thumb, not disabled/readOnly | 同上，但一步走 10 |
Home / End | focus in area-thumb, not disabled/readOnly | 饱和度取 0 / 100（与 aria-valuenow 报的是同一条轴） |
Enter | focus in channel-input | 收下框里的字；收不了就保留草稿并报告输入错误。一并拦住表单提交 |
Escape | open（本层在层栈顶） | 收起浮层，焦点归还触发器；常驻形态不入层栈，不接管这个键 |
Enter / Space | held on eye-dropper-trigger, not disabled | 按住期间取色按钮投影 data-pressed，与指针 :active 同一副按压面；抬起或失焦撤下，屏幕取色一开（窗口随即失焦）或浮层收起时一并撤下 |
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
trigger | aria-controls | content 部件的 id |
trigger | aria-expanded | 'true' | 'false' |
trigger | aria-haspopup | 'dialog' |
trigger | aria-invalid | 'true' | 'false' |
trigger | aria-label | props.ariaLabel |
trigger | aria-labelledby | label 部件的 id value-text 部件的 id | trigger 部件的 id value-text 部件的 id | value-text 部件的 id |
clear-trigger | aria-label | label.clearTrigger |
swatch | aria-hidden | 'true' |
content | aria-hidden | !open || undefined |
content | aria-label | props.ariaLabel |
content | aria-labelledby | label 部件的 id | undefined |
content | aria-modal | undefined | 'false' |
content | role | 'group' | 'dialog' |
area-thumb | aria-disabled | 'true' | 'false' |
area-thumb | aria-label | label.area |
area-thumb | aria-valuemax | '100' |
area-thumb | aria-valuemin | '0' |
area-thumb | aria-valuenow | String(Math.round(hsva.s)) |
area-thumb | aria-valuetext | label.areaValueText(Math.round(hsva.s), Math.round(hs… |
area-thumb | role | 'slider' |
channel-input | aria-invalid | 'true' | 'false' |
channel-input | aria-label | label.input(channel) |
eye-dropper-trigger | aria-label | label.eyeDropperTrigger |
hidden-input | aria-hidden | 'true' |
- 触发按钮是原生按钮，
aria-haspopup="dialog"，名称由标题与当前值串合成，未选时念占位提示；浮层是非模态role="dialog"。 - 清空钮不占 Tab 位（整个控件只占触发钮一个 Tab 位），可及名取
translations.clearTrigger；按下后焦点回到触发钮。 - 多选标签上的删除钮不占 Tab 位，可及名取
translations.deleteItem；键盘从触发钮上按退格摘掉最后一个。色点只是辅助，标签文字就是值串，颜色不是唯一的信息通道。 - 取色面的拇指是
role="slider"：aria-valuenow报告饱和度，明度写入aria-valuetext。 - 两条滑块的名称与带单位的播报文本取自
translations.channel/channelValueText，由内嵌滑块读出。 - 色板是
role="radiogroup"，每格role="radio"；整组名称取translations.swatchGroup，每格读translations.swatch(value)；最近使用色同一套，整组名称取translations.recentSwatchGroup。 - 常驻形态的取色面是
role="group"，由标题命名，不是对话框。 - Escape 收起浮层并把焦点归还触发按钮。
样式参考
皮肤
@xihan-ui/styles/color-picker.css 按 [data-scope="color-picker"][data-part="root"] 部件选择器书写，发布产物以挂载类 .xh-scope-color-picker 代替其中的 data-scope（特异性相同），位于 xihan.components 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。
forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-disabled | ''（条件成立时才出现） |
root | data-inline | ''（条件成立时才出现） |
root | data-invalid | ''（条件成立时才出现） |
root | data-readonly | ''（条件成立时才出现） |
root | data-required | ''（条件成立时才出现） |
root | data-size | props.size |
root | data-state | 'open' | 'closed' |
label | data-disabled | ''（条件成立时才出现） |
label | data-invalid | ''（条件成立时才出现） |
label | data-readonly | ''（条件成立时才出现） |
label | data-required | ''（条件成立时才出现） |
label | data-state | 'open' | 'closed' |
control | data-disabled | ''（条件成立时才出现） |
control | data-invalid | ''（条件成立时才出现） |
control | data-readonly | ''（条件成立时才出现） |
control | data-required | ''（条件成立时才出现） |
control | data-state | 'open' | 'closed' |
control | data-variant | props.variant |
control | data-xh-action-owner | '' |
control | data-xh-field-chrome | '' |
control | data-xh-field-layout | 'multi-tag' | undefined |
control | data-xh-field-size | props.size |
tag-list | data-disabled | ''（条件成立时才出现） |
tag-list | data-instant | ''（条件成立时才出现） |
tag-list | data-xh-tag-list | '' |
trigger | data-disabled | ''（条件成立时才出现） |
trigger | data-invalid | ''（条件成立时才出现） |
trigger | data-readonly | ''（条件成立时才出现） |
trigger | data-required | ''（条件成立时才出现） |
trigger | data-state | 'open' | 'closed' |
clear-trigger | data-xh-action-control | '' |
clear-trigger | data-xh-action-display | 'has-value' |
clear-trigger | data-xh-action-has-value | ''（条件成立时才出现） |
clear-trigger | data-xh-action-profile | 'field-inset' |
clear-trigger | data-xh-action-size | props.size |
clear-trigger | data-xh-action-variant | 'ghost' |
value-text | data-disabled | ''（条件成立时才出现） |
value-text | data-invalid | ''（条件成立时才出现） |
value-text | data-placeholder | ''（条件成立时才出现） |
value-text | data-readonly | ''（条件成立时才出现） |
value-text | data-required | ''（条件成立时才出现） |
value-text | data-state | 'open' | 'closed' |
swatch | data-disabled | ''（条件成立时才出现） |
swatch | data-empty | ''（条件成立时才出现） |
swatch | data-invalid | ''（条件成立时才出现） |
swatch | data-readonly | ''（条件成立时才出现） |
swatch | data-required | ''（条件成立时才出现） |
swatch | data-state | 'open' | 'closed' |
swatch | data-value | undefined | context.get('value') |
swatch | data-xh-swatch | '' |
swatch | data-xh-swatch-size | props.size |
positioner | data-hidden | ''（条件成立时才出现） |
positioner | data-placement | 定位引擎算出的实际落位 |
positioner | data-positioned | ''（条件成立时才出现） |
positioner | data-size | props.size |
positioner | data-state | 'open' | 'closed' |
content | data-disabled | ''（条件成立时才出现） |
content | data-inline | ''（条件成立时才出现） |
content | data-instant | ''（条件成立时才出现） |
content | data-invalid | ''（条件成立时才出现） |
content | data-placement | undefined | 定位引擎算出的实际落位 |
content | data-readonly | ''（条件成立时才出现） |
content | data-required | ''（条件成立时才出现） |
content | data-state | 'open' | 'closed' |
saturation-area | data-disabled | ''（条件成立时才出现） |
saturation-area | data-dragging | ''（条件成立时才出现） |
saturation-area | data-invalid | ''（条件成立时才出现） |
saturation-area | data-readonly | ''（条件成立时才出现） |
saturation-area | data-required | ''（条件成立时才出现） |
saturation-area | data-state | 'open' | 'closed' |
area-thumb | data-disabled | ''（条件成立时才出现） |
area-thumb | data-dragging | ''（条件成立时才出现） |
area-thumb | data-invalid | ''（条件成立时才出现） |
area-thumb | data-readonly | ''（条件成立时才出现） |
area-thumb | data-required | ''（条件成立时才出现） |
area-thumb | data-state | 'open' | 'closed' |
hue-slider | data-channel | 'hue' |
alpha-slider | data-channel | 'alpha' |
alpha-slider | data-disabled | ''（条件成立时才出现） |
channel-input | data-channel | channel |
channel-input | data-disabled | ''（条件成立时才出现） |
channel-input | data-invalid | ''（条件成立时才出现） |
channel-input | data-readonly | ''（条件成立时才出现） |
channel-input | data-required | ''（条件成立时才出现） |
channel-input | data-state | 'open' | 'closed' |
eye-dropper-trigger | data-disabled | ''（条件成立时才出现） |
eye-dropper-trigger | data-invalid | ''（条件成立时才出现） |
eye-dropper-trigger | data-pressed | ''（条件成立时才出现） |
eye-dropper-trigger | data-readonly | ''（条件成立时才出现） |
eye-dropper-trigger | data-required | ''（条件成立时才出现） |
eye-dropper-trigger | data-state | 'picking' | 'open' | 'closed' |
confirm-trigger | data-disabled | ''（条件成立时才出现） |
confirm-trigger | data-xh-action-control | '' |
confirm-trigger | data-xh-action-display | 'always' |
confirm-trigger | data-xh-action-profile | 'text' |
confirm-trigger | data-xh-action-size | 'sm' |
confirm-trigger | data-xh-action-variant | 'solid' |
confirm-trigger | data-xh-ink-surface | '' |
overflow-tag | data-count | String(overflowCount) |
tag | data-value | v |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-color-picker-action-bg | clear-triggereye-dropper-trigger | --xh-ink-surfacebackgroundbackground-color | defaultxh-ink-surface | --xh-_action-variant-bg-resttransparent | color-picker 的 clear-trigger、eye-dropper-trigger 部件 --xh-ink-surface、background、background-color 覆盖槽。 |
--xh-color-picker-action-bg-active | clear-triggereye-dropper-trigger | backgroundbackground-color | disabledis(:active, [data-pressed])loadingnot(:disabled)not([data-disabled])not([data-loading])pressedstate=picking | --xh-_action-variant-bg-pressed--xh-bg-subtle-active--xh-bg-subtle-hover | color-picker 的 clear-trigger、eye-dropper-trigger 部件 background、background-color 覆盖槽。 |
--xh-color-picker-action-bg-hover | clear-triggereye-dropper-trigger | backgroundbackground-color | disabledhoverloadingnot(:disabled)not([data-disabled])not([data-loading]) | --xh-_action-variant-bg-hover--xh-bg-subtle | color-picker 的 clear-trigger、eye-dropper-trigger 部件 background、background-color 覆盖槽。 |
--xh-color-picker-action-border | eye-dropper-trigger | border | default | --xh-border-control | color-picker 的 eye-dropper-trigger 部件 border 覆盖槽。 |
--xh-color-picker-action-border-active | eye-dropper-trigger | border-color | state=picking | --xh-bg-brand | color-picker 的 eye-dropper-trigger 部件 border-color 覆盖槽。 |
--xh-color-picker-action-fg | clear-triggereye-dropper-trigger | color | default | --xh-fg-field-clear--xh-fg-muted | color-picker 的 clear-trigger、eye-dropper-trigger 部件 color 覆盖槽。 |
--xh-color-picker-action-fg-hover | clear-triggereye-dropper-trigger | color | disabledhoverloadingnot(:disabled)not([data-disabled])not([data-loading]) | --xh-fg-default | color-picker 的 clear-trigger、eye-dropper-trigger 部件 color 覆盖槽。 |
--xh-color-picker-action-font-size | clear-triggereye-dropper-trigger | font-size | default | --xh-text-secondary-size | color-picker 的 clear-trigger、eye-dropper-trigger 部件 font-size 覆盖槽。 |
--xh-color-picker-action-radius | clear-triggereye-dropper-trigger | border-radius | default | --xh-shape-circle--xh-shape-control | color-picker 的 clear-trigger、eye-dropper-trigger 部件 border-radius 覆盖槽。 |
--xh-color-picker-action-size | clear-triggereye-dropper-trigger | block-sizeinline-sizemin-inline-size | defaultxh-action-profile=field-inset | --xh-_action-profile-visual-size--xh-control-action-size | color-picker 的 clear-trigger、eye-dropper-trigger 部件 block-size、inline-size、min-inline-size 覆盖槽。 |
--xh-color-picker-alpha-slider-gap | alpha-slider | gap | default | --xh-stack-gap-md | color-picker 的 alpha-slider 部件 gap 覆盖槽。 |
--xh-color-picker-confirm-trigger-bg | confirm-trigger | --xh-ink-surfacebackground-color | defaultxh-ink-surface | --xh-_action-variant-bg-rest | color-picker 的 confirm-trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-color-picker-confirm-trigger-bg-active | confirm-trigger | background-color | disabledis(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | --xh-_action-variant-bg-pressed | color-picker 的 confirm-trigger 部件 background-color 覆盖槽。 |
--xh-color-picker-confirm-trigger-bg-hover | confirm-trigger | background-color | disabledhoverloadingnot([data-disabled])not([data-loading]) | --xh-_action-variant-bg-hover | color-picker 的 confirm-trigger 部件 background-color 覆盖槽。 |
--xh-color-picker-confirm-trigger-fg | confirm-trigger | color | defaultdisabledhoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | --xh-_action-variant-fg-hover--xh-_action-variant-fg-pressed--xh-_action-variant-fg-rest | color-picker 的 confirm-trigger 部件 color 覆盖槽。 |
--xh-color-picker-confirm-trigger-h | confirm-trigger | block-sizeinline-size | defaultxh-action-profile=field-inset | --xh-control-action-size | color-picker 的 confirm-trigger 部件 block-size、inline-size 覆盖槽。 |
--xh-color-picker-confirm-trigger-px | confirm-trigger | padding-inline | default | --xh-_action-profile-padding-inline | color-picker 的 confirm-trigger 部件 padding-inline 覆盖槽。 |
--xh-color-picker-confirm-trigger-radius | confirm-trigger | border-radius | default | --xh-shape-control | color-picker 的 confirm-trigger 部件 border-radius 覆盖槽。 |
--xh-color-picker-confirm-trigger-shadow | confirm-trigger | box-shadow | defaultdisabledhoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | none | color-picker 的 confirm-trigger 部件 box-shadow 覆盖槽。 |
--xh-color-picker-content-bg | content | background | default | --xh-bg-surface | color-picker 的 content 部件 background 覆盖槽。 |
--xh-color-picker-content-border | content | border | default | --xh-border-default | color-picker 的 content 部件 border 覆盖槽。 |
--xh-color-picker-content-fg | content | color | default | --xh-fg-default | color-picker 的 content 部件 color 覆盖槽。 |
--xh-color-picker-content-gap | content | gap | default | --xh-space-3 | color-picker 的 content 部件 gap 覆盖槽。 |
--xh-color-picker-content-px | contentrecent-swatch-pickersaturation-areaswatch-picker | margin-inlinepadding-inline | defaultfirst-childis([data-part='swatch-picker'], [data-part='recent-swatch-picker'])not(:is([data-part='swatch-picker'], [data-part='recent-swatch-picker']) | --xh-space-3 | color-picker 的 content、recent-swatch-picker、saturation-area、swatch-picker 部件 margin-inline、padding-inline 覆盖槽。 |
--xh-color-picker-content-py | contentrecent-swatch-pickersaturation-areaswatch-picker | margin-block-startpadding-blockpadding-block-start | defaultfirst-childis([data-part='swatch-picker'], [data-part='recent-swatch-picker'])not(:is([data-part='swatch-picker'], [data-part='recent-swatch-picker']) | --xh-space-3 | color-picker 的 content、recent-swatch-picker、saturation-area、swatch-picker 部件 margin-block-start、padding-block、padding-block-start 覆盖槽。 |
--xh-color-picker-content-radius | content | border-radius | defaultinline | --xh-shape-overlay--xh-shape-surface | color-picker 的 content 部件 border-radius 覆盖槽。 |
--xh-color-picker-content-shadow | content | box-shadow | defaultinline | --xh-elevation-floatingnone | color-picker 的 content 部件 box-shadow 覆盖槽。 |
--xh-color-picker-content-w | content | inline-size | default | --xh-overlay-max-w-sm | color-picker 的 content 部件 inline-size 覆盖槽。 |
--xh-color-picker-control-bg | control | background-color | xh-field-chrome | --xh-_field-variant-bg-rest | color-picker 的 control 部件 background-color 覆盖槽。 |
--xh-color-picker-control-bg-disabled | control | background-color | disabledxh-field-chrome | --xh-_field-variant-bg-disabled | color-picker 的 control 部件 background-color 覆盖槽。 |
--xh-color-picker-control-bg-hover | control | background-color | disabledhoverinvalidloadingnot(:focus-within)not([data-disabled])not([data-invalid])not([data-loading])not([data-readonly])readonlyxh-field-chrome | --xh-_field-variant-bg-hover | color-picker 的 control 部件 background-color 覆盖槽。 |
--xh-color-picker-control-bg-readonly | control | background-color | readonlyxh-field-chrome | --xh-_field-variant-bg-read-only | color-picker 的 control 部件 background-color 覆盖槽。 |
--xh-color-picker-control-border | control | border | xh-field-chrome | --xh-_field-variant-border-rest | color-picker 的 control 部件 border 覆盖槽。 |
--xh-color-picker-control-border-focus | control | border-colorbox-shadow | disabledfocus-withinnot([data-disabled])xh-field-chrome | --xh-_field-variant-border-focus | color-picker 的 control 部件 border-color、box-shadow 覆盖槽。 |
--xh-color-picker-control-border-hover | control | border-color | disabledhoverinvalidloadingnot(:focus-within)not([data-disabled])not([data-invalid])not([data-loading])not([data-readonly])readonlyxh-field-chrome | --xh-_field-variant-border-hover | color-picker 的 control 部件 border-color 覆盖槽。 |
--xh-color-picker-control-border-invalid | control | border-color | invalidxh-field-chrome | --xh-_field-variant-border-invalid | color-picker 的 control 部件 border-color 覆盖槽。 |
--xh-color-picker-control-fg | control | color | xh-field-chrome | --xh-fg-default | color-picker 的 control 部件 color 覆盖槽。 |
--xh-color-picker-control-gap | control | gap | xh-field-chrome | --xh-_color-picker-gap | color-picker 的 control 部件 gap 覆盖槽。 |
--xh-color-picker-control-h | control | block-sizemin-block-size | has([data-xh-field-input][data-xh-field-layout='multi-tag'])has([data-xh-field-input][data-xh-field-layout='single-line'])has([data-xh-field-input][data-xh-field-layout='textarea'])xh-field-chromexh-field-inputxh-field-layout=multi-tagxh-field-layout=single-linexh-field-layout=textarea | --xh-_color-picker-h | color-picker 的 control 部件 block-size、min-block-size 覆盖槽。 |
--xh-color-picker-control-max-h | control | max-block-size | xh-field-layout=multi-tag | --xh-viewport-h-sm | color-picker 的 control 部件 max-block-size 覆盖槽。 |
--xh-color-picker-control-min-w | controlroot | min-inline-size | defaultxh-field-chrome | --xh-control-min-w | color-picker 的 control、root 部件 min-inline-size 覆盖槽。 |
--xh-color-picker-control-px | control | padding-inline | xh-field-chrome | --xh-_color-picker-px | color-picker 的 control 部件 padding-inline 覆盖槽。 |
--xh-color-picker-control-radius | control | border-radius | xh-field-chrome | --xh-shape-control | color-picker 的 control 部件 border-radius 覆盖槽。 |
--xh-color-picker-control-shadow | control | box-shadow | xh-field-chrome | none | color-picker 的 control 部件 box-shadow 覆盖槽。 |
--xh-color-picker-control-w | root | inline-sizemin-inline-size | default | --xh-control-w | color-picker 的 root 部件 inline-size、min-inline-size 覆盖槽。 |
--xh-color-picker-gap | labelroot | gapmargin-block-end | default | --xh-space-1 | color-picker 的 label、root 部件 gap、margin-block-end 覆盖槽。 |
--xh-color-picker-hue-slider-gap | hue-slider | gap | default | --xh-stack-gap-md | color-picker 的 hue-slider 部件 gap 覆盖槽。 |
--xh-color-picker-icon-size | positionerroot | --xh-icon-size | defaultis([data-part='root'], [data-part='positioner'])size=lgsize=sm | --xh-glyph-size-lg--xh-glyph-size-md--xh-glyph-size-sm | color-picker 的 positioner、root 部件 --xh-icon-size 覆盖槽。 |
--xh-color-picker-input-bg | channel-input | background | default | --xh-bg-field | color-picker 的 channel-input 部件 background 覆盖槽。 |
--xh-color-picker-input-bg-disabled | channel-input | background | disabled | --xh-bg-subtle | color-picker 的 channel-input 部件 background 覆盖槽。 |
--xh-color-picker-input-bg-focus | channel-input | background | focus | --xh-bg-surface | color-picker 的 channel-input 部件 background 覆盖槽。 |
--xh-color-picker-input-bg-readonly | channel-input | background | readonly | --xh-bg-subtle | color-picker 的 channel-input 部件 background 覆盖槽。 |
--xh-color-picker-input-border | channel-input | border | default | --xh-border-control | color-picker 的 channel-input 部件 border 覆盖槽。 |
--xh-color-picker-input-border-focus | channel-input | border-colorbox-shadow | focus | --xh-border-control-focus | color-picker 的 channel-input 部件 border-color、box-shadow 覆盖槽。 |
--xh-color-picker-input-border-hover | channel-input | border-color | hoverinvalidnot(:disabled, :focus, [data-readonly], [data-invalid])readonly | --xh-border-strong | color-picker 的 channel-input 部件 border-color 覆盖槽。 |
--xh-color-picker-input-border-invalid | channel-input | border-color | invalid | --xh-border-invalid | color-picker 的 channel-input 部件 border-color 覆盖槽。 |
--xh-color-picker-input-font-size | channel-input | font-size | default | --xh-text-caption-size | color-picker 的 channel-input 部件 font-size 覆盖槽。 |
--xh-color-picker-input-h | channel-input | block-size | default | --xh-control-action-size | color-picker 的 channel-input 部件 block-size 覆盖槽。 |
--xh-color-picker-input-px | channel-input | padding-inline | default | --xh-control-px-sm | color-picker 的 channel-input 部件 padding-inline 覆盖槽。 |
--xh-color-picker-input-radius | channel-input | border-radius | default | --xh-shape-control | color-picker 的 channel-input 部件 border-radius 覆盖槽。 |
--xh-color-picker-label-fg | label | color | default | --xh-fg-muted | color-picker 的 label 部件 color 覆盖槽。 |
--xh-color-picker-label-font-size | label | font-size | default | --xh-text-label-size | color-picker 的 label 部件 font-size 覆盖槽。 |
--xh-color-picker-label-font-weight | label | font-weight | default | --xh-text-label-weight | color-picker 的 label 部件 font-weight 覆盖槽。 |
--xh-color-picker-label-gap | label | margin-block-end | default | --xh-space-2 | color-picker 的 label 部件 margin-block-end 覆盖槽。 |
--xh-color-picker-layer | positioner | z-index | default | --xh-_layer | color-picker 的 positioner 部件 z-index 覆盖槽。 |
--xh-color-picker-max-h | content | max-block-size | default | --xh-viewport-h-lg | color-picker 的 content 部件 max-block-size 覆盖槽。 |
--xh-color-picker-placeholder-fg | value-text | color | placeholder | --xh-fg-subtle | color-picker 的 value-text 部件 color 覆盖槽。 |
--xh-color-picker-saturation-area-h | saturation-area | block-size | default | --xh-overlay-color-area-h | color-picker 的 saturation-area 部件 block-size 覆盖槽。 |
--xh-color-picker-saturation-area-radius | contentsaturation-area | border-radius | defaultfirst-child | --xh-shape-control0 | color-picker 的 content、saturation-area 部件 border-radius 覆盖槽。 |
--xh-color-picker-separator | contentrecent-swatch-pickerswatch-picker | border-block-start | is([data-part='swatch-picker'], [data-part='recent-swatch-picker'])not(:is([data-part='swatch-picker'], [data-part='recent-swatch-picker']) | --xh-material-solid-border | color-picker 的 content、recent-swatch-picker、swatch-picker 部件 border-block-start 覆盖槽。 |
--xh-color-picker-slider-thumb-bg | alpha-sliderhue-sliderthumb | background | is([data-part='hue-slider'], [data-part='alpha-slider']) | --xh-bg-surface-raised | color-picker 的 alpha-slider、hue-slider、thumb 部件 background 覆盖槽。 |
--xh-color-picker-slider-thumb-size | alpha-sliderhue-slider | --xh-_thumb-size | default | --xh-control-indicator-md | color-picker 的 alpha-slider、hue-slider 部件 --xh-_thumb-size 覆盖槽。 |
--xh-color-picker-slider-track-thickness | alpha-sliderhue-slider | --xh-_track-thickness | default | --xh-space-3 | color-picker 的 alpha-slider、hue-slider 部件 --xh-_track-thickness 覆盖槽。 |
--xh-color-picker-swatch-border | swatch | --xh-swatch-border | default | --xh-border-default | color-picker 的 swatch 部件 --xh-swatch-border 覆盖槽。 |
--xh-color-picker-swatch-cell | recent-swatch-pickerswatch-picker | --xh-_color-swatch-picker-cell | @media (pointer: coarse)is([data-part='swatch-picker'], [data-part='recent-swatch-picker']) | --xh-control-h-sm--xh-glyph-size-sm | color-picker 的 recent-swatch-picker、swatch-picker 部件 --xh-_color-swatch-picker-cell 覆盖槽。 |
--xh-color-picker-swatch-empty-stroke | swatch | background-image | empty | --xh-border-control | color-picker 的 swatch 部件 background-image 覆盖槽。 |
--xh-color-picker-swatch-gap | recent-swatch-pickerswatch-picker | gap | is([data-part='swatch-picker'], [data-part='recent-swatch-picker']) | --xh-space-2 | color-picker 的 recent-swatch-picker、swatch-picker 部件 gap 覆盖槽。 |
--xh-color-picker-swatch-icon-size | recent-swatch-pickerswatch-picker | --xh-icon-size | is([data-part='swatch-picker'], [data-part='recent-swatch-picker']) | --xh-_color-swatch-picker-mark | color-picker 的 recent-swatch-picker、swatch-picker 部件 --xh-icon-size 覆盖槽。 |
--xh-color-picker-swatch-picker-gap | recent-swatch-pickerswatch-picker | gap | is([data-part='swatch-picker'], [data-part='recent-swatch-picker']) | --xh-_color-swatch-picker-gap | color-picker 的 recent-swatch-picker、swatch-picker 部件 gap 覆盖槽。 |
--xh-color-picker-swatch-radius | swatch | --xh-swatch-radius | default | --xh-shape-inset | color-picker 的 swatch 部件 --xh-swatch-radius 覆盖槽。 |
--xh-color-picker-swatch-size | swatch | --xh-swatch-size | default | --xh-_swatch-size | color-picker 的 swatch 部件 --xh-swatch-size 覆盖槽。 |
--xh-color-picker-tag-dot-border | roottag-list | border | value | --xh-border-default | color-picker 的 root、tag-list 部件 border 覆盖槽。 |
--xh-color-picker-tag-dot-size | roottag-list | block-sizeinline-size | value | --xh-control-indicator-sm | color-picker 的 root、tag-list 部件 block-size、inline-size 覆盖槽。 |
--xh-color-picker-tag-list-gap | tag-list | gap | xh-tag-list | --xh-space-1 | color-picker 的 tag-list 部件 gap 覆盖槽。 |
--xh-color-picker-thumb-border | area-thumb | border | default | --xh-color-neutral-0 | color-picker 的 area-thumb 部件 border 覆盖槽。 |
--xh-color-picker-thumb-edge | area-thumb | box-shadow | default | --xh-border-default-opaque | color-picker 的 area-thumb 部件 box-shadow 覆盖槽。 |
--xh-color-picker-thumb-radius | area-thumb | border-radius | default | --xh-shape-circle | color-picker 的 area-thumb 部件 border-radius 覆盖槽。 |
--xh-color-picker-thumb-size | area-thumb | block-sizeinline-sizemargin-block-startmargin-inline-start | default | --xh-control-indicator-md | color-picker 的 area-thumb 部件 block-size、inline-size、margin-block-start、margin-inline-start 覆盖槽。 |
--xh-color-picker-trigger-fg | trigger | color | default | --xh-fg-default | color-picker 的 trigger 部件 color 覆盖槽。 |
--xh-color-picker-trigger-font-size | trigger | font-size | default | --xh-text-body-size | color-picker 的 trigger 部件 font-size 覆盖槽。 |
--xh-color-picker-trigger-gap | trigger | gap | default | --xh-_color-picker-gap | color-picker 的 trigger 部件 gap 覆盖槽。 |
--xh-color-picker-value-fg | value-text | color | default | --xh-fg-default | color-picker 的 value-text 部件 color 覆盖槽。 |
--xh-color-picker-value-font-size | value-text | font-size | default | --xh-text-body-size | color-picker 的 value-text 部件 font-size 覆盖槽。 |
动效
动效角色：按压 · 状态 · 指示与换位 · 出现 · 列表（见动效规范）。
共享关键帧 xh-fade-in · xh-fade-out · xh-overlay-pop-in · xh-pop-in · xh-pop-out 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立；background-color · border-color · color · scale · translate 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。
皮肤之外还有一段：退场由适配器的退场闸门把关，动画播完才真收起。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。
响应式
皮肤另按输入能力分档：pointer: coarse：同一份皮肤在触屏与带指针的设备上不一样，与视口宽度无关。
- 浮层的宽度与高度分别受可用空间约束，窄视口下面板不会超出屏幕，容纳不下时在面板内滚动。
- 粗指针下命中区是取色面、滑块整条与色板整格。
- 不写结构时按标准结构铺出整套部件（Vue 不写默认插槽、React 不给 children、Web Components 不写部件或只写
root），三端出自同一个结构函数：label给标题文字，接着是盒（多选时先是标签行，再是带色块与值串的触发钮）、表单影子（给了name才有）与浮层；inline时取色面直接铺在 root 里。取色面里依次是取色区、色相滑块、透明度滑块（开了alpha才有）、十六进制输入框、预设色板（给了swatches才有）、最近使用色，多选时末尾是「添加」，字取translations.confirmTrigger。屏幕取色按钮要放图标，不在其中，要用时手写结构。Web Components 里标题可以写在宿主的直接子节点slot="label"上接管。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像；另有按 dir 分支的规则。
dir="rtl"只对调横轴（取色面的饱和度、两条滑块）上左右方向键与指针的语义，上下方向键始终是屏幕向上为增大。