logoAnt Design

⌘ K
5.23.3

Checkbox
多选框

收集用户的多项选择。
使用import{ Checkbox }from"antd";
源码components/checkbox
文档
编辑此页更新日志

何时使用

  • 在一组可选项中进行多项选择时；
  • 单独使用可以表示两种状态之间的切换，和 switch 类似。区别在于切换 switch 会直接触发状态改变，而 checkbox 一般用于状态标记，需要和提交操作配合。

代码演示

基本用法

简单的 checkbox。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

受控的 Checkbox

联动 checkbox。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
全选

在实现全选效果时，你可能会用到 indeterminate 属性。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code


不可用

checkbox 不可用。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code




Checkbox 组

方便的从数组生成 Checkbox 组。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
布局

Checkbox.Group 内嵌 Checkbox 并与 Grid 组件一起使用，可以实现灵活的布局。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

API

通用属性参考：通用属性

Checkbox

参数说明类型默认值版本
autoFocus自动获取焦点booleanfalse
checked指定当前是否选中booleanfalse
defaultChecked初始是否选中booleanfalse
disabled失效状态booleanfalse
indeterminate设置 indeterminate 状态，只负责样式控制booleanfalse
onChange变化时的回调函数(e: CheckboxChangeEvent) => void-
onBlur失去焦点时的回调function()-
onFocus获得焦点时的回调function()-

Checkbox Group

参数说明类型默认值版本
defaultValue默认选中的选项(string | number)[][]
disabled整组失效booleanfalse
nameCheckboxGroup 下所有 input[type="checkbox"] 的 name 属性string-
options指定可选项string[] | number[] | Option[][]
value指定选中的选项(string | number | boolean)[][]
onChange变化时的回调函数(checkedValue: T[]) => void-
Option
interface Option {
  label: string;
  value: string;
  disabled?: boolean;
}

方法

Checkbox

名称描述版本
blur()移除焦点
focus()获取焦点
nativeElement返回 Checkbox 的 DOM 节点5.17.3

主题变量（Design Token）

全局 Token如何定制？

FAQ

为什么在 Form.Item 下不能绑定数据？

Form.Item 默认绑定值属性到 value 上，而 Checkbox 的值属性为 checked。你可以通过 valuePropName 来修改绑定的值属性。

<Form.Item name="fieldA" valuePropName="checked">
  <Checkbox />
</Form.Item>