单选框组

概述

一组可勾选的单选框按钮，同一时刻最多只有一个按钮处于选中态。以数据驱动分组与带 icon/description 内容的卡片变体提供，两者均基于 roving-focus 键盘导航。适用于从小型互斥集合中单选；允许多选时请用 SCheckboxGroup；选项集合过大无法一眼扫尽时，优先用 SSelect。

用法

特性

☑️ 单选模型——modelValue / defaultValue，受控与非受控双模式
⌨️ Roving-focus 键盘导航——方向键移动并选中、Enter/Space 选择、可选 loop 循环
🏷 可访问标签——RadioGroupLabel 将 for 关联到每个控件的 id
📋 原生表单代理——隐藏输入携带当前值，支持 name / required
🃏 卡片变体（SRadioGroupCard）——icon、label、description 内容
🎨 radioGroupVariants 提供 6 尺寸、8 颜色与 dot/outline 变体
📊 Aria 数据驱动聚合——RadioGroupCompact / RadioGroupCardCompact
♿ role="radiogroup" + role="radio"，aria-checked / data-state 双通道反射，axe 零违规

单选框组组件系列

SRadioGroup - 数据驱动单选框组，支持 dot/outline 变体
SRadioGroupCard - 卡片单选框组，含 icon、label 与 description

演示

基础

100%

Option 1

Option 2

Option 3

卡片

100%

Apple

This is an apple

Orange

This is an orange

Banana

This is a banana

Grape

This is a grape

API

Aria 层

RadioGroup<T>

18 属性1 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	应用于根元素的额外类名。
variant	RadioGroupVariant	—	该组件的视觉变体。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<RadioGroupUi>	—	该组件的按槽类重写。
items	T[]	—	由该组件渲染的项。
itemProps	RadioGroupItemProps	—	转发给 item 元素的属性。
controlProps	RadioGroupControlProps	—	转发给控件的属性。
indicatorProps	RadioGroupIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'] \| null	—	要选中的单选按钮项的控制值。可作为 `v-model` 进行绑定。
defaultValue	T['value']	—	初始渲染时应选中的单选按钮选项的值。当您无需控制单选按钮选项的状态时使用此选项。
disabled	boolean	—	当值为 `true` 时，禁止用户与单选按钮交互。
orientation	DataOrientation	—	组件的取向。
dir	Direction	—	如适用，请保留单选按钮组的阅读方向。
loop	boolean	—	当值为 `true` 时，键盘导航将在最后一项和第一项之间循环切换。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T \| null	当单选按钮组值发生变化时调用的事件处理程序

RadioGroupCard<T>

21 属性1 事件1 插槽

属性

属性名	类型	默认值	描述
class	ClassValue	—	应用于根元素的额外类名。
variant	RadioGroupVariant	—	该组件的视觉变体。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<RadioGroupCardUi>	—	该组件的按槽类重写。
contentProps	BaseProps	—	转发给内容元素的属性。
textContentProps	BaseProps	—	传递给文本内容元素的属性。
descriptionProps	BaseProps	—	已将属性转发至 description 元素。
items	T[]	—	由该组件渲染的项。
itemProps	RadioGroupItemProps	—	转发给 item 元素的属性。
controlProps	RadioGroupControlProps	—	转发给控件的属性。
indicatorProps	RadioGroupIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'] \| null	—	要选中的单选按钮项的控制值。可作为 `v-model` 进行绑定。
defaultValue	T['value']	—	初始渲染时应选中的单选按钮选项的值。当您无需控制单选按钮选项的状态时使用此选项。
disabled	boolean	—	当值为 `true` 时，禁止用户与单选按钮交互。
orientation	DataOrientation	—	组件的取向。
dir	Direction	—	如适用，请保留单选按钮组的阅读方向。
loop	boolean	—	当值为 `true` 时，键盘导航将在最后一项和第一项之间循环切换。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T \| null	当单选按钮组值发生变化时调用的事件处理程序

插槽

插槽名	参数	描述
description	{ item: T; }	用于在单选按钮卡片中渲染自定义描述内容的插槽。

RadioGroupCardCompact<T>

16 属性1 事件1 插槽

属性

属性名	类型	默认值	描述
contentProps	BaseProps	—	转发给内容元素的属性。
textContentProps	BaseProps	—	传递给文本内容元素的属性。
descriptionProps	BaseProps	—	已将属性转发至 description 元素。
items	T[]	—	由该组件渲染的项。
itemProps	RadioGroupItemProps	—	转发给 item 元素的属性。
controlProps	RadioGroupControlProps	—	转发给控件的属性。
indicatorProps	RadioGroupIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'] \| null	—	要选中的单选按钮项的控制值。可作为 `v-model` 进行绑定。
defaultValue	T['value']	—	初始渲染时应选中的单选按钮选项的值。当您无需控制单选按钮选项的状态时使用此选项。
disabled	boolean	—	当值为 `true` 时，禁止用户与单选按钮交互。
orientation	DataOrientation	—	组件的取向。
dir	Direction	—	如适用，请保留单选按钮组的阅读方向。
loop	boolean	—	当值为 `true` 时，键盘导航将在最后一项和第一项之间循环切换。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T \| null	当单选按钮组值发生变化时调用的事件处理程序

插槽

插槽名	参数	描述
description	{ item: T; }	用于在单选按钮卡片中渲染自定义描述内容的插槽。

RadioGroupCompact<T>

13 属性1 事件

属性

属性名	类型	默认值	描述
items	T[]	—	由该组件渲染的项。
itemProps	RadioGroupItemProps	—	转发给 item 元素的属性。
controlProps	RadioGroupControlProps	—	转发给控件的属性。
indicatorProps	RadioGroupIndicatorProps	—	转发给 indicator 元素的属性。
labelProps	LabelProps	—	传递给 label 元素的属性。
modelValue	T['value'] \| null	—	要选中的单选按钮项的控制值。可作为 `v-model` 进行绑定。
defaultValue	T['value']	—	初始渲染时应选中的单选按钮选项的值。当您无需控制单选按钮选项的状态时使用此选项。
disabled	boolean	—	当值为 `true` 时，禁止用户与单选按钮交互。
orientation	DataOrientation	—	组件的取向。
dir	Direction	—	如适用，请保留单选按钮组的阅读方向。
loop	boolean	—	当值为 `true` 时，键盘导航将在最后一项和第一项之间循环切换。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T \| null	当单选按钮组值发生变化时调用的事件处理程序

RadioGroupControl

5 属性

属性

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

RadioGroupIndicator

3 属性

属性

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

RadioGroupItem

4 属性1 事件

属性

属性名	类型	默认值	描述
value	DefinedWithBooleanValue	—	作为数据提交时与 `name` 关联的值。
disabled	boolean	—	当值为 `true` 时，禁止用户与单选按钮交互。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
select	RadioSelectEvent	当单选按钮被选中时调用的事件处理程序

RadioGroupLabel

RadioGroupRoot<T>

8 属性1 事件

属性

属性名	类型	默认值	描述
modelValue	T \| null	—	要选中的单选按钮项的控制值。可作为 `v-model` 进行绑定。
defaultValue	T	—	初始渲染时应选中的单选按钮选项的值。当您无需控制单选按钮选项的状态时使用此选项。
disabled	boolean	—	当值为 `true` 时，禁止用户与单选按钮交互。
orientation	DataOrientation	—	组件的取向。
dir	Direction	—	如适用，请保留单选按钮组的阅读方向。
loop	boolean	—	当值为 `true` 时，键盘导航将在最后一项和第一项之间循环切换。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	T \| null	当单选按钮组值发生变化时调用的事件处理程序

注意事项

架构与对标差异

VeanUI 以 Aria 链路构建单选框组：RadioGroupRoot（useControllableState + useRovingFocusGroup）→ RadioGroupItem（选中派生 + VisuallyHiddenInput 表单代理）→ RadioGroupControl（Button 基座 + role="radio" + aria-checked/data-state，聚焦派生选中）→ RadioGroupIndicator（usePresence 条件挂载）→ RadioGroupLabel（for ↔ 控件 id）。RadioGroupCompact / RadioGroupCardCompact 持有条目迭代与默认组合，UI 包装器只注入变体类。scv() 配方 radioGroupVariants / radioGroupCardVariants 声明 6 尺寸、8 颜色与 dot/outline 变体。

能力	VeanUI	Ant Design `Radio`	Element Plus `Radio`	Mantine `Radio`	Naive UI `Radio`	shadcn `RadioGroup`
Aria/styled 分离	✅	—	—	—	—	✅
单选互斥	✅	✅	✅	✅	✅	✅
Roving-focus 键盘导航	✅	✅	✅	✅	✅	✅
受控/非受控	✅	✅	✅	✅	✅	✅
卡片变体（icon/描述）	✅	—	—	—	—	—
`button` variant	➕	✅	✅	—	—	—
`Radio.Button` 组合子	➕	✅	—	—	—	—
表单代理 / `name` 提交	✅	✅	✅	✅	✅	✅
axe 零违规（组 + 卡片）	✅	—	—	—	—	—

注意事项

方向键选中经控件上的"聚焦派生 click"提交，与鼠标点击走同一条 radio.select / update:modelValue 链路。
根元素带 form 类且传入 name 时渲染表单代理；配合原生 <form> 或 SForm 集成即可提交值。
select 是可取消的自定义事件——调用 event.preventDefault() 即可否决本次值变更。
Enter 显式接入选中处理器（与 checkbox 族系一致）；Space 依赖原生 button 的点击行为。

常见问题

键盘导航如何工作？

分组使用 roving focus：组内一个 radio 可 tab 到，方向键移动焦点（并选中聚焦项），Enter/Space 选择。设置 loop 可首尾循环。

用受控还是非受控？

受控：传入 modelValue 并配合 v-model；非受控：传入 defaultValue 让分组内部自行维护状态。两者经 useControllableState 统一支持。

如何让选中值随表单提交？

为分组传入 name；在带 form 类的根内，隐藏输入会携带当前值参与原生表单提交。

`SRadioGroup` 与 `SCheckboxGroup` 有什么区别？

SRadioGroup 强制单选——选中一个会取消其他；SCheckboxGroup 允许多个勾选值。互斥选项用 radio，多选用 checkbox。

快速跳转

同分类组件

单选框组

概述

用法

特性

单选框组组件系列

演示

基础

卡片

API

Aria 层

RadioGroup<T>

属性

事件

RadioGroupCard<T>

属性

事件

插槽

RadioGroupCardCompact<T>

属性

事件

插槽

RadioGroupCompact<T>

属性

事件

RadioGroupControl

属性

RadioGroupIndicator

属性

RadioGroupItem

属性

事件

RadioGroupLabel

RadioGroupRoot<T>

属性

事件

注意事项

架构与对标差异

注意事项

常见问题

键盘导航如何工作？

用受控还是非受控？

如何让选中值随表单提交？

SRadioGroup 与 SCheckboxGroup 有什么区别？

更新日志

v0.20.0

重构

v0.0.2

新功能

新功能

新功能

新功能

修复

新功能

新功能

新功能

新功能

修复

`SRadioGroup` 与 `SCheckboxGroup` 有什么区别？