# 复选框 Checkbox

- 页面: https://jiguang132.com/zh/resources/ant-design-mobile/docs/checkbox
- 资源: Ant Design Mobile (https://jiguang132.com/zh/resources/ant-design-mobile.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design-mobile/docs.md

在一组可选项中进行多选。

## 安装

```bash
npm install antd-mobile@5.43.0
```

antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 `unstableSetRender` 注册 `createRoot`，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 `<html data-prefers-color-scheme="dark">` 切换。

示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 `DemoBlock` 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。

在一组可选项中进行多选。

## 何时使用

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

## 示例

## Checkbox

### 属性

```ts | pure
type CheckboxValue = string | number
```

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| block | 是否渲染为块级元素 | `boolean` | `false` |
| checked | 指定当前是否选中 | `boolean` | `false` |
| defaultChecked | 初始是否选中 | `boolean` | `false` |
| disabled | 禁用状态 | `boolean` | `false` |
| icon | 自定义 `icon` 图标 | `(checked: boolean, indeterminate: boolean) => React.ReactNode` | - |
| id | `input` 元素的 `id`，常用来配合 `label` 使用 | `string` | - |
| indeterminate | 设置 `indeterminate` 状态，只负责样式控制 | `boolean` | `false` |
| onChange | 变化时回调函数 | `(val: boolean) => void` | - |
| onClick | Checkbox 的点击事件 | `(event: React.MouseEvent<HTMLLabelElement, MouseEvent>) => void` | - |
| value | 携带的标识值，用于 `Group` 模式 | `CheckboxValue` | - |

### Ref

| 属性    | 说明                         | 类型         |
| ------- | ---------------------------- | ------------ |
| check   | 触发 Checkbox 的选中         | `() => void` |
| uncheck | 触发 Checkbox 的取消选中     | `() => void` |
| toggle  | 触发 Checkbox 的选中状态切换 | `() => void` |

### CSS 变量

| 属性        | 说明                     | 默认值 |
| ----------- | ------------------------ | ------ |
| --font-size | 右侧文字描述的大小       | `17px` |
| --gap       | 图标和文字描述之间的间距 | `8px`  |
| --icon-size | 勾选图标的大小           | `22px` |

## Checkbox.Group

### 属性

| 参数         | 说明           | 类型                               | 默认值  |
| ------------ | -------------- | ---------------------------------- | ------- |
| defaultValue | 默认选中的选项 | `CheckboxValue[]`                  | `[]`    |
| disabled     | 整组失效       | `boolean`                          | `false` |
| onChange     | 变化时回调函数 | `(value: CheckboxValue[]) => void` | -       |
| value        | 指定选中的选项 | `CheckboxValue[]`                  | `[]`    |

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt