---
title: "Checkbox 复选框"
description: "在选中与未选中之间切换的复选控件"
category: Form
status: beta
since: 0.3.4
tags: [checkbox, form, selection]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
点击方框或文案切换。
:::TuffDemoWrapper{demo="CheckboxCheckboxDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const checked = ref(false)
  </script>

  <template>
    <TxCheckbox v-model="checked" label="选项" />
  </template>
---
:::

### 变体
默认 `checkmark` 显示勾选标记；`variant="fill"` 只填充方框。
:::TuffDemoWrapper{demo="CheckboxCheckboxVariantsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCheckbox v-model="fillChecked" variant="fill" label="填充样式" />
    <TxCheckbox v-model="checkmarkChecked" variant="checkmark" label="带勾选标记" />
  </template>
---
:::

### 禁用
:::TuffDemoWrapper{demo="CheckboxCheckboxDisabledDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCheckbox v-model="unchecked" label="禁用" disabled />
    <TxCheckbox v-model="checked" label="禁用且已选中" disabled />
  </template>
---
:::

### 文案在前
`labelPlacement="start"` 把文案放在方框前。
:::TuffDemoWrapper{demo="CheckboxCheckboxLabelStartDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCheckbox v-model="checked" label="我在前面" label-placement="start" />
  </template>
---
:::

### 无文案
没有 `label` 或插槽时，必须传 `aria-label`。
:::TuffDemoWrapper{demo="CheckboxCheckboxNoLabelDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCheckbox v-model="checked" aria-label="勾选" />
  </template>
---
:::

### 加载中
等待服务端确认时设置 `loading`：方框变为旋转环，未选中为灰色，已选中与部分选中为主色，期间不可切换。
:::TuffDemoWrapper{demo="CheckboxCheckboxLoadingDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const checked = ref(false)
  const committing = ref(false)
  const mixed = ref(false)

  async function commit(next: boolean) {
    committing.value = true
    try {
      await save(next)
      checked.value = next
    }
    finally {
      committing.value = false
    }
  }
  </script>

  <template>
    <TxCheckbox :model-value="checked" :loading="committing" label="异步提交" @change="commit" />
    <TxCheckbox v-model="mixed" label="加载中 / 部分选中" indeterminate loading />
  </template>
---
:::

### 自定义文案
默认插槽替代 `label`。
:::TuffDemoWrapper{demo="CheckboxCheckboxSlotDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCheckbox v-model="checked">
      <span>自定义标签</span>
    </TxCheckbox>
  </template>
---
:::

### 最佳实践

- 优先用可见的 `label` 或插槽；只有没有可见文案时才用 `ariaLabel`。
- 「正在提交」用 `loading`，「不可用」用 `disabled`；用 `disabled` 表示忙碌会让控件像是永久不可用。
- 需要服务端确认时设置 `loading`，成功后再写回 `modelValue`；失败时只撤下 `loading`。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `modelValue` | `boolean` | `false` | 选中状态，配合 `v-model` 使用。 |
| `disabled` | `boolean` | `false` | 禁止切换，并移出 Tab 序列。 |
| `loading` | `boolean` | `false` | 显示旋转环并禁止切换，不套用禁用态配色。 |
| `label` | `string` | - | 方框旁的文案。 |
| `labelPlacement` | `'start' \| 'end'` | `'end'` | 文案在方框前或后。 |
| `variant` | `'checkmark' \| 'fill'` | `'checkmark'` | `checkmark` 显示勾选标记，`fill` 只填充方框。 |
| `ariaLabel` | `string` | - | 没有可见文案时的可访问名称。 |
| `indeterminate` | `boolean` | `false` | 部分选中：显示横杠，点击后变为选中。 |

### 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `update:modelValue` | `(value: boolean) => void` | 用户切换后触发，参数为新值。 |
| `change` | `(value: boolean) => void` | 与 `update:modelValue` 同时触发。 |

### 插槽

| 插槽名 | 说明 |
|--------|------|
| `default` | 自定义文案，优先于 `label`。 |

## 概述

- 根节点是原生 `<button role="checkbox">`；点击、Enter 或 Space 切换。
- 受控组件：切换只派发事件，父级回写 `modelValue` 后外观才更新。
- `indeterminate` 时 `aria-checked="mixed"`；加载中已选中与部分选中外观相同，靠它区分。
- `disabled` 与 `loading` 都设置原生 `disabled`；`loading` 另设 `aria-busy="true"`，有可见文案时不渲染 `aria-label`。
- 在 `TxFormItem` 中，表单项的 label 经 `for` 命名复选框；复选框自带文案时改用 `aria-labelledby`，同时引用两者。表单的 `disabled` 同样生效。
- 减少动态效果时，加载环停止旋转。

## 技术实现

- `index.ts` 同时导出 `TuffCheckbox` 与 `TxCheckbox`。
- 源码：`packages/tuffex/packages/components/src/checkbox/`。

<TuffDocSourceLink />
