Checkbox · Radio · Switch 选择器套装

一套清晰、友好的手绘风选择器，覆盖多选、单选与即时开关场景。三个组件都保留原生键盘语义，同时提供可跨越 Shadow DOM 的状态事件。

选择提示多项并存使用 Checkbox，互斥选项使用 Radio，立即生效的二元设置使用 Switch。

类型

Checkbox 多选框

indeterminate 表示“部分选择”。用户点击半选项后，组件会退出半选状态并进入普通选中或未选中状态。

基础多选框

选项 A

选项 B

半选多选框

部分选择

卡片多选

标准功能适合日常使用

扩展功能包含更多能力

html

<super-checkbox>选项 A</super-checkbox>
<super-checkbox checked>选项 B</super-checkbox>
<super-checkbox indeterminate>部分选择</super-checkbox>

<super-checkbox variant="card" checked>
  <feature-icon slot="icon"></feature-icon>
  扩展功能
  <span slot="description">包含更多能力</span>
</super-checkbox>

variant="card" 提供完整卡片点击区域；icon 与 description Slot 用于补充图形和次级说明。基础多选仍使用默认的 default 变体。

Radio 单选框

同一根节点下拥有相同 name 的 super-radio 会保持互斥；使用方向键可以在启用的同组项目间循环选择。

基础单选框

选项 A

选项 B

按钮单选

选项 A

选项 B

卡片单选

标准版基础功能

高级版更多功能

html

<fieldset>
  <legend>选择方案</legend>
  <super-radio name="plan" value="standard" checked>标准版</super-radio>
  <super-radio name="plan" value="pro">高级版</super-radio>
</fieldset>

<super-radio variant="button" name="view" value="list">列表</super-radio>
<super-radio variant="button" name="view" value="card" checked>卡片</super-radio>

button 变体提供胶囊式选项，card 变体提供更大的内容区域；二者都保留内部原生 Radio 的键盘与可访问语义。

Switch 开关

默认 Slot 提供固定说明；checked-label / unchecked-label 和 checked-icon / unchecked-icon 可以随状态切换内容，不需要引入图标库。

基础开关

带文字开关

关闭开启

图标开关

☾☀ 显示模式跟随当前阅读偏好

html

<super-switch aria-label="深色模式">
  <moon-icon slot="unchecked-icon"></moon-icon>
  <sun-icon slot="checked-icon"></sun-icon>
  深色模式
  <span slot="description">夜间阅读更加舒适</span>
</super-switch>

<super-switch aria-label="消息提醒">
  <span slot="unchecked-label">关闭</span>
  <span slot="checked-label">开启</span>
</super-switch>

尺寸

大、中、小三档尺寸会同步调整指示器、轨道、间距与文字。组内建议保持同一尺寸。

大

多选项

单选项

中

多选项

单选项

小

多选项

单选项

html

<super-checkbox size="large">大号</super-checkbox>
<super-radio size="medium" name="size">中号</super-radio>
<super-switch size="small" aria-label="小号开关"></super-switch>

状态

悬停与聚焦列使用固定演示样式；普通组件可以直接交互体验真实状态。

默认悬停选中禁用

Checkbox

未选择

已选择

未选择

Radio

未选择

已选择

未选择

Switch

关闭

开启

关闭

Checkbox 半选

部分选择

全部选择

部分选择

校验与提示

validation 表达结果语义，helper-text 提供说明。错误状态会给内部控件添加 aria-invalid="true"，错误提示使用 role="alert"；其他提示使用礼貌播报。

多选成功

已同意协议

多选警告

接收活动通知

单选错误

支付宝

开关帮助

自动同步

html

<super-checkbox
  checked
  validation="success"
  helper-text="可以继续提交"
>已同意协议</super-checkbox>

<super-radio
  name="payment"
  validation="error"
  helper-text="请选择支付方式"
>支付宝</super-radio>

常用组合与布局

选择器不内置 Group 或卡片容器。使用原生 fieldset / legend 提供分组语义，再用业务布局决定纵向、横向、卡片或列表形态。

消息渠道

邮件

短信

站内信

默认付款方式

微信

支付宝

银行卡

设置开关组

消息提醒

深色模式

自动保存

横向排列

选项 A

选项 B

选项 C

♧ 消息提醒接收系统消息推送

☾ 深色模式夜间阅读更加舒适

☁ 自动备份自动上传并保存数据

html

<fieldset>
  <legend>默认付款方式</legend>
  <super-radio name="payment" value="wechat">微信</super-radio>
  <super-radio name="payment" value="alipay" checked>支付宝</super-radio>
</fieldset>

状态同步

三个组件分别派发独立的跨框架事件，事件都支持冒泡并穿过 Shadow DOM。不要只读取初始 attribute；用户操作后应读取事件 detail 或组件 property。

document.addEventListener("super-checkbox-change", (event) => {
  console.log(
    event.detail.name,
    event.detail.value,
    event.detail.checked,
    event.detail.indeterminate,
  );
});

document.addEventListener("super-radio-change", (event) => {
  console.log(event.detail.name, event.detail.value, event.detail.checked);
});

document.addEventListener("super-switch-change", (event) => {
  console.log(event.detail.name, event.detail.value, event.detail.checked);
});

无障碍

为一组相关选项使用原生 fieldset 与 legend，不要只依赖视觉边框表达分组。
Radio 组必须位于同一根节点与同一个最近的 form 中，并使用相同且非空的 name。组内仅当前选中项（没有选中项时为首个启用项）进入 Tab 顺序；聚焦后可使用上、下、左、右方向键循环选择启用项。
有可见文字时，默认 Slot 会参与内部原生控件的可访问名称；纯图标或无文字 Switch 必须提供 aria-label。
disabled 会让内部原生控件不可操作且不可聚焦。不要仅用降低透明度模拟禁用。
indeterminate 是独立视觉状态，并不等于 checked。业务中的“全选”逻辑仍需由消费者根据子项状态计算。

API

Checkbox Attributes / Properties

名称	类型	默认值	说明
`checked`	`boolean`	`false`	当前是否选中，并反射到 attribute
`indeterminate`	`boolean`	`false`	是否处于部分选择状态，并反射到 attribute
`disabled`	`boolean`	`false`	禁止操作并移出 Tab 顺序
`required`	`boolean`	`false`	转发给内部原生 Checkbox 的必选语义
`variant`	`default \| card`	`default`	基础或卡片布局
`size`	`large \| medium \| small`	`medium`	组件尺寸
`validation`	`none \| success \| warning \| error \| info`	`none`	校验视觉与辅助语义
`name`	`string`	空字符串	转发给内部控件，并包含在事件详情中
`value`	`string`	`on`	事件中返回的业务值
`helper-text`	`string`	空字符串	控件下方的帮助或错误信息
`aria-label`	`string`	空字符串	转发给内部 Checkbox 的可访问名称

Radio Attributes / Properties

名称	类型	默认值	说明
`checked`	`boolean`	`false`	当前是否选中，并反射到 attribute
`disabled`	`boolean`	`false`	禁止操作并移出 Tab 顺序
`required`	`boolean`	`false`	转发给内部原生 Radio 的必选语义
`variant`	`default \| button \| card`	`default`	基础、胶囊按钮或卡片布局
`size`	`large \| medium \| small`	`medium`	组件尺寸
`validation`	`none \| success \| warning \| error \| info`	`none`	校验视觉与辅助语义
`value`	`string`	`on`	事件中返回的业务值
`name`	`string`	空字符串	同根节点、同最近表单的同名组件构成互斥组
`helper-text`	`string`	空字符串	控件下方的帮助或错误信息
`aria-label`	`string`	空字符串	转发给内部 Radio 的可访问名称

Switch Attributes / Properties

名称	类型	默认值	说明
`checked`	`boolean`	`false`	当前是否开启，并反射到 attribute
`disabled`	`boolean`	`false`	禁止操作并移出 Tab 顺序
`required`	`boolean`	`false`	转发给内部原生 Checkbox 的必选语义
`size`	`large \| medium \| small`	`medium`	组件尺寸
`validation`	`none \| success \| warning \| error \| info`	`none`	校验视觉与辅助语义
`name`	`string`	空字符串	转发给内部控件，并包含在事件详情中
`value`	`string`	`on`	开关事件中返回的业务值
`helper-text`	`string`	空字符串	控件下方的帮助或错误信息
`aria-label`	`string`	空字符串	转发给内部 `role="switch"` 控件的可访问名称

Events

组件	名称	`detail`	说明
Checkbox	`super-checkbox-change`	`{ checked, indeterminate, name, value, originalEvent }`	选中或半选状态因用户操作发生变化
Radio	`super-radio-change`	`{ checked, value, name, originalEvent }`	用户选择一个未选中的单选项
Switch	`super-switch-change`	`{ checked, name, value, originalEvent }`	开关状态因用户操作发生变化

所有事件均设置 bubbles: true 与 composed: true。

Methods

三个组件提供相同的宿主方法：

名称	说明
`click()`	触发内部原生控件；禁用时无操作
`focus(options?)`	聚焦内部原生控件
`blur()`	移除内部原生控件焦点

Slots

组件	名称	说明
Checkbox	默认 Slot	选项文字或消费者内容
Checkbox	`icon`	卡片或选项中的装饰图标
Checkbox	`description`	与控件关联的次级说明
Radio	默认 Slot	选项文字或消费者内容
Radio	`icon`	卡片或选项中的装饰图标
Radio	`description`	与控件关联的次级说明
Switch	默认 Slot	固定说明文字
Switch	`description`	与控件关联的次级说明
Switch	`unchecked-label`	关闭状态显示的文字
Switch	`checked-label`	开启状态显示的文字
Switch	`unchecked-icon`	关闭状态显示在滑块内的图标
Switch	`checked-icon`	开启状态显示在滑块内的图标

组件不绑定图标库，图标 Slot 可以接收 SVG、图标组件或简单文本符号。

CSS Parts

组件	Part	说明
Checkbox	`control` / `input`	可点击标签容器 / 内部原生 Checkbox
Checkbox	`indicator` / `mark`	方形指示器 / 对勾或半选标记
Checkbox	`icon` / `content` / `label` / `description` / `helper`	图标、内容、主文字、次级说明与辅助信息
Radio	`control` / `input`	可点击标签容器 / 内部原生 Radio
Radio	`indicator` / `dot`	圆形指示器 / 选中圆点
Radio	`icon` / `content` / `label` / `description` / `helper`	图标、内容、主文字、次级说明与辅助信息
Switch	`control` / `input`	可点击标签容器 / 内部原生 Checkbox
Switch	`track` / `thumb`	轨道 / 滑块
Switch	`unchecked-icon` / `checked-icon`	两种状态的滑块图标容器
Switch	`content` / `label` / `unchecked-label` / `checked-label`	内容、固定说明与两种状态文字容器
Switch	`description` / `helper`	次级说明 / 校验或帮助信息

CSS Custom Properties

常用视觉 token 如下；其余尺寸 token 也可以在宿主上按场景覆盖。

css

super-checkbox {
  --super-checkbox-border-color: #34445f;
  --super-checkbox-background: #fffef9;
  --super-checkbox-checked-background: #3978e9;
  --super-checkbox-checked-color: #fff;
  --super-checkbox-hover-color: #3fa66a;
  --super-checkbox-focus-color: #356df3;
  --super-checkbox-rotation: -0.35deg;
  --super-checkbox-card-background: #fffef9;
  --super-checkbox-card-checked-background: #f3f7ff;
  --super-checkbox-card-padding: 13px 16px;
}

super-radio {
  --super-radio-border-color: #34445f;
  --super-radio-background: #fffef9;
  --super-radio-checked-color: #3978e9;
  --super-radio-hover-color: #3fa66a;
  --super-radio-focus-color: #356df3;
  --super-radio-rotation: -0.4deg;
  --super-radio-option-background: #fffef9;
  --super-radio-option-checked-background: #dff3df;
  --super-radio-option-padding: 9px 15px;
}

super-switch {
  --super-switch-background: #d6d9de;
  --super-switch-checked-background: #68c875;
  --super-switch-border-color: #6b7280;
  --super-switch-checked-border-color: #2e7738;
  --super-switch-focus-color: #356df3;
  --super-switch-rotation: -0.3deg;
}

可调整的尺寸 token 包括 Checkbox 的 --super-checkbox-size、--super-checkbox-gap、--super-checkbox-font-size，Radio 的 --super-radio-size、--super-radio-dot-size、--super-radio-gap、--super-radio-font-size，以及 Switch 的 --super-switch-width、--super-switch-height、--super-switch-thumb-size、--super-switch-gap、--super-switch-font-size。

表单限制

三个组件当前都不是 form-associated Custom Element。内部原生控件用于语义、键盘与焦点行为，但宿主的 name / value 不会自动进入原生表单提交数据，也没有公开 form、validity、checkValidity() 或表单重置契约。需要提交时，请在 super-*-change 事件中同步应用状态，或显式同步到表单字段；不要依赖 Shadow DOM 内部实现。

Checkbox · Radio · Switch 选择器套装 ​

类型 ​

Checkbox 多选框 ​

Radio 单选框 ​

Switch 开关 ​

尺寸 ​

状态 ​

校验与提示 ​

常用组合与布局 ​

状态同步 ​

无障碍 ​

API ​

Checkbox Attributes / Properties ​

Radio Attributes / Properties ​

Switch Attributes / Properties ​

Events ​

Methods ​

Slots ​

CSS Parts ​

CSS Custom Properties ​

表单限制 ​

Checkbox · Radio · Switch 选择器套装

类型

Checkbox 多选框

Radio 单选框

Switch 开关

尺寸

状态

校验与提示

常用组合与布局

状态同步

无障碍

API

Checkbox Attributes / Properties

Radio Attributes / Properties

Switch Attributes / Properties

Events

Methods

Slots

CSS Parts

CSS Custom Properties

表单限制