介绍
在一组可选项中进行任意选择。
引入
js
import Checkbox from 'sard-uniapp/components/checkbox/checkbox.vue'
import CheckboxGroup from 'sard-uniapp/components/checkbox-group/checkbox-group.vue'代码演示
基础使用
使用 checked 属性控制是否选中。
vue
<template>
<sar-checkbox v-model:checked="checked" @change="onChange">
{{ checked ? '已选中' : '未选中' }}
</sar-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>
<sar-checkbox v-model:checked="checked" @change="onChange">
{{ checked ? '已选中' : '未选中' }}
</sar-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>
<sar-checkbox readonly>复选框</sar-checkbox>
<sar-checkbox readonly checked root-style="margin-top: 10rpx">
复选框
</sar-checkbox>
<doc-title>禁用</doc-title>
<sar-checkbox disabled>复选框</sar-checkbox>
<sar-checkbox disabled checked root-style="margin-top: 10rpx">
复选框
</sar-checkbox>
</template>图标大小
使用 size 属性设置图标大小。
vue
<template>
<sar-checkbox size="48rpx">复选框</sar-checkbox>
</template>图标颜色
使用 checked-color 属性设置选中时的图标颜色。
vue
<template>
<sar-checkbox checked checked-color="var(--sar-red)">复选框</sar-checkbox>
</template>图标类型
设置 type 属性为 circle 可以使图标变为圆形。
vue
<template>
<sar-checkbox checked type="circle">复选框</sar-checkbox>
</template>自定义图标
如果内置的图标不满足需求,可以使用 icon 插槽设置为任意的图标。 插槽接收checked属性表示当前的选中状态。
vue
<template>
<sar-checkbox checked>
<template #icon="{ checked }">
<sar-icon family="demo-icons" :name="checked ? 'heart-fill' : 'heart'" />
</template>
复选框
</sar-checkbox>
</template>复选框组
复选框组用于收集选中状态的复选框的值。
vue
<template>
<sar-checkbox-group v-model="value" @change="onChange">
<sar-checkbox value="option1">选项1</sar-checkbox>
<sar-checkbox value="option2">选项2</sar-checkbox>
<sar-checkbox value="option3">选项3</sar-checkbox>
</sar-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>
<sar-checkbox-group v-model="value" @change="onChange">
<sar-checkbox value="option1">选项1</sar-checkbox>
<sar-checkbox value="option2">选项2</sar-checkbox>
<sar-checkbox value="option3">选项3</sar-checkbox>
</sar-checkbox-group>
</template>
<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const onChange = (value2) => {
console.log("change", value2);
};
</script>排列方向
将 direction 属性设置为 horizontal 后,复选框组会变成水平排列。
vue
<template>
<sar-checkbox-group v-model="value" direction="horizontal">
<sar-checkbox value="option1">选项1</sar-checkbox>
<sar-checkbox value="option2">选项2</sar-checkbox>
<sar-checkbox value="option3">选项3</sar-checkbox>
</sar-checkbox-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(['option2'])
</script>vue
<template>
<sar-checkbox-group v-model="value" direction="horizontal">
<sar-checkbox value="option1">选项1</sar-checkbox>
<sar-checkbox value="option2">选项2</sar-checkbox>
<sar-checkbox value="option3">选项3</sar-checkbox>
</sar-checkbox-group>
</template>
<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
</script>自动渲染复选框
使用 options 属性设置可选项。
vue
<template>
<sar-checkbox-group v-model="value" :options="options"></sar-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>
<sar-checkbox-group v-model="value" :options="options"></sar-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: `\u9009\u9879${i + 1}`
};
});
</script>自定义 UI
如果只想使用复选的逻辑,并想自定义 UI,可以使用复选框组的 custom 插槽。
这个插槽接收 toggle方法和 value 属性作为参数。toggle 用于切换指定选项的选中状态,value 用于判断选中状态。
vue
<template>
<sar-checkbox-group v-model="value">
<template #custom="{ toggle, value }">
<view>
<sar-tag
v-for="option in options"
:key="option.value"
theme="primary"
root-style="margin-right: 20rpx"
:plain="!value.includes(option.value)"
@click="toggle(option.value)"
>
{{ option.label }}
</sar-tag>
</view>
</template>
</sar-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>
<sar-checkbox-group v-model="value">
<template #custom="{ toggle, value }">
<view>
<sar-tag
v-for="option in options"
:key="option.value"
theme="primary"
root-style="margin-right: 20rpx"
:plain="!value.includes(option.value)"
@click="toggle(option.value)"
>
{{ option.label }}
</sar-tag>
</view>
</template>
</sar-checkbox-group>
</template>
<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const options = [
{ value: "option1", label: "\u9009\u98791" },
{ value: "option2", label: "\u9009\u98792" },
{ value: "option3", label: "\u9009\u98793" }
];
</script>结合 list 组件使用:
vue
<template>
<sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
<template #custom="{ toggle, value }">
<sar-list card>
<sar-list-item
v-for="option in options"
:key="option.value"
:title="option.label"
hover
@click="toggle(option.value)"
>
<template #value>
<sar-icon
v-if="value.includes(option.value)"
color="var(--sar-red)"
size="32rpx"
name="success"
/>
</template>
</sar-list-item>
</sar-list>
</template>
</sar-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>
<sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
<template #custom="{ toggle, value }">
<sar-list card>
<sar-list-item
v-for="option in options"
:key="option.value"
:title="option.label"
hover
@click="toggle(option.value)"
>
<template #value>
<sar-icon
v-if="value.includes(option.value)"
color="var(--sar-red)"
size="32rpx"
name="success"
/>
</template>
</sar-list-item>
</sar-list>
</template>
</sar-checkbox-group>
</template>
<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const options = [
{ value: "option1", label: "\u9009\u98791" },
{ value: "option2", label: "\u9009\u98792" },
{ value: "option3", label: "\u9009\u98793" }
];
</script>复选框组里面 checkbox 组件,会自动判断选中状态;可以给 checkbox 组件添加 readonly 属性以便将点击操作交给其他组件。
vue
<template>
<sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
<template #custom="{ toggle }">
<sar-list card>
<sar-list-item
v-for="option in options"
:key="option.value"
:title="option.label"
hover
@click="toggle(option.value)"
>
<template #icon>
<sar-checkbox readonly :value="option.value" />
</template>
</sar-list-item>
</sar-list>
</template>
</sar-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>
<sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
<template #custom="{ toggle }">
<sar-list card>
<sar-list-item
v-for="option in options"
:key="option.value"
:title="option.label"
hover
@click="toggle(option.value)"
>
<template #icon>
<sar-checkbox readonly :value="option.value" />
</template>
</sar-list-item>
</sar-list>
</template>
</sar-checkbox-group>
</template>
<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const options = [
{ value: "option1", label: "\u9009\u98791" },
{ value: "option2", label: "\u9009\u98792" },
{ value: "option3", label: "\u9009\u98793" }
];
</script>不确定状态
vue
<template>
<sar-checkbox
v-model:checked="allChecked"
:indeterminate="isIndeterminate"
root-style="margin-bottom: 40rpx"
@change="onAllChange"
>
全选
</sar-checkbox>
<sar-checkbox-group v-model="checkedResult">
<sar-checkbox
v-for="option in options"
:key="option.value"
:value="option.value"
>
{{ option.label }}
</sar-checkbox>
</sar-checkbox-group>
</template>
<script setup lang="ts">
import { useIndeterminate } from 'sard-uniapp'
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>
<sar-checkbox
v-model:checked="allChecked"
:indeterminate="isIndeterminate"
root-style="margin-bottom: 40rpx"
@change="onAllChange"
>
全选
</sar-checkbox>
<sar-checkbox-group v-model="checkedResult">
<sar-checkbox
v-for="option in options"
:key="option.value"
:value="option.value"
>
{{ option.label }}
</sar-checkbox>
</sar-checkbox-group>
</template>
<script setup lang="js">
import { useIndeterminate } from "sard-uniapp";
import { ref } from "vue";
const checkedResult = ref(["option2"]);
const options = [
{ value: "option1", label: "\u9009\u98791" },
{ value: "option2", label: "\u9009\u98792" },
{ value: "option3", label: "\u9009\u98793" }
];
const { allChecked, isIndeterminate, onAllChange } = useIndeterminate(
checkedResult,
options
);
</script>API
CheckboxProps
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| root-class | 组件根元素类名 | string | - |
| root-style | 组件根元素样式 | StyleValue | - |
| checked (v-model) | 是否选中 | boolean | false |
| indeterminate 1.6+ | 是否处于不确定状态 | 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: any) => void |
| update:checked | 选中状态改变时触发 | (checked: boolean) => void |
| change | 选中状态改变时触发 | (checked: boolean) => void |
CheckboxGroupProps
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| root-class | 组件根元素类名 | string | - |
| root-style | 组件根元素样式 | StyleValue | - |
| model-value (v-model) | 指定选中的选项 | any[] | - |
| disabled | 禁用状态 | boolean | - |
| readonly | 只读状态 | boolean | - |
| size | 图标的尺寸 | string | - |
| type | 图标类型 | 'square' | 'circle' | 'square' |
| checked-color | 选中时图标的颜色 | string | - |
| validate-event | 是否触发表单验证 | boolean | true |
| options | 自动设置复选框 | CheckboxGroupOption[] | - |
| option-keys | 自定义 options 的 label、value 的字段 | OptionKeys | {label: 'label', value: 'value'} |
CheckboxGroupOption
ts
export type CheckboxGroupOption =
| {
[key: PropertyKey]: any
}
| string
| number
| booleanOptionKeys
ts
export interface OptionKeys {
label?: string
value?: string
}CheckboxGroupSlots
| 插槽 | 描述 | 属性 |
|---|---|---|
| default | 自定义默认内容 | - |
| custom | 同默认插槽,额外可以接收 toggle 方法切换选中状态,用于自定义复选框结构和样式 | { toggle: (value: any) => void, value: any[] } |
CheckboxGroupEmits
| 事件 | 描述 | 类型 |
|---|---|---|
| update:model-value | 复选框组值改变时触发 | (value: any[]) => void |
| change | 复选框组值改变时触发 | (value: any[]) => void |
主题定制
CSS 变量
scss
page,
.sar-portal {
--sar-checkbox-group-column-gap: 24rpx;
--sar-checkbox-group-row-gap: 16rpx;
--sar-checkbox-icon-font-size: 40rpx;
--sar-checkbox-icon-color: var(--sar-fourth-color);
--sar-checkbox-icon-checked-color: var(--sar-primary);
--sar-checkbox-icon-disabled-color: var(--sar-disabled-color);
--sar-checkbox-icon-transition-duration: var(--sar-duration);
--sar-checkbox-label-margin-left: 16rpx;
}