u

2026-10-08 22:38:34 +08:00
1 parent f572dce2f6
commit e99a9fb274
@@ -0,0 +1,102 @@
+---
+title: Checkbox 复选框
+description: 支持选中、未选中与半选三种状态的独立勾选控件
+---
+
+# Checkbox 复选框
+
+`Checkbox` 用于在一组互不排斥的选项里多选，或表示单个布尔开关（如「同意协议」）。
+
+## 何时使用
+
+- 多选：一组选项可以用任意组合选中；
+- 单个布尔：如「记住我」「同意条款」；
+- 父子联动：父项用 `indeterminate` 表达「部分选中」（见下方示例）；
+- 只有一个开关、立即生效的场景请用 [Switch](/ui/form/switch)。
+
+## 基础用法
+
+`v-model` 绑定 `boolean`。
+
+:::demo{name="checkbox/basic"}
+:::
+
+## 半选联动
+
+`indeterminate` 是纯展示状态：组件**不会**自动推导它，需要业务根据子项结果计算。
+
+:::demo{name="checkbox/indeterminate"}
+:::
+
+| 状态 | 表现 |
+| --- | --- |
+| `modelValue = true` | 显示勾选（优先级最高，会强制清掉半选） |
+| `modelValue = false` + `indeterminate = true` | 显示减号（半选） |
+| 两者都为 `false` | 显示空框 |
+
+## 禁用态
+
+:::demo{name="checkbox/disabled"}
+:::
+
+## 富内容
+
+默认插槽可以放任意内容（多行说明、链接、标签），此时仍然整块可点击。
+
+:::demo{name="checkbox/rich-label"}
+:::
+
+## 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` 的焦点环可以作用在自绘的方框上，键盘用户依然有焦点提示。