Checkbox 多选框

何时使用

在一组选项中选择多项，或表示开关型同意状态时使用。

基础用法

同意用户协议

<script setup lang="ts">
import { ref } from 'vue'
import { DanCheckbox } from '@dandan-ui/ui'

const checked = ref(true)
</script>

<template>
  <DanCheckbox v-model="checked">同意用户协议</DanCheckbox>
</template>

多选组

VueReactTypeScriptCSS（禁用）

已选：vue, ts

<script setup lang="ts">
import { ref } from 'vue'
import { DanCheckbox, DanCheckboxGroup } from '@dandan-ui/ui'

const list = ref(['vue', 'ts'])
</script>

<template>
  <div style="display: grid; gap: 12px">
    <DanCheckboxGroup v-model="list">
      <DanCheckbox label="vue">Vue</DanCheckbox>
      <DanCheckbox label="react">React</DanCheckbox>
      <DanCheckbox label="ts">TypeScript</DanCheckbox>
      <DanCheckbox label="css" disabled>CSS（禁用）</DanCheckbox>
    </DanCheckboxGroup>
    <div style="font-size: 13px; color: var(--dan-color-text-secondary)">
      已选：{{ list.join(', ') || '无' }}
    </div>
  </div>
</template>

全选 / 半选

全选

上海北京广州深圳

<script setup lang="ts">
import { computed, ref } from 'vue'
import { DanCheckbox, DanCheckboxGroup } from '@dandan-ui/ui'

const cities = ['上海', '北京', '广州', '深圳']
const checked = ref(['上海', '北京'])
const checkAll = computed({
  get: () => checked.value.length === cities.length,
  set: (val: boolean) => {
    checked.value = val ? [...cities] : []
  },
})
const indeterminate = computed(
  () => checked.value.length > 0 && checked.value.length < cities.length,
)
</script>

<template>
  <div style="display: grid; gap: 12px">
    <DanCheckbox v-model="checkAll" :indeterminate="indeterminate">
      全选
    </DanCheckbox>
    <DanCheckboxGroup v-model="checked">
      <DanCheckbox v-for="city in cities" :key="city" :label="city">
        {{ city }}
      </DanCheckbox>
    </DanCheckboxGroup>
  </div>
</template>

API

Checkbox Props

属性	说明	类型	默认值	必填
modelValue / v-model	单独使用时为布尔；也可绑定数组（少见）	boolean | string | number | Array<...>	—	否
label	在 Group 内表示该选项的值	string | number | boolean	—	组内建议必填
disabled	禁用当前项；也可继承 Group / Form	boolean	false	否
indeterminate	半选样式（仅视觉，常用于全选）	boolean	false	否

Checkbox Events

事件名	说明	回调参数
update:modelValue	单独使用时的 v-model	(value) => void
change	勾选变化；组内由 Group 统一处理	(value) => void

CheckboxSlots

插槽名	说明
default	选项文案；未传时回退显示 label

CheckboxGroup Props

属性	说明	类型	默认值	必填
modelValue / v-model	已选值数组	Array<string | number | boolean>	[]	否
disabled	禁用整组	boolean	false	否

CheckboxGroup Events

事件名	说明	回调参数
update:modelValue	选中数组更新	(value: Array<...>) => void
change	选择变化，并联动 FormItem	(value: Array<...>) => void

CheckboxGroup Slots

插槽名	说明
default	放置多个 DanCheckbox

与 Form 联用

将 DanCheckboxGroup（或单个 Checkbox）放在 DanFormItem 内，change 会触发校验。数组字段可用 type: 'array' + min 规则限制最少选择数。