Checkbox 多选框

WARNING

label 作为 value 来使用已经被废弃, 建议label 只用来表示展示的文字，这个被废弃的用法将会在 3.0.0 版本被移除，请考虑使用新 API 替换. 新 API value 在2.6.0 中已经可用，您可以使用 value API 来设置复选框的值。

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

基础用法

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

checkbox-group元素能把多个 checkbox 管理为一组，只需要在 Group 中使用 v-model 绑定 Array 类型的变量即可。只有一个选项时的默认值类型为 Boolean，当选中时值为true。 s-checkbox 标签中的内容将成为复选框按钮之后的描述。

<template>
  <div>
    <s-checkbox v-model="checked1" label="Option 1" size="large" />
    <s-checkbox v-model="checked2" label="Option 2" size="large" />
  </div>
  <div>
    <s-checkbox v-model="checked3" label="Option 1" />
    <s-checkbox v-model="checked4" label="Option 2" />
  </div>
  <div>
    <s-checkbox v-model="checked5" label="Option 1" size="small" />
    <s-checkbox v-model="checked6" label="Option 2" size="small" />
  </div>
  <div>
    <s-checkbox v-model="checked7" label="Option 1" size="small" disabled />
    <s-checkbox v-model="checked8" label="Option 2" size="small" disabled />
  </div>
</template>

<script setup>
import SCheckbox from '@/components/Checkbox'
import { ref } from 'vue'

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

<style lang="scss" scoped>

</style>

禁用状态

多选框不可用状态。

设置 disabled 属性即可。

DisabledNot disabled

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

<script setup>
import SCheckbox from '@/components/Checkbox'
import { ref } from 'vue'

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

<style lang="scss" scoped>

</style>

多选框组

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

在 s-checkbox 元素中定义 v-model 绑定变量，单一的 checkbox 中，默认绑定变量的值会是 Boolean，选中为 true。在 s-checkbox 组件中，value 是选择框的值。如果该组件下没有被传入内容，那么 label 将会作为 checkbox 按钮后的介绍。 value 也与数组中的元素值相对应。如果指定的值存在于数组中，就处于选择状态，反之亦然。

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

<script setup>
import SCheckbox, { SCheckboxGroup} from '@/components/Checkbox'
import { ref } from 'vue'

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

<style lang="scss" scoped>

</style>

中间状态

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

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

<script setup>
import SCheckbox, { SCheckboxGroup} from '@/components/Checkbox'
import { ref } from 'vue'

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

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

<style lang="scss" scoped>

</style>

可选项目数量的限制

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

ShanghaiBeijingGuangzhouShenzhen

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

<script setup>
import SCheckbox, { SCheckboxGroup} from '@/components/Checkbox'
import { ref } from 'vue'

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

<style lang="scss" scoped>

</style>

按钮样式

按钮样式的多选组合。

只需要把 s-checkbox 元素替换为 s-checkbox-button 元素即可。此外，sharp-ui 还提供了size属性。

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

<script setup>
import {SCheckboxGroup,SCheckboxButton} from '@/components/Checkbox'
import { ref } from 'vue'

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>

带有边框

设置border属性可以渲染为带有边框的多选框。

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

<script setup>
import SCheckbox, { SCheckboxGroup} from '@/components/Checkbox'
import { ref } from 'vue'

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

<style lang="scss" scoped>

</style>

Checkbox API

Checkbox Attributes

Name	Description	Type	Default
model-value / v-model	binding value	string / number / boolean	—
value ^(2.6.0)	value of the Checkbox when used inside a `checkbox-group`	string / number / boolean / object	—
label	label of the Checkbox when used inside a `checkbox-group`. If there's no value, `label` will act as `value`	string / number / boolean / object	—
true-value ^(2.6.0)	value of the Checkbox if it's checked	string / number	—
false-value ^(2.6.0)	value of the Checkbox if it's not checked	string / number	—
true-label ^(deprecated)	value of the Checkbox if it's checked	string / number	—
false-label ^(deprecated)	value of the Checkbox if it's not checked	string / number	—
disabled	whether the Checkbox is disabled	boolean	false
border	whether to add a border around Checkbox	boolean	false
size	size of the Checkbox	enum `'large' \| 'default' \| 'small'`	—
name	native 'name' attribute	string	—
checked	if the Checkbox is checked	boolean	false
indeterminate	Set indeterminate state, only responsible for style control	boolean	false
validate-event	whether to trigger form validation	boolean	true
tabindex	input tabindex	string / number	—
id	input id	string	—
controls ^(a11y) ^(deprecated)	same as [aria-controls] (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls), takes effect when `indeterminate` is `true`	string	—
aria-controls ^(a11y) ^(2.7.2)	same as [aria-controls] (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls), takes effect when `indeterminate` is `true`	string	—

Checkbox Events

Name	Description	Type
change	triggers when the binding value changes	Function `(value: string \| number \| boolean) => void`

Checkbox Slots

Name	Description
default	customize default content

CheckboxGroup API

CheckboxGroup Attributes

Name	Description	Type	Default
model-value / v-model	binding value	object `string[] \| number[]`	[
size	size of checkbox	enum `'large' \| 'default' \| 'small'`	—
disabled	whether the nesting checkboxes are disabled	boolean	false
min	minimum number of checkbox checked	number	—
max	maximum number of checkbox checked	number	—
label ^(a11y) ^(deprecated)	native `aria-label` attribute	string	—
aria-label ^(a11y) ^(2.7.2)	native `aria-label` attribute	string	—
text-color	font color when button is active	string	#ffffff
fill	border and background color when button is active	string	#409eff
tag	element tag of the checkbox group	string	div
validate-event	whether to trigger form validation	boolean	true

CheckboxGroup Events

Name	Description	Type
change	triggers when the binding value changes	Function `(value: string[] \| number[] ) => void`

CheckboxGroup Slots

Name	Description	Subtags
default	customize default content	Checkbox / Checkbox-button

CheckboxButton API

CheckboxButton Attributes

Name	Description	Type	Default
value ^(2.6.0)	value of the checkbox when used inside a `checkbox-group`	string / number / boolean / object	—
label	label of the checkbox when used inside a `checkbox-group`. If there's no value, `label` will act as `value`	string / number / boolean / object	—
true-value ^(2.6.0)	value of the checkbox if it's checked	string / number	—
false-value ^(2.6.0)	value of the checkbox if it's not checked	string / number	—
true-label ^(deprecated)	value of the checkbox if it's checked	string / number	—
false-label ^(deprecated)	value of the checkbox if it's not checked	string / number	—
disabled	whether the checkbox is disabled	boolean	false
name	native 'name' attribute	string	—
checked	if the checkbox is checked	boolean	false

CheckboxButton Slots

Name	Description
default	customize default content

Checkbox 多选框 ​

基础用法 ​

禁用状态 ​

多选框组 ​

中间状态 ​

可选项目数量的限制 ​

按钮样式 ​

带有边框 ​

Checkbox API ​

Checkbox Attributes ​

Checkbox Events ​

Checkbox Slots ​

CheckboxGroup API ​

CheckboxGroup Attributes ​

CheckboxGroup Events ​

CheckboxGroup Slots ​

CheckboxButton API ​

CheckboxButton Attributes ​

CheckboxButton Slots ​