Checkbox 复选框
选择在提交表单时才生效时用 Checkbox:同意条款,或者用 CheckboxGroup 从一小组选项里任意勾选几个。立即生效的设置请用 Switch;要从很长的列表里选多个,请用带 multiple 的 Select。
Checkbox 是一个原生 input type="checkbox" 加上绘制出来的方框,和文字一起包在 label 里,所以表单、label、键盘和读屏软件都和普通复选框一样工作。CheckboxGroup 管理其中各个复选框的选中值。
#演示
#基础用法
标签文字用 children 或 label 传入。没有可见文字时,用 aria-label 给复选框命名。
#尺寸
#受控
checked 配合 onCheckedChange,由你来管理状态。
#自定义值
checkedValue 和 uncheckedValue 替换 checked 与 onCheckedChange 里的 true 和 false。
#半选
indeterminate 显示一条横线而不是勾,用于子项只选中了一部分的“全选”框。读屏软件会读作“部分选中”。
#复选框组
CheckboxGroup 里的每个 Checkbox 设置一个 value,组的 value 列出选中的那些。设置 max 后,选满时未选中的框会禁用;设置 min 后,只剩这么多时已选中的框会禁用。name 让表单提交所有选中的值。
#禁用
禁用的复选框仍然能看出选中状态。组上的 disabled 会禁用其中所有复选框。
#Checkbox Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
checked | boolean | string | number | undefined | 受控的选中状态:等于 checkedValue 时为选中。 | 未发布 |
defaultChecked | boolean | string | number | uncheckedValue | 非受控时的初始状态。 | 未发布 |
checkedValue | boolean | string | number | true | 选中时 checked 的值。 | 未发布 |
uncheckedValue | boolean | string | number | false | 未选中时 checked 的值。 | 未发布 |
indeterminate | boolean | false | 显示横线而不是勾。 | 未发布 |
disabled | boolean | false | 禁用复选框。 | 未发布 |
focusable | boolean | true | 为 false 时不进入 Tab 顺序,点击也不会让它获得焦点。 | 未发布 |
label | ReactNode | undefined | 标签文字,优先于 children。 | 未发布 |
size | small | medium | large | medium | 方框和文字的大小。 | 未发布 |
value | string | number | undefined | 在 CheckboxGroup 里的值,同时是原生 input 的 value。 | 未发布 |
onCheckedChange | (checked, event) => void | undefined | 以新的 checkedValue 或 uncheckedValue 调用。在组内不会调用。 | 未发布 |
className 和 style 作用在 label 上;ref 和其余原生属性(id、name、required、aria-*、onFocus 等)作用在原生 input 上。
#CheckboxGroup Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
value | (string | number)[] | null | undefined | 受控的选中值。 | 未发布 |
defaultValue | (string | number)[] | null | null | 非受控时初始选中的值。 | 未发布 |
disabled | boolean | false | 禁用组内所有复选框。 | 未发布 |
max | number | undefined | 最多可选中的数量。 | 未发布 |
min | number | undefined | 最少保持选中的数量。 | 未发布 |
name | string | undefined | 组内每个复选框的原生 name。 | 未发布 |
size | small | medium | large | undefined | 组内未单独设置尺寸的复选框的大小。 | 未发布 |
onUpdateValue | (value, meta: { actionType: "check" | "uncheck", value }) => void | undefined | 以新的选中值和本次变化调用。 | 未发布 |
组渲染为带 role="group" 的 div,不负责布局:复选框可以放在任何布局里,并用 aria-label 或 aria-labelledby 给组命名。要渲染一组选项,把它们映射成 Checkbox 即可。