Checkbox 复选框
选择一个或多个选项,或确认某项设置。
基础用法
通过文字内容提供选项名称,用户可独立切换选中状态。
basic.tsx
受控使用时传入 checked,在 onChange 中从 event.target.checked 读取布尔值。
示例
选项组
使用 CheckboxGroup 管理多个选项。与单个复选框不同,组的 value 和 onChange 使用字符串数组。
group.tsx
禁用状态
设置 disabled 后,选中状态仍可显示,但不能由用户切换。
未选中已选中
disabled.tsx
全选与半选
indeterminate 表示部分选中,不改变 checked 或提交值。子选项和全选逻辑由应用维护。
已选择 1 项
check-all.tsx
卡片选项
设置 variant="card",展示包含图标和说明的选项。
surfaces.tsx
成组选项
使用 CheckboxGroup variant="list" 展示成组列表。extra 只放状态标签等非交互内容,不放按钮或链接。
list.tsx
表单提交与重置
设置 name 后,只有已勾选且未禁用的选项参与提交。选项组按同一个字段名提交多个值,可用 FormData.getAll(name) 读取。
非受控字段在表单重置时恢复 defaultChecked 或 defaultValue;受控字段需要同步重置应用状态。
API
Checkbox API
支持 name、value、required、form 等原生 checkbox 属性。没有文字标签时提供 aria-label;className 和 style 作用于标签容器。
CheckboxGroupProps API
统一管理一组选项和值的参数。
CheckboxOption API
通过复选框组 options 提供的选项数据。