颜色选择器
概述
组合式颜色选择器，内置颜色区域、色相/透明度滑块、格式化输入框和预设色板，并支持 oklch 输出与编辑。SColorPicker 在 popover 内组合 Aria 颜色基础组件（ColorArea/ColorSlider/ColorField/ColorSwatch/ColorSwatchPicker），以 SegmentCompact 切换格式。子部件样式统一写在 colorPickerVariants 中，经 provideColorPickerUi 转发。
颜色选择器适合完整的颜色选择 UI（格式页签、饱和度平面、色相/透明度滑块、预设色板与格式化输入）。
用法
特性
- 🧩 组合式 Aria — 在
Popover内组合ColorArea/ColorSlider/ColorField/ColorSwatchPicker，各自零样式 - 🎛️ 格式页签 —
SegmentCompact切换hex/rgb/hsl/oklch；update:format反映当前格式 - 🎨 完整
oklch支持 —colorSpace="oklch"带色度/明度区域与 OKLCH 格式化输出 - 🎚️ 色相 + 透明度滑块 —
showAlpha切换 alpha 通道滑块与输入框 - 📝 格式化输入框 —
showFields渲染 hex/格式输入加 alpha 输入 - 🖼️ 预设色板 —
showSwatches+swatches渲染可点击预设（ColorSwatchPicker） - 🪟 Popover 触发器 —
open/modal/placement，触发器显示当前值 - 🔒 禁用 —
disabled禁用所有控件 - 📐 6 种尺寸 — xs–2xl
size；逐部分ui覆盖
组件家族
SColorPicker（样式层）— 入口包装组件；计算colorPickerVariants并调用provideColorPickerUiColorPickerCompact（Aria）— 聚合组件；连接根、popover、区域、滑块、输入框与色板ColorPickerRoot（Aria）— 共享颜色状态（color/hexValue/displayFormat/areaChannel/setColor/setFormat）ColorPickerTrigger（Aria）— 显示当前值的按钮- 底层基础组件 —
ColorAreaCompact、ColorSliderCompact、ColorFieldCompact、ColorSwatchCompact、ColorSwatchPickerCompact、PopoverCompact、SegmentCompact
演示
基础
100%
OKLCH
100%
API
Aria 层
4ColorPicker
35 属性12 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 应用于触发元素的额外类名。 |
size | ThemeSize | — | 组件的视觉尺寸。 |
ui | Partial<ColorPickerUi> | — | 该组件的按槽类重写。 |
showAlpha | boolean | — | 是否显示 alpha 版本。 |
showFields | boolean | — | 是否显示字段。 |
showSwatches | boolean | — | 是否显示色板。 |
swatches | string[] | — | 示例。 |
swatchProps | ColorSwatchCompactProps | — | 传递给 swatch 元素的属性。 |
segmentProps | SegmentCompactProps<T extends SegmentOptionData> | — | 已转发至段落元素的属性。 |
areaProps | ColorAreaCompactProps | — | 转发给 area 元素的属性。 |
hueSliderProps | ColorSliderCompactProps | — | 传递给色相滑块元素的属性。 |
alphaSliderProps | ColorSliderCompactProps | — | 传递给 alpha 滑块元素的属性。 |
alphaFieldProps | ColorFieldCompactProps | — | 转发至 alpha 字段元素的属性。 |
fieldProps | ColorFieldCompactProps | — | 转发到 field 元素的属性。 |
swatchPickerProps | ColorSwatchPickerCompactProps<M extends boolean = false> | — | 传递给色板选择器元素的属性。 |
modelValue | import("@soybeanjs/colord").AnyColor | — | 当前模型值。 |
defaultValue | import("@soybeanjs/colord").AnyColor | — | 默认值。 |
format | ColorFormat | — | 格式。 |
defaultFormat | ColorFormat | — | 默认格式。 |
colorSpace | ColorSpace | — | 色彩空间。 |
disabled | boolean | — | 该组件是否已禁用。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
placement | import("@/index").Placement | — | 位置。 |
showArrow | boolean | — | 是否显示箭头。 |
triggerProps | PopoverTriggerProps | — | 转发给触发元素的属性。 |
portalProps | PopperPortalProps | — | 转发给 portal 元素的属性。 |
positionerProps | PopoverPositionerProps | — | 转发给定位器元素的属性。 |
popupProps | PopoverPopupProps | — | 转发给弹出窗口元素的属性。 |
arrowProps | PopperArrowProps | — | 转发给箭头元素的属性。 |
closeProps | PopoverCloseProps | — | 转发至 close 元素的属性。 |
dir | Direction | — | — |
open | boolean | — | — |
defaultOpen | boolean | — | — |
modal | boolean | — | — |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
update:color | NormalizedColor | 当颜色值发生变化时触发。 |
update:format | ColorFormat | 当格式值发生变化时触发。 |
change | string | 在发生变更时触发。 |
update:open | boolean | 当对话框的打开状态发生变化时调用的事件处理程序。 |
escapeKeyDown | KeyboardEvent | 当 Esc 键被按下时触发的事件处理程序。可被阻止。 |
pointerDownOutside | PointerDownOutsideEvent | 当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。 |
focusOutside | FocusOutsideEvent | 当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。 |
interactOutside | PointerDownOutsideEvent | FocusOutsideEvent | 当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown`
事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。 |
openAutoFocus | Event | 在打开页面时自动聚焦时触发的事件处理程序。可被阻止。 |
closeAutoFocus | Event | 在关闭时自动聚焦时触发的事件处理程序。可被阻止。 |
placed | — | — |
ColorPickerCompact
32 属性12 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
showAlpha | boolean | — | 是否显示 alpha 版本。 |
showFields | boolean | — | 是否显示字段。 |
showSwatches | boolean | — | 是否显示色板。 |
swatches | string[] | — | 示例。 |
swatchProps | ColorSwatchCompactProps | — | 传递给 swatch 元素的属性。 |
segmentProps | SegmentCompactProps<T extends SegmentOptionData> | — | 已转发至段落元素的属性。 |
areaProps | ColorAreaCompactProps | — | 转发给 area 元素的属性。 |
hueSliderProps | ColorSliderCompactProps | — | 传递给色相滑块元素的属性。 |
alphaSliderProps | ColorSliderCompactProps | — | 传递给 alpha 滑块元素的属性。 |
alphaFieldProps | ColorFieldCompactProps | — | 转发至 alpha 字段元素的属性。 |
fieldProps | ColorFieldCompactProps | — | 转发到 field 元素的属性。 |
swatchPickerProps | ColorSwatchPickerCompactProps<M extends boolean = false> | — | 传递给色板选择器元素的属性。 |
modelValue | import("@soybeanjs/colord").AnyColor | — | 当前模型值。 |
defaultValue | import("@soybeanjs/colord").AnyColor | — | 默认值。 |
format | ColorFormat | — | 格式。 |
defaultFormat | ColorFormat | — | 默认格式。 |
colorSpace | ColorSpace | — | 色彩空间。 |
disabled | boolean | — | 该组件是否已禁用。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
placement | import("@/index").Placement | — | 位置。 |
showArrow | boolean | — | 是否显示箭头。 |
triggerProps | PopoverTriggerProps | — | 转发给触发元素的属性。 |
portalProps | PopperPortalProps | — | 转发给 portal 元素的属性。 |
positionerProps | PopoverPositionerProps | — | 转发给定位器元素的属性。 |
popupProps | PopoverPopupProps | — | 转发给弹出窗口元素的属性。 |
arrowProps | PopperArrowProps | — | 转发给箭头元素的属性。 |
closeProps | PopoverCloseProps | — | 转发至 close 元素的属性。 |
dir | Direction | — | — |
open | boolean | — | — |
defaultOpen | boolean | — | — |
modal | boolean | — | — |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
update:color | NormalizedColor | 当颜色值发生变化时触发。 |
update:format | ColorFormat | 当格式值发生变化时触发。 |
change | string | 在发生变更时触发。 |
update:open | boolean | 当对话框的打开状态发生变化时调用的事件处理程序。 |
escapeKeyDown | KeyboardEvent | 当 Esc 键被按下时触发的事件处理程序。可被阻止。 |
pointerDownOutside | PointerDownOutsideEvent | 当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。 |
focusOutside | FocusOutsideEvent | 当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。 |
interactOutside | PointerDownOutsideEvent | FocusOutsideEvent | 当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown`
事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。 |
openAutoFocus | Event | 在打开页面时自动聚焦时触发的事件处理程序。可被阻止。 |
closeAutoFocus | Event | 在关闭时自动聚焦时触发的事件处理程序。可被阻止。 |
placed | — | — |
ColorPickerRoot
8 属性4 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
modelValue | import("@soybeanjs/colord").AnyColor | — | 当前模型值。 |
defaultValue | import("@soybeanjs/colord").AnyColor | — | 默认值。 |
format | ColorFormat | — | 格式。 |
defaultFormat | ColorFormat | — | 默认格式。 |
colorSpace | ColorSpace | — | 色彩空间。 |
disabled | boolean | — | 该组件是否已禁用。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
update:color | NormalizedColor | 当颜色值发生变化时触发。 |
update:format | ColorFormat | 当格式值发生变化时触发。 |
change | string | 在发生变更时触发。 |
ColorPickerTrigger
4 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
注意事项
架构与对标差异
ColorPickerCompact 负责跨基础组件组合（根状态 + popover + 区域 + 滑块 + 输入框 + 色板 + 页签），所有底层基础组件保持零样式。UI 包装组件通过 provideColorPickerUi 注入一份 colorPickerVariants map，再把别名 slot 映射到各子树的 provide*Ui。这与 radix-ui-color/shadcn-ui 的 headless 分离一致。Ant Design、Element Plus、Mantine、Naive UI 提供带 showAlpha/presets prop 的单一样式化颜色选择器；VeanUI 暴露带显式格式页签、完整 oklch 编辑与 size 尺寸体系的组合式选择器。
| 能力 | VeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
|---|---|---|---|---|---|---|
| 组合式基础组件 | ✅ | ✅ | — | — | — | — |
| 格式页签 | ✅ | ✅ | — | — | — | — |
| 完整 oklch 编辑 | ✅ | ✅ | — | — | — | — |
| 色相 + 透明度滑块 | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| 预设色板 | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| 尺寸（6） | ✅ | — | — | — | — | — |
— = 不支持或采用不同交互模型。
运行时注意
colorSpace（默认hsl）驱动区域通道与输出；defaultFormat/format选择初始/受控格式页签。showAlpha（默认true）添加 alpha 滑块与 alpha 输入；showFields/showSwatches切换输入/预设区。swatches为预设颜色数组；选择其一发出update:modelValue与change。- 选择器在
Popover中打开；受控场景用v-model:open绑定open。 - 这是最高层颜色组件；嵌入式轻量编辑器请优先使用单个
color-area/color-slider/color-field。
Roadmap
不适用——color-picker 对当前对标集已功能完备。
FAQ
如何使用颜色选择器？
绑定 model-value，可选 swatches：
<SColorPicker v-model:model-value="color" :swatches="['#7c3aed', '#06b6d4']" />如何启用 OKLCH 编辑？
设置 color-space 与 default-format：
<SColorPicker v-model:model-value="color" color-space="oklch" default-format="oklch" />如何切换分区？
使用 show-alpha/show-fields/show-swatches：
<SColorPicker v-model:model-value="color" :show-alpha="false" :show-swatches="false" />如何控制 popover？
用 v-model:open 绑定 open：
<SColorPicker v-model:open="open" v-model:model-value="color" />