复选框 Checkbox

在一组数据中，用户可通过复选框选择一个或多个数据。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

基础用法：最基本的点击选中操作。
禁用：禁用复选框。
受控：通过 checked 属性控制是否选中
复选框组：生成复选框组。设置 direction="vertical" 可以展示竖向的复选框组
全选：通过 indeterminate 属性可以实现半选效果。
布局：可以通过 children 传入 checkbox，配合Grid组件实现灵活的布局。
自定义 Icon：通过 icon 属性自定义选中态图标。
自定义节点内容：可以通过传入函数类型的 children 来自定义渲染节点内容( v2.29.0)。
useCheckbox：使用 useCheckbox 快捷管理复选框数据

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

Checkbox

T = string | number

参数名	描述	类型	默认值	版本
checked	是否选中	boolean	`-`	-
defaultChecked	默认是否选中	boolean	`-`	-
disabled	是否禁用	boolean	`-`	-
error	错误样式	boolean	`-`	-
indeterminate	半选状态	boolean	`-`	-
icon	自定义 IconCheck	ReactNode	`-`	2.43.0
className	节点类名	string \| string[]	`-`	-
style	节点样式	CSSProperties	`-`	-
value	复选框的 value 属性	T	`-`	-
onChange	点击复选框的回调	(checked: boolean, e: Event) => void	`-`	-

Checkbox.Group

参数名	描述	类型	默认值
disabled	整组失效	boolean	`-`
direction	方向	'horizontal' \| 'vertical'	`horizontal`
className	节点类名	string \| string[]	`-`
defaultValue	默认选中的选项	T[]	`-`
options	可选项	(T \| { label: ReactNode; value: T; disabled?: boolean; icon?: ReactNode })[]	`-`
style	节点样式	CSSProperties	`-`
value	选中的选项（受控模式）	T[]	`-`
onChange	变化时的回调函数	(value: T[], e: Event) => void	`-`

`Checkbox.useCheckbox`

/** T = string | number */
const result: ResultType = Checkbox.useCheckbox<T>(values: T[], defaultSelected?: T[]);

ResultType

参数名	描述	类型
selected	当前选中项	`T[]`
setSelected	只选中传入参数的选项	`(value: T[]) => void;`
setValueSelected	设置选项的选中状态，第二个参数为要设置的选中状态。	`(value: T \| T[], selected?: boolean) => void;`
selectAll	选中全部	`() => void;`
unSelectAll	取消全部选中	`() => void;`
isSelected	是否选项被选中	`(value: T) => boolean;`
toggle	切换选项选中状态。不传参数时，会切换所有选项的选中状态	`(value?: T \| T[]) => void;`
isAllSelected	是否全部选项被选中	`() => boolean;`
isPartialSelected	是否只有部分选项选中	`() => boolean;`