跳到主要内容

Checkbox 复选框Checkbox · CheckboxGroup

从一组选项里选零个或多个，或者单独表示“同意 / 不同意”。需要提交后才生效时用它；立即生效的设置用 Switch；只能选一个用 Radio。

基本用法

children 是标签文字，点文字同样可以切换。description 是标签下的说明。

状态

indeterminate 表示“部分选中”，只影响外观和读屏播报。

复选组

CheckboxGroup 用一个字符串数组管理一组复选框。放进 Field 会自动用 Field 的标签命名，否则请给 aria-label。

至少选一个
请勾选全部条款

受控用法

单个复选框用 checked / onChange（参数是新的布尔值）；组用 value / onChange（参数是选中项的数组）。下面是常见的“全选 + 半选”。

已选：read

规格

描边
1.5px；悬停时边变强调色，无光晕
选中
对勾描线 240ms · 延迟 50ms
取消
90ms 快速擦除

API

Checkbox

属性类型默认值说明
checkedboolean—是否选中（受控）。在带 value 的 CheckboxGroup 里由组决定。
defaultCheckedbooleanfalse初始是否选中（非受控）。
onChange(checked: boolean) => void—状态变化时触发，参数是新状态。
indeterminatebooleanfalse半选，只影响外观和读屏播报。
valuestring—在组里标识这一项；单独使用时是表单提交的值。
descriptionReactNode—标签下的说明文字。
invalidboolean—校验失败。
rootClassName / rootStylestring / CSSProperties—外层 <label> 的类名与样式。className / style 同样落在 <label> 上。
…restInputHTMLAttributes—其余原生属性（disabled、required、name…）和 ref 落在 <input> 上。

CheckboxGroup

属性类型默认值说明
valuestring[]—选中项的 value 列表（受控）。
defaultValuestring[][]初始选中项（非受控）。
onChange(value: string[]) => void—选中项变化时触发。
namestring—组内复选框共用的字段名。
orientation'vertical' | 'horizontal''vertical'排列方向；横向放不下会换行。
disabledboolean—整组禁用。
invalidboolean—整组标成校验失败。在 Field 里默认跟随 Field。

无障碍

  • 每一项都是真的 <input type="checkbox">，包在 <label> 里，点文字即可切换。
  • Tab 逐个经过每个复选框，Space 切换。复选组没有方向键导航，这是复选框的常规模式。
  • 半选时读屏读作“部分选中 / 混合”。
  • CheckboxGroup 是 role="group"，名称来自 Field 的标签或 aria-label。
  • 没有可见文字的复选框（表格里的行选择等）必须给 aria-label。
  • 勾选框本身是装饰（aria-hidden），状态由原生 input 传达；键盘聚焦时焦点环画在勾选框上。