NueUI

Appearance

Checkbox 复选框 ​

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

提示

NueCheckbox 组件在设计上没有使用到 HTML 的 Input 元素。

基础用法 ​

使用标签 <NueCheckbox> 声明一个复选框组件。

值和标识文字 ​

通过 v-model 绑定复选框的值；通过属性 label 或默认插槽 #default 设置复选框的标识文本。

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

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

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

禁用状态 ​

通过属性 disabled 禁用复选框。

<template>
    <nue-div>
        <nue-checkbox v-model="state1" disabled label="禁用状态（未选）" />
        <nue-checkbox v-model="state2" disabled label="禁用状态（已选）" />
    </nue-div>
</template>

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

const state1 = ref(false);
const state2 = ref(true);
</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 设置复选框为中间状态。

TIP

  • 属性 indeterminate 表示有选择项但不是全选的中间状态，通常会在控制整体选项组的复选框上应用。
  • 属性 indeterminate 的显示优先级会低于选中值为 true 、高于选中值为 false 的情况。

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

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

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

扩展插槽 1.8.53 以上版本 ​

通过插槽 #prefix 和 #suffix 分别可以在复选框图标前方和后方插入自定义元素。

<template>
    <nue-div align="center" gap="var(--nue-gap-md)">
        <nue-checkbox label="前缀">
            <template #prefix>
                <nue-icon name="user" />
            </template>
        </nue-checkbox>
        <nue-checkbox label="后缀">
            <template #suffix>
                <nue-icon name="theme" />
            </template>
        </nue-checkbox>
    </nue-div>
</template>

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

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

<template>
    <nue-checkbox
        v-model="state"
        :before-check="handleBeforeCheck"
        :label="label"
        :loading="loading"
    />
</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> 声明一个复选框组。

建议为每个 <NueCheckbox> 复选框组件指定 name 属性，通过 v-model 在 <NueCheckboxGroup> 上绑定一个复选框组的响应式值，该值将会记录下所有已选择的 <NueCheckbox> 复选框组件的 name 属性值。

TIP

若 <NueCheckbox> 复选框组件没有指定 name 属性值，则内部将随机生成由 4 个字符组成的随机字符串作为 name 默认属性值。

<template>
    <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>已选中：{{ activeNames.join(', ') || 'none' }}</nue-text>
</template>

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

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

禁用状态 ​

通过属性 disabled 控制组内 <NueCheckbox> 复选框组件的禁用状态。

<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 控制组内 <NueCheckbox> 复选框组件的大小，可选值与 <NueCheckbox> 复选框组件的属性 size 相同。

<template>
    <nue-div vertical>
        <nue-checkbox-group v-model="activeNames" size="small">
            <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 开启复选框组的预设选择控制器。通过属性 controllerLabel 设置控制器标识文本。

<template>
    <nue-checkbox-group v-model="activeNames" controller-label="全选" use-controller>
        <nue-div gap="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 指定复选框组内 <NueCheckbox> 复选框组件的最小和最大选中数。属性接受 Number 类型，默认值分别为 min=0 和 max=Infinity。

<template>
    <nue-checkbox-group
        v-model="activeNames"
        :controller-label="controllerLabel"
        :max="3"
        :min="1"
        use-controller
    >
        <nue-div gap="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 `已选择 ${activeNames.value.length} 项，总共可选 3 项`;
});
</script>

注意事项 ​

  1. HTML 实现：组件没有使用原生 <input type="checkbox"> 元素，而是自定义实现的选中状态样式。
  2. 中间状态：indeterminate 状态的优先级高于选中状态，高于未选中状态。
  3. 异步验证：beforeCheck 回调支持返回 Promise，可用于处理异步验证逻辑。
  4. CheckboxGroup：使用 NueCheckboxGroup 时，通过 v-model 绑定的数组会记录所有选中项的 name 值。

组件属性与事件 ​

下方涵盖了 NueCheckbox 组件所有的可用属性与事件。

NueCheckbox 属性 ​

属性Type默认值说明
modelValueboolean-绑定值
labelstring-标签文本
namestring-名称（用于CheckboxGroup记录）
size'small' | 'large'-尺寸
disabledbooleanfalse是否禁用
loadingbooleanfalse加载状态
indeterminatebooleanfalse中间状态（部分选中）
beforeCheck(state: boolean) => boolean | Promise<boolean>-选择前回调，返回 false 可阻止选择
themestring | string[] | Record<string, boolean>-主题样式（继承自 GlobalProps）

NueCheckbox 事件 ​

事件参数说明
update:modelValuevalue: boolean值更新事件
changevalue: boolean状态变化事件
checked-选中事件
unchecked-取消选中事件

NueCheckboxGroup 属性 ​

属性Type默认值说明
modelValuestring[]-选中项的 name 数组
size'small' | 'large'-组内复选框尺寸
disabledbooleanfalse是否禁用
namestring-名称（用于组内复选框记录）
useControllerbooleanfalse是否启用全选控制器
controllerLabelstring-全选控制器标签文字
minnumber0最少选中数量
maxnumberInfinity最多选中数量
themestring | string[] | Record<string, boolean>-主题样式（继承自 GlobalProps）

NueCheckboxGroup 事件 ​

事件参数说明
update:modelValuevalue: string[]值更新事件

Released under the MIT License.

Copyright © 2026-present Nathan Lee