Checkbox

何时使用 {#when-to-use}

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

代码演示 {#examples}

<code src="./demo/basic.tsx">基本用法</code> <code src="./demo/disabled.tsx">不可用</code> <code src="./demo/controller.tsx">受控的 Checkbox</code> <code src="./demo/group.tsx">Checkbox 组</code> <code src="./demo/check-all.tsx">全选</code> <code src="./demo/layout.tsx">布局</code> <code src="./demo/style-class.tsx" version="6.0.0">自定义语义结构的样式和类</code> <code src="./demo/debug-line.tsx" debug>同行布局</code> <code src="./demo/debug-disable-popover.tsx" debug>禁用下的 Tooltip</code> <code src="./demo/debug-group-width.tsx" debug>Group 内勾选框等宽</code> <code src="./demo/custom-line-width.tsx" debug>自定义 lineWidth</code>

API

通用属性参考：通用属性

参数	说明	类型	默认值
checked	指定当前是否选中	boolean	false
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-
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>	-

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

typescript

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

方法 {#methods}

Checkbox

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

Semantic DOM

主题变量（Design Token）{#design-token}

FAQ

为什么在 Form.Item 下不能绑定数据？ {#faq-form-item-limitations}

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

tsx

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