Checkbox | Sard

介绍

在一组可选项中进行任意选择。

代码演示

基础使用

使用 checked 属性控制是否选中。

vue tsvue js

vue

<template>
  <s-checkbox v-model:checked="checked" @change="onChange">
    {{ checked ? '已选中' : '未选中' }}
  </s-checkbox>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const checked = ref(false)

const onChange = (value: any) => {
  console.log('change', value)
}
</script>

vue

<template>
  <s-checkbox v-model:checked="checked" @change="onChange">
    {{ checked ? '已选中' : '未选中' }}
  </s-checkbox>
</template>

<script setup lang="js">
import { ref } from 'vue'
const checked = ref(false)
const onChange = (value) => {
  console.log('change', value)
}
</script>

只读和禁用

只读或禁用后不可点击。

vue

<template>
  <doc-title>只读</doc-title>
  <s-checkbox readonly>复选框</s-checkbox>
  <s-checkbox readonly checked style="margin-top: 5px">复选框</s-checkbox>

  <doc-title>禁用</doc-title>
  <s-checkbox disabled>复选框</s-checkbox>
  <s-checkbox disabled checked style="margin-top: 5px">复选框</s-checkbox>
</template>

图标大小

使用 size 属性设置图标大小。

vue

<template>
  <s-checkbox size="24px">复选框</s-checkbox>
</template>

图标颜色

使用 checked-color 属性设置选中时的图标颜色。

vue

<template>
  <s-checkbox checked checked-color="var(--s-color-danger)">复选框</s-checkbox>
</template>

图标类型

设置 type 属性为 circle 可以使图标变为圆形。

vue

<template>
  <s-checkbox checked type="circle">复选框</s-checkbox>
</template>

自定义图标

如果内置的图标不满足需求，可以使用 icon 插槽设置为任意的图标。插槽接收checked属性表示当前的选中状态。

vue

<template>
  <s-checkbox checked>
    <template #icon="{ checked }">
      <demo-icon :name="checked ? 'heart-fill' : 'heart'" />
    </template>
    复选框
  </s-checkbox>
</template>

复选框组

复选框组用于收集选中状态的复选框的值。

vue tsvue js

vue

<template>
  <s-checkbox-group v-model="value" @change="onChange">
    <s-checkbox value="option1">选项1</s-checkbox>
    <s-checkbox value="option2">选项2</s-checkbox>
    <s-checkbox value="option3">选项3</s-checkbox>
  </s-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(['option2'])

const onChange = (value: any) => {
  console.log('change', value)
}
</script>

vue

<template>
  <s-checkbox-group v-model="value" @change="onChange">
    <s-checkbox value="option1">选项1</s-checkbox>
    <s-checkbox value="option2">选项2</s-checkbox>
    <s-checkbox value="option3">选项3</s-checkbox>
  </s-checkbox-group>
</template>

<script setup lang="js">
import { ref } from 'vue'
const value = ref(['option2'])
const onChange = (value) => {
  console.log('change', value)
}
</script>

排列方向

将 direction 属性设置为 horizontal 后，复选框组会变成水平排列。

vue tsvue js

vue

<template>
  <s-checkbox-group v-model="value" direction="horizontal">
    <s-checkbox value="option1">选项1</s-checkbox>
    <s-checkbox value="option2">选项2</s-checkbox>
    <s-checkbox value="option3">选项3</s-checkbox>
  </s-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(['option2'])
</script>

vue

<template>
  <s-checkbox-group v-model="value" direction="horizontal">
    <s-checkbox value="option1">选项1</s-checkbox>
    <s-checkbox value="option2">选项2</s-checkbox>
    <s-checkbox value="option3">选项3</s-checkbox>
  </s-checkbox-group>
</template>

<script setup lang="js">
import { ref } from 'vue'
const value = ref(['option2'])
</script>

自动渲染复选框

使用 options 属性设置可选项。

vue tsvue js

vue

<template>
  <s-checkbox-group v-model="value" :options="options"></s-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(['option2'])

const options = Array(3)
  .fill(0)
  .map((_, i) => {
    return {
      value: `option${i + 1}`,
      label: `选项${i + 1}`,
    }
  })
</script>

vue

<template>
  <s-checkbox-group v-model="value" :options="options"></s-checkbox-group>
</template>

<script setup lang="js">
import { ref } from 'vue'
const value = ref(['option2'])
const options = Array(3)
  .fill(0)
  .map((_, i) => {
    return {
      value: `option${i + 1}`,
      label: `选项${i + 1}`,
    }
  })
</script>

自定义 UI

如果只想使用复选的逻辑，并想自定义 UI，可以使用复选框组的 custom 插槽。

这个插槽接收 toggle方法和 value 属性作为参数。toggle 用于切换指定选项的选中状态，value 用于判断选中状态。

vue tsvue js

vue

<template>
  <s-checkbox-group v-model="value" #default="{ toggle, value }">
    <s-flex gap="medium">
      <s-tag
        v-for="option in options"
        :key="option.value"
        :color="value.includes(option.value) ? 'primary' : 'default'"
        :variant="value.includes(option.value) ? 'solid' : 'filled'"
        @click="toggle(option.value)"
      >
        {{ option.label }}
      </s-tag>
    </s-flex>
  </s-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]
</script>

vue

<template>
  <s-checkbox-group v-model="value" #default="{ toggle, value }">
    <s-flex gap="medium">
      <s-tag
        v-for="option in options"
        :key="option.value"
        :color="value.includes(option.value) ? 'primary' : 'default'"
        :variant="value.includes(option.value) ? 'solid' : 'filled'"
        @click="toggle(option.value)"
      >
        {{ option.label }}
      </s-tag>
    </s-flex>
  </s-checkbox-group>
</template>

<script setup lang="js">
import { ref } from 'vue'
const value = ref(['option2'])
const options = [
  {
    value: 'option1',
    label: '选项1',
  },
  {
    value: 'option2',
    label: '选项2',
  },
  {
    value: 'option3',
    label: '选项3',
  },
]
</script>

结合 list 组件使用：

vue tsvue js

vue

<template>
  <s-checkbox-group v-model="value" #default="{ toggle, value }">
    <s-list card>
      <s-list-item
        v-for="option in options"
        :key="option.value"
        :title="option.label"
        hover
        @click="toggle(option.value)"
      >
        <template #value>
          <Success v-if="value.includes(option.value)" class="text-base text-(--s-color-danger)" />
        </template>
      </s-list-item>
    </s-list>
  </s-checkbox-group>
</template>

<script setup lang="ts">
import { Success } from '@sard/icons'
import { ref } from 'vue'

const value = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]
</script>

vue

<template>
  <s-checkbox-group v-model="value" #default="{ toggle, value }">
    <s-list card>
      <s-list-item
        v-for="option in options"
        :key="option.value"
        :title="option.label"
        hover
        @click="toggle(option.value)"
      >
        <template #value>
          <Success v-if="value.includes(option.value)" class="text-base text-(--s-color-danger)" />
        </template>
      </s-list-item>
    </s-list>
  </s-checkbox-group>
</template>

<script setup lang="js">
import { Success } from '@sard/icons'
import { ref } from 'vue'
const value = ref(['option2'])
const options = [
  {
    value: 'option1',
    label: '选项1',
  },
  {
    value: 'option2',
    label: '选项2',
  },
  {
    value: 'option3',
    label: '选项3',
  },
]
</script>

复选框组里面 checkbox 组件，会自动判断选中状态；可以给 checkbox 组件添加 readonly 属性以便将点击操作交给其他组件。

vue tsvue js

vue

<template>
  <s-checkbox-group v-model="value" #default="{ toggle }">
    <s-list card>
      <s-list-item
        v-for="option in options"
        :key="option.value"
        :title="option.label"
        hover
        @click="toggle(option.value)"
        #icon
      >
        <s-checkbox readonly :value="option.value" />
      </s-list-item>
    </s-list>
  </s-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]
</script>

vue

<template>
  <s-checkbox-group v-model="value" #default="{ toggle }">
    <s-list card>
      <s-list-item
        v-for="option in options"
        :key="option.value"
        :title="option.label"
        hover
        @click="toggle(option.value)"
        #icon
      >
        <s-checkbox readonly :value="option.value" />
      </s-list-item>
    </s-list>
  </s-checkbox-group>
</template>

<script setup lang="js">
import { ref } from 'vue'
const value = ref(['option2'])
const options = [
  {
    value: 'option1',
    label: '选项1',
  },
  {
    value: 'option2',
    label: '选项2',
  },
  {
    value: 'option3',
    label: '选项3',
  },
]
</script>

不确定状态

vue tsvue js

vue

<template>
  <s-checkbox
    v-model:checked="allChecked"
    :indeterminate="isIndeterminate"
    style="margin-bottom: 20px"
    @change="onAllChange"
  >
    全选
  </s-checkbox>

  <s-checkbox-group v-model="checkedResult">
    <s-checkbox v-for="option in options" :key="option.value" :value="option.value">
      {{ option.label }}
    </s-checkbox>
  </s-checkbox-group>
</template>

<script setup lang="ts">
import { useIndeterminate } from 'sard'
import { ref } from 'vue'

const checkedResult = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]

const { allChecked, isIndeterminate, onAllChange } = useIndeterminate(checkedResult, options)
</script>

vue

<template>
  <s-checkbox
    v-model:checked="allChecked"
    :indeterminate="isIndeterminate"
    style="margin-bottom: 20px"
    @change="onAllChange"
  >
    全选
  </s-checkbox>

  <s-checkbox-group v-model="checkedResult">
    <s-checkbox v-for="option in options" :key="option.value" :value="option.value">
      {{ option.label }}
    </s-checkbox>
  </s-checkbox-group>
</template>

<script setup lang="js">
import { useIndeterminate } from 'sard'
import { ref } from 'vue'
const checkedResult = ref(['option2'])
const options = [
  {
    value: 'option1',
    label: '选项1',
  },
  {
    value: 'option2',
    label: '选项2',
  },
  {
    value: 'option3',
    label: '选项3',
  },
]
const { allChecked, isIndeterminate, onAllChange } = useIndeterminate(checkedResult, options)
</script>

API

CheckboxProps

属性	描述	类型	默认值
checked	是否选中	boolean	false
indeterminate	是否处于不确定状态	boolean	false
value	复选框的值，配合复选框组一起使用	any	-
label	复选框标签	string	-
disabled	禁用状态	boolean	-
readonly	只读状态	boolean	-
size	图标的尺寸	string	-
type	图标类型	'square' \| 'circle'	'square'
checked-color	选中时图标的颜色	string	-
validate-event	是否触发表单验证	boolean	true

CheckboxSlots

插槽	描述	属性
default	自定义默认内容	-
icon	自定义图标	`{ checked: boolean }`

CheckboxEmits

事件	描述	类型
click	点击时触发	`(event: MouseEvent) => void`
update:checked	选中状态改变时触发	`(checked: boolean) => void`
change	选中状态改变时触发	`(checked: boolean) => void`

CheckboxGroupProps

属性	描述	类型	默认值
model-value	指定选中的选项	any[]	-
disabled	禁用状态	boolean	-
readonly	只读状态	boolean	-
size	图标的尺寸	string	-
type	图标类型	'square' \| 'circle'	'square'
checked-color	选中时图标的颜色	string	-
direction	排列方向	'horizontal' \| 'vertical'	'vertical'
validate-event	是否触发表单验证	boolean	true
options	自动设置复选框	CheckboxGroupOption[]	-
option-keys	自定义 options 的 label、value 的字段	OptionKeys	`{label: 'label', value: 'value'}`

CheckboxGroupOption

export type CheckboxGroupOption =
  | {
      [key: PropertyKey]: any
    }
  | string
  | number
  | boolean

OptionKeys

export interface OptionKeys {
  label?: string
  value?: string
}

CheckboxGroupSlots

插槽	描述	属性
default	自定义默认内容	-
custom	同默认插槽，额外可以接收 `toggle` 方法切换选中状态，用于自定义复选框结构和样式	`{ toggle: (value: any) => void, value: any[] }`

CheckboxGroupEmits

事件	描述	类型
update:modelValue	复选框组值改变时触发	`(value: any[]) => void`
change	复选框组值改变时触发	`(value: any[]) => void`

主题定制

样式变量

CSS 变量	值
`--s-checkbox-group-column-gap`	`var(--s-size-sm)`
`--s-checkbox-group-row-gap`	`var(--s-size-xs)`
`--s-checkbox-icon-font-size`	`20px`
`--s-checkbox-icon-color`	`var(--s-text-color-fourth)`
`--s-checkbox-icon-color-checked`	`var(--s-color-primary)`
`--s-checkbox-icon-color-disabled`	`var(--s-text-color-disabled)`
`--s-checkbox-label-margin-start`	`var(--s-size-xs)`

介绍 ​

代码演示 ​

基础使用 ​

只读和禁用 ​

图标大小 ​

图标颜色 ​

图标类型 ​

自定义图标 ​

复选框组 ​

排列方向 ​

自动渲染复选框 ​

自定义 UI ​

不确定状态 ​

API ​

CheckboxProps ​

CheckboxSlots ​

CheckboxEmits ​

CheckboxGroupProps ​

CheckboxGroupOption ​

OptionKeys ​

CheckboxGroupSlots ​

CheckboxGroupEmits ​

主题定制 ​

样式变量 ​

介绍

代码演示

基础使用

只读和禁用

图标大小

图标颜色

图标类型

自定义图标

复选框组

排列方向

自动渲染复选框

自定义 UI

不确定状态

API

CheckboxProps

CheckboxSlots

CheckboxEmits

CheckboxGroupProps

CheckboxGroupOption

OptionKeys

CheckboxGroupSlots

CheckboxGroupEmits

主题定制

样式变量