Checkbox 复选框

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

基础用法

使用标签 NueCheckbox 生成复选框。

通过 v-model 绑定复选框的值。

通过 label 属性或 默认插槽 设置复选框的标识文本。

<template>
    <nue-div>
        <nue-checkbox v-model="state" label="复选框"></nue-checkbox>
        <nue-checkbox v-model="state">复选框</nue-checkbox>
    </nue-div>
</template>

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

const state = ref(false);
</script>

禁用状态

通过 disabled 属性来禁用复选框，接受 Boolean 类型，默认为 false。

<template>
    <nue-div>
        <nue-checkbox v-model="state" label="正常复选框" />
        <nue-checkbox v-model="state" disabled label="禁用复选框" />
    </nue-div>
</template>

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

const state = ref(false);
</script>

大小

通过 size 属性来设置复选框的大小，可选值为 small 和 large，不设置则为正常大小。

<template>
    <nue-div align="center">
        <nue-checkbox v-model="state1" label="小型复选框" size="small" />
        <nue-checkbox v-model="state2" label="正常复选框" />
        <nue-checkbox v-model="state3" label="大型复选框" size="large" />
    </nue-div>
</template>

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

const state1 = ref(false);
const state2 = ref(false);
const state3 = ref(false);
</script>

中间状态

通过属性 indeterminate 设置复选框的中间状态，接受 Boolean 类型，默认为 false。

TIP

由于 indeterminate 属性表示的是一种模糊的中间状态，因此优先级会低于选中值为 true 、高于选中值为 false 的情况。

<template>
    <nue-div>
        <nue-checkbox v-model="state1" label="未选中" />
        <nue-checkbox
            v-model="state2"
            :indeterminate="isIndeterminate"
            label="中间状态"
        />
        <nue-checkbox v-model="state3" label="已选中" />
    </nue-div>
</template>

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

const state1 = ref(false);
const state2 = ref(false);
const state3 = ref(true);
const isIndeterminate = ref(true);
</script>

加载状态和状态变更前的回调函数

通过属性 loading 设置复选框的加载状态，通常搭配状态变更前的回调函数属性 before-check 使用。在 before-switch 回调函数中，只有返回 Resolved Promise 或是布尔类型 ture 时才会使开关组件的状态发生改变。

<template>
    <nue-div>
        <nue-checkbox
            v-model="state"
            :before-check="handleBeforeCheck"
            :label="label"
            :loading="loading"
        />
    </nue-div>
</template>

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

const state = ref(false);
const loading = ref(false);

const label = computed(() => {
    if (loading.value) {
        return '加载中...';
    }
    return state.value ? '已选中' : '未选中';
});

const handleBeforeCheck = () => {
    loading.value = true;
    return new Promise(resolve => {
        setTimeout(() => {
            loading.value = false;
            resolve(true);
        }, 2000);
    });
};
</script>

复选框组

复选框组能够统一控制和记录多个复选框的选中以及其他属性，适用于多个勾选框绑定到同一个数组的情景，通过是否勾选来表示这一组选项中选中的项。

使用标签 NueCheckboxGroup 生成复选框组，通过 v-model 绑定复选框组的值。

TIP

在复选框组中的复选框组件需要指定 name 属性用于记录当前复选框的值，否则内部将随机生成由 4 个字符组成的随机字符串作为 name 默认属性值。

<template>
    <nue-div vertical>
        <nue-checkbox-group v-model="activeNames">
            <nue-div gap="12px">
                <nue-checkbox
                    v-for="name in checkboxes"
                    :key="name"
                    :label="name"
                    :name="name"
                />
                <nue-checkbox label="未命名复选框" />
            </nue-div>
        </nue-checkbox-group>
        <nue-text size="14px">
            已选中：{{ activeNames.join(', ') || 'none' }}
        </nue-text>
    </nue-div>
</template>

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

const checkboxes = ['游戏', '音乐', '电影'];
const activeNames = ref([]);
</script>

复选框组 - 禁用状态

通过使用复选框组的 disabled 属性控制组内的复选框的禁用状态，接受 Boolean 类型，默认为 false。

<template>
    <nue-div vertical>
        <nue-checkbox-group v-model="activeNames" disabled>
            <nue-div gap="12px">
                <nue-checkbox
                    v-for="name in checkboxes"
                    :key="name"
                    :label="name"
                    :name="name"
                />
            </nue-div>
        </nue-checkbox-group>
    </nue-div>
</template>

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

const checkboxes = ['游戏', '音乐', '电影'];
const activeNames = ref([]);
</script>

复选框组 - 大小

通过使用复选框组的 size 属性控制组内复选框的大小，可选值为 small 和 large，不设置则为正常大小。

<template>
    <nue-div vertical>
        <nue-checkbox-group v-model="activeNames" size="large">
            <nue-div gap="12px">
                <nue-checkbox
                    v-for="name in checkboxes"
                    :key="name"
                    :label="name"
                    :name="name"
                />
            </nue-div>
        </nue-checkbox-group>
    </nue-div>
</template>

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

const checkboxes = ['游戏', '音乐', '电影'];
const activeNames = ref([]);
</script>

复选框组 - 控制器

通过使用复选框组的 useController 属性开启和关闭复选框组控制器，接受 Boolean 类型，默认为 false。

通过 controllerLabel 属性设置控制器标识文本。

<template>
    <nue-checkbox-group
        v-model="activeNames"
        controller-label="全选"
        use-controller
    >
        <nue-div gap="12px" style="margin-top: 12px">
            <nue-checkbox
                v-for="name in checkboxes"
                :key="name"
                :label="name"
                :name="name"
            />
        </nue-div>
    </nue-checkbox-group>
</template>

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

const checkboxes = ['游戏', '音乐', '电影', '运动', '旅行'];
const activeNames = ref<string[]>(['游戏', '音乐']);
</script>

复选框组 - 最小和最大选中数

通过使用复选框的 min 和 max 属性指定复选框组内复选框的最小和最大选中数，接受 Number 类型，默认值分别为 0 和 Infinity。

<template>
    <nue-checkbox-group
        v-model="activeNames"
        :controller-label="controllerLabel"
        :max="4"
        :min="1"
        use-controller
    >
        <nue-div gap="12px" style="margin-top: 12px">
            <nue-checkbox
                v-for="name in checkboxes"
                :key="name"
                :label="name"
                :name="name"
            />
        </nue-div>
    </nue-checkbox-group>
</template>

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

const checkboxes = ['游戏', '音乐', '电影', '运动', '旅行'];
const activeNames = ref<string[]>(['游戏', '音乐']);

const controllerLabel = computed(() => {
    return '1 < ' + activeNames.value.length + ' < 4';
});
</script>

自定义主题

通过属性 theme 设置复选框的主题样式。

<template>
    <nue-checkbox v-model="state" label="带主题的复选框" theme="custom" />
</template>

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

const state = ref(false);
</script>

<style scoped>
.nue-checkbox--custom.nue-checkbox--checked {
    --nue-check-icon-color: #448aff;
    --nue-check-label-color: #448aff;
}
</style>