多选框

收集用户的多项选择。

何时使用

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

代码演示

API

通用属性参考：通用属性

Checkbox

参数	说明	类型	默认值	全局配置
checked	指定当前是否选中	boolean	false	×
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-	6.0.0
defaultChecked	初始是否选中	boolean	false	×
disabled	失效状态	boolean	false	×
indeterminate	设置 indeterminate 状态，只负责样式控制	boolean	false	×
onChange	变化时的回调函数	(e: CheckboxChangeEvent) => void	-	×
onBlur	失去焦点时的回调	function()	-	×
onFocus	获得焦点时的回调	function()	-	×
styles	用于自定义组件内部各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-	6.0.0

Checkbox.Group

参数	说明	类型	默认值	版本
defaultValue	默认选中的选项	(string \| number)[]	[]
disabled	整组失效	boolean	false
name	CheckboxGroup 下所有 `input[type="checkbox"]` 的 `name` 属性	string	-
options	指定可选项	string[] \| number[] \| Option[]	[]
value	指定选中的选项	(string \| number \| boolean)[]	[]
title	选项的 title	`string`	-
className	选项的类名	`string`	-	5.25.0
style	选项的样式	`React.CSSProperties`	-
onChange	变化时的回调函数	(checkedValue: T[]) => void	-

Option

interface Option {
  label: string;
  value: string;
  disabled?: boolean;
}

方法

Checkbox

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

Semantic DOM

语义节点	原生说明	版本
`root`	根元素，包含行内 flex 布局、基线对齐、光标样式、重置样式等复选框容器的基础样式	6.0.0
`icon`	选中框元素，包含尺寸、方向、背景色、边框、圆角、过渡动画，以及选中状态的勾选标记样式	6.0.0
`label`	文本元素，包含文本的内边距和与复选框的间距样式	6.0.0

语义说明来源: vendor/components/checkbox/demo/_semantic.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

原生 ComponentToken 未声明可直接提取的自有字段；共享令牌或继承关系以以下声明为准。

声明来源: vendor/components/checkbox/style/index.ts

import { unit } from '@ant-design/cssinjs';

import { genFocusOutline, resetComponent } from '../../style';

import { genNoMotionRawStyle, genNoMotionStyle } from '../../style/motion';

import type { FullToken, GenerateStyle } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

// biome-ignore lint/suspicious/noEmptyInterface: ComponentToken need to be empty by default
export interface ComponentToken {}

/**
 * @desc Checkbox 组件的 Token
 * @descEN Token for Checkbox component
 */
interface CheckboxToken extends FullToken<'Checkbox'> {
  /**
   * @desc Checkbox 类名
   * @descEN Checkbox class name
   */
  checkboxCls: string;
  /**
   * @desc Checkbox 尺寸
   * @descEN Size of Checkbox
   */
  checkboxSize: number;
}

FAQ

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

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

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

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

参数	说明	类型	默认值
style	自定义样式	CSSProperties	-
className	自定义类名	string	-
rootClassName	添加在组件最外层的 className	string	-
autoFocus	自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效	boolean	false

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

vendor/components/checkbox/Checkbox.tsx
vendor/components/checkbox/Group.tsx
vendor/components/checkbox/GroupContext.ts
vendor/components/checkbox/index.tsx
vendor/components/checkbox/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。