色块选择器

概述

通过预设色板快速选择颜色，适合主题面板和颜色推荐场景。SColorSwatchPicker 组合 Aria ColorSwatchPickerRoot/Item/ItemSwatch/ItemIndicator 基础组件（构建于 listbox）与 colorSwatchPickerVariants 样式配方（6 个槽、6 种尺寸 × 2 种形状）。

色块选择器适合紧凑、可点击的预设色板（主题面板、品牌色、推荐颜色）。

用法

特性

🧩 基于 Aria listbox — 构建于 listbox 基础组件，带 role="listbox"/option、roving focus 与选择
🎨 预设色板 — 传入 colors 数组；每项渲染一个带勾选指示器的 ColorSwatch
🔘 单选/多选 — multiple（经 listbox M 泛型）选择单个或多个值
✅ 指示器 — indicator 插槽（默认 lucide:check）标记当前选中色块
🔵 形状 — shape="square"（默认）或 "circle"
📐 6 种尺寸 — xs–2xl size；逐槽 ui 覆盖
🧩 自定义内容 — 无 colors 时的 default 插槽与 swatch/indicator 插槽提供完全控制

组件家族

SColorSwatchPicker（样式层）— 入口包装组件；colorSwatchPickerVariants 配方配合动态插槽转发
ColorSwatchPickerCompact（Aria）— 聚合组件；将 colors 迭代为带色块 + 指示器的条目
ColorSwatchPickerRoot（Aria）— listbox 根（modelValue、multiple）
ColorSwatchPickerItem（Aria）— 可选择的色块选项（role="option"）
ColorSwatchPickerItemSwatch（Aria）— 色块（ColorSwatchCompact 基座）
ColorSwatchPickerItemIndicator（Aria）— 选中勾选指示器

演示

基础

100%

#7c3aed

API

Aria 层

ColorSwatchPicker

19 属性5 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	应用于根元素的额外类名。
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<ColorSwatchPickerExtendedUi>	—	该组件的按槽类重写。
shape	ColorSwatchPickerShape	—	组件的结构。
colors	string[]	—	颜色。
itemProps	Omit<ColorSwatchPickerItemProps, 'value'>	—	转发给 item 元素的属性。
indicatorProps	ColorSwatchPickerItemIndicatorProps	—	转发给 indicator 元素的属性。
swatchProps	ColorSwatchPickerItemSwatchProps	—	传递给 swatch 元素的属性。
orientation	DataOrientation	—	列表框的方向。<br>主要是为了确保箭头导航方向与之对应（左右 vs. 上下）
dir	Direction	—	列表框的阅读方向（如适用）。<br> 若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
disabled	boolean	—	当值为 `true` 时，禁止用户与列表框进行交互
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示
modelValue	string \| string[]	—	所选项的受控值。当需要控制项的状态时使用此属性。可通过 `v-model` 进行绑定。
defaultValue	string \| string[]	—	所选项的默认值。当需要设置项的初始状态时，请使用此选项。
multiple	boolean	—	用于确定一次可选择“单个”还是“多个”项目。此属性将覆盖根据 `modelValue` 和 `defaultValue` 推断出的类型。
clearable	boolean	—	当 `multiple` 为 false 时，是否可以清除所选项目。
selectionBehavior	SelectionBehavior	'toggle'	集合中多选功能应如何工作。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	string \| string[]	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	当选中元素发生变化时的事件处理程序。
entryFocus	CustomEvent<any>	当容器获得焦点时触发的事件处理程序。可被阻止。
leave	Event	当鼠标离开容器时调用的事件处理程序
select	SelectEvent<string>	当选中某项时触发的事件处理程序。<br> 可以通过调用 `event.preventDefault` 来阻止该事件。

ColorSwatchPickerCompact<M>

15 属性5 事件3 插槽

属性

属性名	类型	默认值	描述
colors	string[]	—	颜色。
itemProps	Omit<ColorSwatchPickerItemProps, 'value'>	—	转发给 item 元素的属性。
indicatorProps	ColorSwatchPickerItemIndicatorProps	—	转发给 indicator 元素的属性。
swatchProps	ColorSwatchPickerItemSwatchProps	—	传递给 swatch 元素的属性。
orientation	DataOrientation	—	列表框的方向。<br>主要是为了确保箭头导航方向与之对应（左右 vs. 上下）
dir	Direction	—	列表框的阅读方向（如适用）。<br> 若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
disabled	boolean	—	当值为 `true` 时，禁止用户与列表框进行交互
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示
modelValue	(M extends true ? string[] : string)	—	所选项的受控值。当需要控制项的状态时使用此属性。可通过 `v-model` 进行绑定。
defaultValue	(M extends true ? string[] : string)	—	所选项的默认值。当需要设置项的初始状态时，请使用此选项。
multiple	M	—	用于确定一次可选择“单个”还是“多个”项目。此属性将覆盖根据 `modelValue` 和 `defaultValue` 推断出的类型。
clearable	boolean	—	当 `multiple` 为 false 时，是否可以清除所选项目。
selectionBehavior	SelectionBehavior	'toggle'	集合中多选功能应如何工作。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	M extends true ? string[] : string	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	当选中元素发生变化时的事件处理程序。
entryFocus	CustomEvent<any>	当容器获得焦点时触发的事件处理程序。可被阻止。
leave	Event	当鼠标离开容器时调用的事件处理程序
select	SelectEvent<string>	当选中某项时触发的事件处理程序。<br> 可以通过调用 `event.preventDefault` 来阻止该事件。

插槽

插槽名	参数	描述
default	ColorSwatchPickerCompactSlotProps<M>	当未提供颜色时渲染的自定义内容。
swatch	ColorSwatchPickerCompactColorSlotProps	每个色板内渲染的自定义内容。
indicator	ColorSwatchPickerCompactColorSlotProps	每个指示器内部渲染的自定义内容。

ColorSwatchPickerCompactColor

ColorSwatchPickerItem

4 属性1 事件

属性

属性名	类型	默认值	描述
value	string	—	作为数据提交时与 `name` 关联的值。
disabled	boolean	—	当值为 `true` 时，禁止用户与该项进行交互。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
select	SelectEvent<string>	当选中某项时触发的事件处理程序。<br> 可以通过调用 `event.preventDefault` 来阻止该事件。

ColorSwatchPickerItemIndicator

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ColorSwatchPickerItemSwatch

6 属性

属性

属性名	类型	默认值	描述
checkerProps	ColorSwatchCheckerProps	—	ColorSwatch 组件中 checker 元素的 props。
fillProps	ColorSwatchFillProps	—	ColorSwatch 组件中 fill 属性的属性值。
color	import("@soybeanjs/colord").AnyColor	—	组件的主题颜色。
label	string	—	翻译组件渲染的标签文本。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ColorSwatchPickerRoot<M>

11 属性4 事件

属性

属性名	类型	默认值	描述
orientation	DataOrientation	—	列表框的方向。<br>主要是为了确保箭头导航方向与之对应（左右 vs. 上下）
dir	Direction	—	列表框的阅读方向（如适用）。<br> 若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
disabled	boolean	—	当值为 `true` 时，禁止用户与列表框进行交互
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示
modelValue	(M extends true ? string[] : string)	—	所选项的受控值。当需要控制项的状态时使用此属性。可通过 `v-model` 进行绑定。
defaultValue	(M extends true ? string[] : string)	—	所选项的默认值。当需要设置项的初始状态时，请使用此选项。
multiple	M	—	用于确定一次可选择“单个”还是“多个”项目。此属性将覆盖根据 `modelValue` 和 `defaultValue` 推断出的类型。
clearable	boolean	—	当 `multiple` 为 false 时，是否可以清除所选项目。
selectionBehavior	SelectionBehavior	'toggle'	集合中多选功能应如何工作。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	M extends true ? string[] : string	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	当选中元素发生变化时的事件处理程序。
entryFocus	CustomEvent<any>	当容器获得焦点时触发的事件处理程序。可被阻止。
leave	Event	当鼠标离开容器时调用的事件处理程序

注意事项

架构与对标差异

ColorSwatchPickerCompact 负责色板迭代（条目 + 色块 + 指示器），所有基础组件保持零样式，仅由 UI 包装组件注入 colorSwatchPickerVariants 类。这与 radix-ui-color/shadcn-ui 的 headless 分离一致，构建于共享 listbox 基础组件之上。Ant Design、Element Plus、Mantine、Naive UI 在单个颜色选择器中提供预设行；VeanUI 暴露独立的基于 listbox 的色块选择器，带单选/多选、勾选指示器、形状/尺寸控制与完整插槽覆盖。

能力	VeanUI	shadcn/ui	Ant Design	Element Plus	Mantine	Naive UI
基于 Aria listbox	✅	✅	—	—	—	—
单选/多选	✅	✅	✅	✅	✅	—
勾选指示器	✅	✅	—	—	—	—
Roving focus	✅	✅	—	—	—	—
形状（方/圆）	✅	✅	✅	✅	✅	—
尺寸（6）	✅	—	—	—	—	—

— = 不支持或采用不同交互模型。

运行时注意

colors 为颜色字符串数组；每项渲染一个 ColorSwatch 选项，当前值带勾选指示器。
选择发出 update:modelValue（单选：字符串；multiple：数组）与 select。
提供 indicator/swatch 插槽自定义勾选标记与色块内容；colors 为空时用 default 插槽渲染完全自定义内容。
shape 在方形（rounded-md）与圆形（rounded-full）间切换。
构建于 listbox 基础组件，键盘/roving-focus 行为遵循 listbox 契约。

Roadmap

不适用——color-swatch-picker 对当前对标集已功能完备。

FAQ

如何构建色块选择器？

传入 colors 并绑定 model-value：

<SColorSwatchPicker v-model:model-value="color" :colors="['#7c3aed', '#06b6d4', '#10b981']" />

如何允许多选？

使用 multiple（值变为数组）：

<SColorSwatchPicker v-model:model-value="colors" multiple :colors="palette" />

如何设为圆形色块？

设置 shape="circle"：

<SColorSwatchPicker v-model:model-value="color" :colors="palette" shape="circle" />

如何自定义指示器？

使用 indicator 插槽：

<SColorSwatchPicker v-model:model-value="color" :colors="palette">
  <template #indicator>✓</template>
</SColorSwatchPicker>

快速跳转

同分类组件