Checkbox 多选框 ​

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

WARNING

label 作为 value 来使用已经被 废弃, 建议label 只用来表示展示的文字，这个被废弃的用法将会在 3.0.0 版本被移除，请考虑使用新 API 替换.

TIP

新的 API value 已在 2.6.0 版本添加，文档中的示例都将使用 value。 如果您使用的版本 低于 2.6.0 并且使用 checkbox-group，请参考：

vue
<template>
  <el-checkbox-group v-model="checkList">
    <!-- works when >=2.6.0, recommended ✔️ value not work when <2.6.0 ❌ -->
    <el-checkbox label="Option 1" value="Value 1" />
    <!-- works when <2.6.0, deprecated act as value when >=3.0.0 -->
    <el-checkbox label="Option 2 & Value 2" />
  </el-checkbox-group>
</template>
ts
import { createApp } from 'vue'
import { Checkbox as ElCheckbox, CheckboxButton as ElCheckboxButton, CheckboxGroup as ElCheckboxGroup } from '@szhn/dh-design-pc'

const app = createApp()
app.use(ElCheckbox)
app.use(ElCheckboxButton)
app.use(ElCheckboxGroup)

基础用法 ​

单独使用可以表示两种状态之间的切换，写在标签中的内容为 checkbox 按钮后的介绍。

<template>
  <div>
    <el-checkbox v-model="checked1" label="Option 1" size="large" />
    <el-checkbox v-model="checked2" label="Option 2" size="large" />
  </div>
  <div class="my-2">
    <el-checkbox v-model="checked3" label="Option 1" />
    <el-checkbox v-model="checked4" label="Option 2" />
  </div>
  <div class="mt-2">
    <el-checkbox v-model="checked5" label="Option 1" size="small" />
    <el-checkbox v-model="checked6" label="Option 2" size="small" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Checkbox as ElCheckbox } from '@szhn/dh-design-pc'


const checked1 = ref(true)
const checked2 = ref(false)
const checked3 = ref(false)
const checked4 = ref(false)
const checked5 = ref(false)
const checked6 = ref(false)
</script>

禁用状态 ​

多选框不可用状态。

<template>
  <el-checkbox v-model="checked1" disabled>Disabled</el-checkbox>
  <el-checkbox v-model="checked2">Not disabled</el-checkbox>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Checkbox as ElCheckbox } from '@szhn/dh-design-pc'


const checked1 = ref(false)
const checked2 = ref(true)
</script>

多选框组 ​

适用于多个勾选框绑定到同一个数组的情景，通过是否勾选来表示这一组选项中选中的项。

<template>
  <el-checkbox-group v-model="checkList">
    <el-checkbox label="Option A" value="Value A" />
    <el-checkbox label="Option B" value="Value B" />
    <el-checkbox label="Option C" value="Value C" />
    <el-checkbox label="disabled" value="Value disabled" disabled />
    <el-checkbox
      label="selected and disabled"
      value="Value selected and disabled"
      disabled
    />
  </el-checkbox-group>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Checkbox as ElCheckbox, CheckboxGroup as ElCheckboxGroup } from '@szhn/dh-design-pc'


const checkList = ref(['Value selected and disabled', 'Value A'])
</script>

Options 属性 (2.11.2) ​

<template>
  <el-checkbox-group v-model="checkList" :options="options" :props="props" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CheckboxGroup as ElCheckboxGroup } from '@szhn/dh-design-pc'


const checkList = ref(['Value selected and disabled', 'Value A'])
const props = { label: 'name', value: 'id', disabled: 'unable' }
const options = [
  { name: 'Option A', id: 'Value A' },
  { name: 'Option B', id: 'Value B' },
  { name: 'Option C', id: 'Value C' },
  { name: 'disabled', id: 'Value disabled', unable: true },
  {
    name: 'selected and disabled',
    id: 'Value selected and disabled',
    unable: true,
  },
]
</script>

中间状态 ​

indeterminate 属性用以表示 checkbox 的不确定状态，一般用于实现全选的效果

<template>
  <el-checkbox
    v-model="checkAll"
    :indeterminate="isIndeterminate"
    @change="handleCheckAllChange"
  >
    Check all
  </el-checkbox>
  <el-checkbox-group
    v-model="checkedCities"
    @change="handleCheckedCitiesChange"
  >
    <el-checkbox v-for="city in cities" :key="city" :label="city" :value="city">
      {{ city }}
    </el-checkbox>
  </el-checkbox-group>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { CheckboxValueType } from '@szhn/dh-design-pc'
import { Checkbox as ElCheckbox, CheckboxGroup as ElCheckboxGroup } from '@szhn/dh-design-pc'


const checkAll = ref(false)
const isIndeterminate = ref(true)
const checkedCities = ref(['Shanghai', 'Beijing'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']

const handleCheckAllChange = (val: CheckboxValueType) => {
  checkedCities.value = val ? cities : []
  isIndeterminate.value = false
}
const handleCheckedCitiesChange = (value: CheckboxValueType[]) => {
  const checkedCount = value.length
  checkAll.value = checkedCount === cities.length
  isIndeterminate.value = checkedCount > 0 && checkedCount < cities.length
}
</script>

可选项目数量的限制 ​

使用 min 和 max 属性能够限制可以被勾选的项目的数量。

<template>
  <el-checkbox-group v-model="checkedCities" :min="1" :max="2">
    <el-checkbox v-for="city in cities" :key="city" :label="city" :value="city">
      {{ city }}
    </el-checkbox>
  </el-checkbox-group>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Checkbox as ElCheckbox, CheckboxGroup as ElCheckboxGroup } from '@szhn/dh-design-pc'


const checkedCities = ref(['Shanghai', 'Beijing'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
</script>

按钮样式 ​

按钮样式的多选组合。

<template>
  <div>
    <el-checkbox-group v-model="checkboxGroup1" size="large">
      <el-checkbox-button v-for="city in cities" :key="city" :value="city">
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup2">
      <el-checkbox-button v-for="city in cities" :key="city" :value="city">
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup3" size="small">
      <el-checkbox-button
        v-for="city in cities"
        :key="city"
        :value="city"
        :disabled="city === 'Beijing'"
      >
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup4" size="small" disabled>
      <el-checkbox-button v-for="city in cities" :key="city" :value="city">
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CheckboxButton as ElCheckboxButton, CheckboxGroup as ElCheckboxGroup } from '@szhn/dh-design-pc'


const checkboxGroup1 = ref(['Shanghai'])
const checkboxGroup2 = ref(['Shanghai'])
const checkboxGroup3 = ref(['Shanghai'])
const checkboxGroup4 = ref(['Shanghai'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
</script>

<style scoped>
.demo-button-style {
  margin-top: 24px;
}
</style>

带有边框 ​

<template>
  <div>
    <el-checkbox v-model="checked1" label="Option1" size="large" border />
    <el-checkbox v-model="checked2" label="Option2" size="large" border />
  </div>
  <div class="mt-4">
    <el-checkbox v-model="checked3" label="Option1" border />
    <el-checkbox v-model="checked4" label="Option2" border />
  </div>
  <div class="mt-4">
    <el-checkbox-group v-model="checkboxGroup1" size="small">
      <el-checkbox label="Option1" value="Value1" border />
      <el-checkbox label="Option2" value="Value2" border />
    </el-checkbox-group>
  </div>
  <div class="mt-4">
    <el-checkbox-group v-model="checkboxGroup1" size="small">
      <el-checkbox label="Option1" value="Value1" border disabled />
      <el-checkbox label="Option2" value="Value2" border disabled />
    </el-checkbox-group>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Checkbox as ElCheckbox, CheckboxGroup as ElCheckboxGroup } from '@szhn/dh-design-pc'


const checked1 = ref(true)
const checked2 = ref(false)
const checked3 = ref(false)
const checked4 = ref(true)
const checkboxGroup1 = ref(['Value1'])
</script>

Checkbox API ​

Checkbox Attributes ​

属性名说明类型默认值
model-value / v-model选中项绑定值string / number / boolean—
value 2.6.0选中状态的值（只有在checkbox-group或者绑定对象类型为array 时有效）string / number / boolean / object—
label选中状态的值，只有在绑定对象类型为 array 时有效。 如果没有 value， label则作为value使用string / number / boolean / object—
true-value 2.6.0选中时的值string / number—
false-value 2.6.0没有选中时的值string / number—
disabled是否禁用booleanfalse
border是否显示边框booleanfalse
sizeCheckbox 的尺寸enum—
name原生 name 属性string—
checked当前是否勾选booleanfalse
indeterminate设置不确定状态，仅负责样式控制booleanfalse
validate-event输入时是否触发表单的校验booleantrue
tabindex输入框的 tabindexstring / number—
idinput idstring—
aria-controls a11y 2.7.2与 aria-control一致, 当 indeterminate为 true时生效string—
aria-label a11y原生 aria-label属性string—
true-label deprecated选中时的值string / number—
false-label deprecated没有选中时的值string / number—
controls a11y deprecated和 aria-control一致。当 indeterminate 为 true 时生效string—

Checkbox Events ​

事件名说明类型
change当绑定值变化时触发的事件Function

Checkbox Slots ​

插槽名说明
default自定义默认内容

CheckboxGroup API ​

CheckboxGroup Attributes ​

属性名说明类型默认值
model-value / v-model绑定值array[]
size多选框组尺寸enum—
disabled是否禁用booleanfalse
min可被勾选的 checkbox 的最小数量number—
max可被勾选的 checkbox 的最大数量number—
aria-label a11y 2.7.2原生 aria-label属性string—
text-color当按钮为活跃状态时的字体颜色string#ffffff
fill当按钮为活跃状态时的边框和背景颜色string#409eff
tag复选框组元素标签stringdiv
validate-event是否触发表单验证booleantrue
label a11y deprecated原生 aria-label属性string—
options 2.11.2选项的数据源， value 的 key 和 label 和 disabled可以通过 props自定义.array—
props 2.11.2options 的配置object{value: 'value', label: 'label', disabled: 'disabled'}
type 2.11.5用于渲染选项的组件类型（例如 'button'）enum'checkbox'

CheckboxGroup Events ​

事件名说明类型
change当绑定值变化时触发的事件Function

CheckboxGroup Slots ​

插槽名说明子标签
default自定义默认内容Checkbox / Checkbox-button

CheckboxButton API ​

CheckboxButton Attributes ​

名称详情类型默认值
value 2.6.0选中状态的值，只有在绑定对象类型为 array 时有效。string / number / boolean / object—
label选中状态的值，只有在绑定对象类型为 array 时有效。 如果没有 value， label则作为value使用string / number / boolean / object—
true-value 2.6.0选中时的值string / number—
false-value 2.6.0没有选中时的值string / number—
disabled是否禁用booleanfalse
name原生 name 属性string—
checked当前是否勾选booleanfalse
true-label deprecated选中时的值string / number—
false-label deprecated没有选中时的值string / number—

CheckboxButton Slots ​

插槽名描述
default自定义默认内容