Checkbox
独立确认或多项选择。中文惯用名：复选框。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.checkbox |
| 名称 | Checkbox |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 独立确认或多项选择 |
| 描述 | 中文惯用名：复选框。 |
预览
静态结构：Checkbox 为 inline-flex 包裹：勾选框（data-slot="checkbox" + data-slot="checkbox-indicator" 勾选标记）+ 旁侧 label 文本，label 经 htmlFor 关联控件 useId，点击文字即切换。Form 内声明非空 name 时外层为 data-slot="form-item" 容器（mb-4），label 仍与勾选框同行、不另起表单标签行，校验错误以 data-slot="form-error" 追加在下方。
DSL 结构
{
"type": "Checkbox",
"props": {
"name": "subscribe",
"label": "订阅版本更新通知",
"value": true
}
}何时用
何时使用
- 布尔开关语义的勾选：同意条款、订阅通知、记住选项、启用某能力。
- 一组独立选项中可多选的集合（多个 Checkbox 并列，各自独立提交）。
- 表单内的 boolean 字段：声明 name 即自动注册，值为 true / false。
何时不用
- 多个互斥选项中选一个：使用 RadioGroup。
- 即时启停某个能力并立即生效（如自动保存）：使用 Switch——多选 Checkbox、单选 RadioGroup、即时启停 Switch。
- 「全选 / 反选」等集合控制：这是业务组合，用 Checkbox 组的半选态自行实现。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（勾选 / 未勾选） | 方框 + 标签文本，选中时框内显示勾 | 布尔选项、多选集合中的单项 |
| 无 label 纯勾选框 | 仅方框（label 缺省不渲染） | 表格行选择列、与外部文本配合的紧凑场景 |
| Form 表单项 | form-item 容器：勾选框 + 标签同行，错误行在下方 | 表单内 boolean 字段（声明 name 自动注册） |
| disabled 禁用 | 半透明不可切换 | 只读回显、不可变更的授权项 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项（值为 boolean） |
label | string | — | 勾选框旁的标签文本（Form 内仍与勾选框同行，不另起表单标签行） |
rules | FieldRule[] | — | 校验规则（如必勾：required） |
value | boolean | — | 受控值（独立渲染时生效）；Form 内作为字段初始值（优先于 Form initialValues） |
disabled | boolean | false | 禁用切换 |
onChange | (checked: boolean) => void | — | 勾选变化事件，传出 boolean（Renderer 绑定 events.onChange；DSL 语义值） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为控件包裹） |
使用规范
- 三态边界：多选集合用多个 Checkbox，互斥单选用 RadioGroup，即时启停用 Switch，不要互相替代。
- 未勾选与未填写语义不同：必勾项配 rules.required，校验文案写清后果（如「请先同意服务条款」）。
- 标签文案用肯定句式（「订阅更新通知」而非「不订阅更新通知」），避免双重否定。
- 一个 Checkbox 只表达一个布尔命题；需要「同意 A 且同意 B」时拆成两项。
- Form 内声明非空 name 才注册字段；未声明 name 时仅作独立受控控件使用。
正例
- ✓ 注册表单：Checkbox「我已阅读并同意服务条款」，name + rules 必填，未勾选提交被拦截。
- ✓ 通知设置：多个 Checkbox 并列（邮件 / 短信 / 站内信），各自独立 name 随表单提交。
- ✓ 只读回显：disabled 展示已确认的选项，用户可见但不可改。
反例
- ✕ 用 Checkbox 做「启用 / 停用」的即时开关（应使用 Switch）。
- ✕ 用多个 Checkbox 实现互斥单选（应使用 RadioGroup，否则用户可同时勾选）。
- ✕ 必勾项不配校验，用户跳过同意直接提交。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。