---
title: Checkbox 复选框
description: 支持选中、未选中与半选三种状态的独立勾选控件
---

# Checkbox 复选框

`Checkbox` 用于在一组互不排斥的选项里多选，或表示单个布尔开关（如「同意协议」）。

## 何时使用

- 多选：一组选项可以用任意组合选中；
- 单个布尔：如「记住我」「同意条款」；
- 父子联动：父项用 `indeterminate` 表达「部分选中」（见下方示例）；
- 只有一个开关、立即生效的场景请用 [Switch](/ui/form/switch)。

## 基础用法

`v-model` 绑定 `boolean`。

<demo vue="checkbox/basic.vue" />

## 半选联动

`indeterminate` 是纯展示状态：组件**不会**自动推导它，需要业务根据子项结果计算。

<demo vue="checkbox/indeterminate.vue" />

| 状态 | 表现 |
| --- | --- |
| `modelValue = true` | 显示勾选（优先级最高，会强制清掉半选） |
| `modelValue = false` + `indeterminate = true` | 显示减号（半选） |
| 两者都为 `false` | 显示空框 |

## 禁用态

<demo vue="checkbox/disabled.vue" />

## 富内容

默认插槽可以放任意内容（多行说明、链接、标签），此时仍然整块可点击。

<demo vue="checkbox/rich-label.vue" />

## API

### Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` | `boolean` | `false` | 双向绑定的选中状态 |
| `indeterminate` | `boolean` | `false` | 半选状态（仅展示，需业务自行计算）。选中时会被忽略 |
| `disabled` | `boolean` | `false` | 禁用态 |
| `name` | `string` | — | 原生 `name`，用于表单提交分组 |
| `value` | `string \| number \| boolean` | — | 原生 `value`，随表单提交的值 |

### Events

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `update:modelValue` | `(value: boolean)` | 勾选状态变化 |
| `change` | `(value: boolean, event: Event)` | 同上，附带原生事件 |
| `focus` | `(event: FocusEvent)` | 获得焦点 |
| `blur` | `(event: FocusEvent)` | 失去焦点 |

### Slots

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `default` | — | 复选框文案（可放富内容）。为空时不渲染文字容器 |

### 类型定义

```ts
export interface CheckboxProps {
  modelValue?: boolean
  indeterminate?: boolean
  disabled?: boolean
  name?: string
  value?: string | number | boolean
}
```

### 样式变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `--g3-checkbox-size` | `16px` | 勾选框边长 |
| `--g3-radius-sm` | `4px` | 勾选框圆角 |
| `--g3-color-primary` | `#18181b` | 选中态底色与边框 |
| `--g3-bg-disabled` / `--g3-text-disabled` | `rgba(0,0,0,.04 / .25)` | 禁用态 |

## 实现说明

- 底层是原生 `<input type="checkbox">`，通过 `<label>` 包裹：因此键盘 Space 切换、点击文字、屏幕阅读器状态全部由浏览器负责，组件只负责视觉；
- `indeterminate` 是 **DOM property**（不是 attribute），Vue 的绑定语法覆盖不到，组件内部在 `mounted` 与相关 prop 变化时手动写入 `input.indeterminate`；
- 勾选态优先：`modelValue = true` 时会强制把 DOM 的 `indeterminate` 置为 `false`，避免「已勾选却显示减号」；
- 原生 input 视觉上隐藏（`opacity: 0` + 1px 尺寸），但**保留在布局中**，这样 `:focus-visible` 的焦点环可以作用在自绘的方框上，键盘用户依然有焦点提示。