组件详情入口

表单

@vean/ui

SCheckbox

Checkbox

Checkbox 属于表单分类。建议先看演示与用法，再对照 API 表格完成接入和样式调整。

先用快捷跳转面板找到概述、用法、演示和 API，再往下细读完整文档内容。

快速跳转

概述用法演示 API 更新日志

同分类组件

如果你在同一类交互里做组合，这些组件通常会一起出现。

Autocomplete Calendar ColorArea ColorField ColorPicker ColorSlider

复选框

概述

用于在选中/未选中之间切换的控件，并支持半选（indeterminate）状态表达部分选中。以独立控件、roving-focus 分组与数据驱动卡片变体等多种形态提供。适用于独立开关、多选列表以及带半选联动的"全选"场景；从集合中单选请用 SRadioGroup。

用法

特性

☑️ 三态模型——CheckedState 为 boolean | 'indeterminate'，经 aria-checked（mixed）与 data-state 双通道反射
🗂 分组支持 roving-focus 键盘导航（useRovingFocusGroup，方向键）
🏷 可访问标签——SCheckboxLabel 将 for 关联到控件的 id
📋 原生表单代理——渲染隐藏输入，携带 name / value（默认 'on'）/ checked 参与表单提交
🃏 卡片变体（SCheckboxCard / SCheckboxCardGroup）——icon、label、description 内容
🎨 checkboxVariants 提供 6 尺寸、8 颜色、2 形状与横/纵排列
📊 数据驱动 Compact 聚合——CheckboxGroupCompact / CheckboxCardGroupCompact 持有迭代与默认组合
♿ role="checkbox" + 完整 aria 支持，四种形态 axe 零违规

复选框组件系列

SCheckbox - 基础复选框，含 label、control 与 indicator
SCheckboxGroup - 纵向/横向分组，支持 roving-focus 导航与表单代理
SCheckboxCard - 卡片复选框，含 icon、label 与 description
SCheckboxCardGroup - 数据驱动的卡片复选框分组

演示

基础

100%

Checkbox

图标

100%

Rounded

分组

100%

Check All

Apple

Orange

Banana

Grape

卡片

100%

Label

this is a description

卡片组

100%

Check All

Apple

Orange

Banana

Grape

API

Aria 层

Checkbox

16 属性1 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	根元素的类
ui	Partial<CheckboxUi>	—	该组件的按槽类重写。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
shape	CheckboxShape	—	组件的结构。
label	string	—	翻译组件渲染的标签文本。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
id	string	—	同上。
modelValue	CheckedState \| null	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	CheckedState	—	复选框在初始渲染时的值。当不需要控制其值时使用。
value	DefinedValue	on	作为数据提交时与 `name` 关联的值。
disabled	boolean	false	当值为 `true` 时，禁止用户与该复选框进行交互
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	CheckedState \| null	当复选框的值发生变化时调用的事件处理程序。

CheckboxCard

18 属性1 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	根元素的类
ui	Partial<CheckboxCardUi>	—	该组件的按槽类重写。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
shape	CheckboxShape	—	组件的结构。
icon	string	—	由该组件渲染的图标。
description	string	—	由组件渲染的描述文本。
label	string	—	翻译组件渲染的标签文本。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
id	string	—	同上。
modelValue	CheckedState \| null	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	CheckedState	—	复选框在初始渲染时的值。当不需要控制其值时使用。
value	DefinedValue	on	作为数据提交时与 `name` 关联的值。
disabled	boolean	false	当值为 `true` 时，禁止用户与该复选框进行交互
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	CheckedState \| null	当复选框的值发生变化时调用的事件处理程序。

CheckboxCardCompact

13 属性1 事件

属性

属性名	类型	默认值	描述
icon	IconValue	—	由该组件渲染的图标。
description	string	—	由组件渲染的描述文本。
label	string	—	翻译组件渲染的标签文本。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
id	string	—	同上。
modelValue	CheckedState \| null	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	CheckedState	—	复选框在初始渲染时的值。当不需要控制其值时使用。
value	DefinedValue	on	作为数据提交时与 `name` 关联的值。
disabled	boolean	false	当值为 `true` 时，禁止用户与该复选框进行交互
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	CheckedState \| null	当复选框的值发生变化时调用的事件处理程序。

CheckboxCardGroup<T>

19 属性1 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	组根元素的类
ui	Partial<CheckboxCardUi>	—	该组件的按槽类重写。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
shape	CheckboxShape	—	组件的结构。
items	T[]	—	由该组件渲染的项。
rootProps	CheckboxRootProps	—	转发至根元素的属性。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'][]	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	T['value'][]	—	复选框在初始渲染时的值。当不需要控制其值时使用。
rovingFocus	boolean	true	当值为 `false` 时，将禁用使用方向键浏览项目的功能。
disabled	boolean	false	当值为 `true` 时，禁止用户与复选框进行交互
dir	Direction	—	项目之间的导航方向。
loop	boolean	false	键盘导航是否应循环往复
orientation	DataOrientation	—	该组的取向。主要是为了确保箭头导航能据此正确进行（左右与上下）。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T[]	当复选框组的值发生变化时调用的事件处理程序。

CheckboxCardGroupCompact<T>

14 属性1 事件

属性

属性名	类型	默认值	描述
items	T[]	—	由该组件渲染的项。
rootProps	CheckboxRootProps	—	转发至根元素的属性。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'][]	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	T['value'][]	—	复选框在初始渲染时的值。当不需要控制其值时使用。
rovingFocus	boolean	true	当值为 `false` 时，将禁用使用方向键浏览项目的功能。
disabled	boolean	false	当值为 `true` 时，禁止用户与复选框进行交互
dir	Direction	—	项目之间的导航方向。
loop	boolean	false	键盘导航是否应循环往复
orientation	DataOrientation	—	该组的取向。主要是为了确保箭头导航能据此正确进行（左右与上下）。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T[]	当复选框组的值发生变化时调用的事件处理程序。

CheckboxCompact

11 属性1 事件

属性

属性名	类型	默认值	描述
label	string	—	翻译组件渲染的标签文本。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
id	string	—	同上。
modelValue	CheckedState \| null	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	CheckedState	—	复选框在初始渲染时的值。当不需要控制其值时使用。
value	DefinedValue	on	作为数据提交时与 `name` 关联的值。
disabled	boolean	false	当值为 `true` 时，禁止用户与该复选框进行交互
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	CheckedState \| null	当复选框的值发生变化时调用的事件处理程序。

CheckboxControl

5 属性

属性

属性名	类型	默认值	描述
id	string	—	元素的 ID
type	ButtonType	'button'	按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。
disabled	boolean	—	该组件是否已禁用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

CheckboxGroup<T>

19 属性1 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	组根元素的类
ui	Partial<CheckboxUi>	—	该组件的按槽类重写。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
shape	CheckboxShape	—	组件的结构。
items	T[]	—	由该组件渲染的项。
rootProps	CheckboxRootProps	—	转发至根元素的属性。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'][]	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	T['value'][]	—	复选框在初始渲染时的值。当不需要控制其值时使用。
rovingFocus	boolean	true	当值为 `false` 时，将禁用使用方向键浏览项目的功能。
disabled	boolean	false	当值为 `true` 时，禁止用户与复选框进行交互
dir	Direction	—	项目之间的导航方向。
loop	boolean	false	键盘导航是否应循环往复
orientation	DataOrientation	—	该组的取向。主要是为了确保箭头导航能据此正确进行（左右与上下）。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T[]	当复选框组的值发生变化时调用的事件处理程序。

CheckboxGroupCompact<T>

14 属性1 事件

属性

属性名	类型	默认值	描述
items	T[]	—	由该组件渲染的项。
rootProps	CheckboxRootProps	—	转发至根元素的属性。
controlProps	CheckboxControlProps	—	转发给控件的属性。
indicatorProps	CheckboxIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'][]	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	T['value'][]	—	复选框在初始渲染时的值。当不需要控制其值时使用。
rovingFocus	boolean	true	当值为 `false` 时，将禁用使用方向键浏览项目的功能。
disabled	boolean	false	当值为 `true` 时，禁止用户与复选框进行交互
dir	Direction	—	项目之间的导航方向。
loop	boolean	false	键盘导航是否应循环往复
orientation	DataOrientation	—	该组的取向。主要是为了确保箭头导航能据此正确进行（左右与上下）。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T[]	当复选框组的值发生变化时调用的事件处理程序。

CheckboxGroupRoot<T>

9 属性1 事件

属性

属性名	类型	默认值	描述
modelValue	T[]	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	T[]	—	复选框在初始渲染时的值。当不需要控制其值时使用。
rovingFocus	boolean	true	当值为 `false` 时，将禁用使用方向键浏览项目的功能。
disabled	boolean	false	当值为 `true` 时，禁止用户与复选框进行交互
dir	Direction	—	项目之间的导航方向。
loop	boolean	false	键盘导航是否应循环往复
orientation	DataOrientation	—	该组的取向。主要是为了确保箭头导航能据此正确进行（左右与上下）。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T[]	当复选框组的值发生变化时调用的事件处理程序。

CheckboxIndicator

3 属性

属性

属性名	类型	默认值	描述
forceMount	boolean	—	用于在需要更多控制时强制挂载。在使用 Vue 动画库控制动画时非常有用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

CheckboxLabel

CheckboxRoot

7 属性1 事件

属性

属性名	类型	默认值	描述
id	string	—	同上。
modelValue	CheckedState \| null	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	CheckedState	—	复选框在初始渲染时的值。当不需要控制其值时使用。
value	DefinedValue	on	作为数据提交时与 `name` 关联的值。
disabled	boolean	false	当值为 `true` 时，禁止用户与该复选框进行交互
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	CheckedState \| null	当复选框的值发生变化时调用的事件处理程序。

注意事项

架构与对标差异

VeanUI 以单一事实源的三态状态机构建复选框：CheckboxRoot（useControllableState + CheckedState）派生 ariaChecked（indeterminate → mixed）与 dataState（checked / indeterminate / unchecked），CheckboxControl 在 role="checkbox" 上双通道反射，CheckboxIndicator 经 usePresence 条件挂载。组值变更由 CheckboxGroupRoot 发出——它包装 useRovingFocusGroup 提供方向键导航，并渲染 VisuallyHiddenInput 表单代理。scv() 配方 checkboxVariants / checkboxCardVariants 声明 6 尺寸、8 颜色、2 形状；四层 Compact 持有迭代与默认组合，UI 包装器只注入变体类。

能力	VeanUI	Ant Design `Checkbox`	Element Plus `Checkbox`	Mantine `Checkbox`	shadcn/ui `Checkbox`
Aria/styled 分离	✅	—	—	—	✅
三态（indeterminate）	✅	✅	✅	✅	✅
独立 `indeterminate` prop	➕	✅	✅	✅	—
表单 value 映射	✅	✅	✅	✅	✅
卡片变体（icon/描述）	✅	—	—	—	—
组 roving-focus 键盘导航	✅	✅	✅	✅	—
`button` variant	➕	✅	✅	—	—
全选/半选联动辅助	➕	✅	—	—	—

注意事项

半选状态通过 modelValue="indeterminate" 驱动；独立 indeterminate prop 属于路线图增强项，尚未实现。
组根 disabled 会禁用全部条目；启用组内的单条目 disabled 同样生效。
传入 name 后表单代理生效——配合原生 <form> 或 SForm 集成即可提交值。
indicator 使用 pointer-events: none，点击始终落在控件自身。

常见问题

如何展示半选状态？

传入 modelValue="indeterminate"（或 defaultValue）；控件会反射 aria-checked="mixed" 与 data-state="indeterminate"。

如何构建"全选"列表？

用主 SCheckbox 配合 modelValue="indeterminate" 与一个 SCheckboxGroup；把组的 update:modelValue 回映到主复选框即可驱动半选联动。

如何让复选框值随表单提交？

为复选框或分组传入 name；组件会渲染隐藏输入，使原生表单提交携带 value（默认 'on'）或勾选值数组。

`SCheckboxCard` 与 `SCheckbox` 有什么区别？

SCheckboxCard 渲染带边框的卡片，含 icon / label / description 内容槽与 data-[state=checked] 边框高亮；SCheckbox 是裸控件。

更新日志

版本记录按发布版本分组，便于快速查看这个组件在不同版本里的实际变更。

v0.19.0

2026-05-11

对比版本

优化

更新组件结构，提高可读性

范围: checkbox作者: soybeanfe查看提交3a6a2

优化

在 CheckboxCardGroupCompact 中设置默认 rovingFocus 属性

范围: checkbox作者: soybeanfe查看提交5930e

优化

在复选框卡组和复选框组中设置默认漫游焦点道具

范围: checkbox作者: soybeanfe查看提交d659e

v0.15.0

2026-04-26

对比版本

修复

更新 forwardedProps，省略 "class "而非 "label

范围: checkbox作者: soybeanfe查看提交0d537

文档

修正 emit 参数语法以保持一致

范围: checkbox作者: soybeanjs, Copilot查看提交1d2d7

修复

更新 forwardedProps，省略 "class "而非 "label

范围: checkbox作者: soybeanfe查看提交0d537

v0.9.0

2026-03-01

对比版本

修复

根据槽或标签的存在有条件地渲染 CheckboxLabel；更新根变体样式

范围: checkbox作者: soybeanjs查看提交78f2b

v0.0.20

2026-01-21

对比版本

文档

修复标记符格式

范围: checkbox作者: soybeanjs查看提交762c9

v0.0.19

2026-01-19

对比版本

新功能

支持键盘输入以切换选中状态

范围: checkbox作者: soybeanjs查看提交75ddd

v0.0.2

2025-11-18

对比版本

新功能

新增支持多种状态和分组功能的复选框组件

范围: checkbox作者: soybeanjs查看提交3dfcb

新功能

重构复选框组件，以利用新的主题上下文，并通过 SCheckbox 和 SCheckboxGroup 改进结构

范围: checkbox作者: soybeanjs查看提交81075

新功能

新增 CheckboxCard 和 CheckboxCardGroup 组件，通过卡片式布局增强复选框功能，并优化了 UI 集成

范围: checkbox作者: soybeanjs查看提交1b764

新功能

添加颜色和尺寸示例，增强复选框卡片和组组件的颜色支持，并改进复选框标签

范围: checkbox作者: soybeanjs查看提交ac32d

新功能

引入形状和图标示例，为复选框组件增强形状支持，并更新卡片组的样式

范围: checkbox作者: soybeanjs查看提交bbd07

修复

更新点击处理程序，在访问 modelValue 之前先检查 groupContext 是否存在

范围: checkbox作者: soybeanjs查看提交78fda

重构

从共享复选框文件中移除未使用的常量和 CSS 变量

范围: checkbox作者: soybeanjs查看提交494f4

重构

整合 CheckedState 的类型定义，并更新相关函数以提高清晰度

范围: checkbox作者: soybeanjs查看提交fac63

重构

简化复选框组件的结构，并通过改进状态管理来增强分组功能

范围: checkbox作者: soybeanjs查看提交4d4ec

重构

通过引入 getAriaLabel 函数并更新元素引用，增强无障碍功能和状态管理

范围: checkbox作者: soybeanjs查看提交472ba

重构

通过确保 modelValue 仅使用非空值进行更新，从而提高类型安全性

范围: checkbox作者: soybeanjs查看提交1c300

重构

更新复选框的上下文和样式，改用 data-state 属性以改进状态管理

范围: checkbox作者: soybeanjs查看提交ca1b5

重构

将 `isIndeterminate` 函数移至共享工具类，并清理导入语句

范围: checkbox作者: soybeanjs查看提交61449

新功能

新增支持多种状态和分组功能的复选框组件

范围: checkbox作者: soybeanjs查看提交3dfcb

新功能

重构复选框组件，以利用新的主题上下文，并通过 SCheckbox 和 SCheckboxGroup 改进结构

范围: checkbox作者: soybeanjs查看提交81075

新功能

新增 CheckboxCard 和 CheckboxCardGroup 组件，通过卡片式布局增强复选框功能，并优化了 UI 集成

范围: checkbox作者: soybeanjs查看提交1b764

新功能

添加颜色和尺寸示例，增强复选框卡片和组组件的颜色支持，并改进复选框标签

范围: checkbox作者: soybeanjs查看提交ac32d

新功能

引入形状和图标示例，为复选框组件增强形状支持，并更新卡片组的样式

范围: checkbox作者: soybeanjs查看提交bbd07

修复

更新点击处理程序，在访问 modelValue 之前先检查 groupContext 是否存在

范围: checkbox作者: soybeanjs查看提交78fda

重构

从共享复选框文件中移除未使用的常量和 CSS 变量

范围: checkbox作者: soybeanjs查看提交494f4

重构

整合 CheckedState 的类型定义，并更新相关函数以提高清晰度

范围: checkbox作者: soybeanjs查看提交fac63

重构

简化复选框组件的结构，并通过改进状态管理来增强分组功能

范围: checkbox作者: soybeanjs查看提交4d4ec

重构

通过引入 getAriaLabel 函数并更新元素引用，增强无障碍功能和状态管理

范围: checkbox作者: soybeanjs查看提交472ba

重构

通过确保 modelValue 仅使用非空值进行更新，从而提高类型安全性

范围: checkbox作者: soybeanjs查看提交1c300

重构

更新复选框的上下文和样式，改用 data-state 属性以改进状态管理

范围: checkbox作者: soybeanjs查看提交ca1b5

重构

将 `isIndeterminate` 函数移至共享工具类，并清理导入语句

范围: checkbox作者: soybeanjs查看提交61449

快速跳转

同分类组件

复选框

概述

用法

特性

复选框组件系列

演示

基础

图标

分组

卡片

卡片组

API

Aria 层

Checkbox

属性

事件

CheckboxCard

属性

事件

CheckboxCardCompact

属性

事件

CheckboxCardGroup<T>

属性

事件

CheckboxCardGroupCompact<T>

属性

事件

CheckboxCompact

属性

事件

CheckboxControl

属性

CheckboxGroup<T>

属性

事件

CheckboxGroupCompact<T>

属性

事件

CheckboxGroupRoot<T>

属性

事件

CheckboxIndicator

属性

CheckboxLabel

CheckboxRoot

属性

事件

注意事项

架构与对标差异

注意事项

常见问题

如何展示半选状态？

如何构建"全选"列表？

如何让复选框值随表单提交？

SCheckboxCard 与 SCheckbox 有什么区别？

更新日志

v0.19.0

优化

优化

优化

v0.15.0

修复

文档

修复

v0.9.0

修复

v0.0.20

文档

v0.0.19

新功能

v0.0.2

新功能

新功能

新功能

新功能

新功能

修复

`SCheckboxCard` 与 `SCheckbox` 有什么区别？