uView Pro X

简体中文

English

简体中文

English

主题

Checkbox 复选框 ​

17:06

说明 ​

复选框用于多选场景。ux-checkbox-group 负责分组、用 v-model 绑定选中的 name 数组，并统一控制 shape / size / active-color / max / disabled 等；ux-checkbox 是组内单个选项，用 name（或 value）标识、label 为显示文本。ux-checkbox 也可脱离 group 独立使用，此时由自身 model-value 控制选中状态。

兼容性 ​

平台支持情况
App✅ 支持（ux-checkbox 根节点为块级 flex）
H5✅ 支持（ux-checkbox 根节点为 inline-flex）
微信小程序✅ 支持（ux-checkbox 根节点为 inline-flex）

示例 ​

基础用法 ​

使用 v-model 绑定选中的 name 数组，支持 max 限制最大选择数量。

查看源码
vue
<template>
    <ux-checkbox-group v-model="values" :max="3">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <text class="result">已选: {{ values.join(',') }}</text>
</template>

<script setup lang="uts">
type FruitItem = {
    label: string;
    value: string;
    disabled: boolean;
};

const values = ref<string[]>(['荔枝']);

const list: FruitItem[] = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

批量操作 ​

通过修改绑定值实现全选/全不选。

查看源码
vue
<template>
    <ux-checkbox-group v-model="values">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <view class="btn-row">
        <ux-button size="small" shape="round" @click="setAll(false)">全不选</ux-button>
        <ux-button size="small" shape="round" type="primary" @click="setAll(true)">全选</ux-button>
    </view>
</template>

<script setup lang="uts">
type FruitItem = {
    label: string;
    value: string;
    disabled: boolean;
};

const values = ref<string[]>([]);

const list: FruitItem[] = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

function setAll(checked: boolean): void {
    values.value = checked ? list.map((item) => item.value) : [];
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    margin-top: 10px;
}
</style>

形状 shape ​

shape="square" 为方形（3px 小圆角），shape="circle" 为圆形。

查看源码
vue
<template>
    <ux-checkbox-group v-model="values" :shape="shape">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <ux-subsection :list="shapeList" :current="shapeIndex" @change="setShape" />
</template>

<script setup lang="uts">
const values = ref<string[]>(['荔枝']);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const shape = ref<string>('square');

type ShapeOption = {
    name: string;
    value: string;
};

const shapeList: ShapeOption[] = [
    { name: 'square', value: 'square' },
    { name: 'circle', value: 'circle' }
];

const shapeIndex = computed((): number => shapeList.findIndex((item) => item.value === shape.value));

function setShape(index: number): void {
    shape.value = shapeList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

尺寸配置 size ​

支持 small / default / large 预设值和自定义数值（单位px）；传数值时图标按 size 的 0.6、label 按 0.8 自适应。

查看源码
vue
<template>
    <ux-checkbox-group v-model="values" :size="size">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <ux-subsection :list="sizeList" :current="sizeIndex" @change="setSize" />
</template>

<script setup lang="uts">
const values = ref<string[]>(['荔枝']);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const size = ref<string>('default');

type SizeOption = {
    name: string;
    value: string;
};

const sizeList: SizeOption[] = [
    { name: 'small', value: 'small' },
    { name: 'default', value: 'default' },
    { name: 'large', value: 'large' },
    { name: '60', value: '60' }
];

const sizeIndex = computed((): number => sizeList.findIndex((item) => item.value === size.value));

function setSize(index: number): void {
    size.value = sizeList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

激活颜色 active-color ​

通过 active-color 设置选中时的颜色，可覆盖 group 的颜色。

查看源码
vue
<template>
    <ux-checkbox-group v-model="values" :active-color="activeColor">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <view class="btn-row">
        <ux-button v-for="(item, index) in colorList" :key="index" size="small" shape="round" :type="activeColor === item.value ? 'primary' : 'default'" @click="activeColor = item.value">{{ item.label }}</ux-button>
    </view>
</template>

<script setup lang="uts">
const values = ref<string[]>(['荔枝']);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const activeColor = ref<string>('');

type ColorOption = {
    name: string;
    value: string;
};

const colorList: ColorOption[] = [
    { name: 'primary', value: '' },
    { name: 'error', value: '#fa3534' },
    { name: 'warning', value: '#ff9900' },
    { name: 'success', value: '#19be6b' },
    { name: 'info', value: '#909399' }
];

const colorIndex = computed((): number => colorList.findIndex((item) => item.value === activeColor.value));

function setColor(index: number): void {
    activeColor.value = colorList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

最大选择数量 max ​

通过 max 限制最多能选中的数量，超出时提示。

查看源码
vue
<template>
    <ux-checkbox-group v-model="values" :max="max">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <ux-subsection :list="maxList" :current="maxIndex" @change="setMax" />
</template>

<script setup lang="uts">
const values = ref<string[]>([]);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const max = ref<number>(2);

type MaxOption = {
    name: string;
    value: number;
};

const maxList: MaxOption[] = [
    { name: '1', value: 1 },
    { name: '2', value: 2 },
    { name: '3', value: 3 }
];

const maxIndex = computed((): number => maxList.findIndex((item) => item.value === max.value));

function setMax(index: number): void {
    max.value = maxList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

禁用 disabled ​

通过 disabled 禁用单个 checkbox，或通过 group 的 disabled 禁用全部。

查看源码
vue
<template>
    <ux-checkbox-group v-model="values">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" :disabled="item.disabled" />
    </ux-checkbox-group>
    <ux-button size="small" shape="round" :type="disabledFirst ? 'primary' : 'default'" @click="toggleDisabled">{{ disabledFirst ? '恢复第一个' : '禁用第一个' }}</ux-button>
</template>

<script setup lang="uts">
type FruitItem = {
    label: string;
    value: string;
    disabled: boolean;
};

const values = ref<string[]>(['荔枝']);

const list = ref<FruitItem[]>([
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
]);

const disabledFirst = ref<boolean>(false);

function toggleDisabled(): void {
    disabledFirst.value = !disabledFirst.value;
    list.value[0].disabled = disabledFirst.value;
}
</script>

API ​

Props ​

ux-checkbox-group ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
modelValue绑定值，选中的复选框 name 组成的数组(string | number)[]--
max最多能选中多少个 checkboxnumber999-
disabled是否禁用所有 checkboxbooleanfalse-
name在表单内提交时的标识符string | boolean''-
labelDisabled是否禁止点击文本操作 checkboxbooleanfalse-
shape形状'circle' | 'square''square'-
activeColor选中状态下的颜色string''-
size组件整体大小string | number''-
width每个 checkbox 宽度string'auto'-
wrap是否换行booleanfalse-
iconSize图标大小string | number''-

ux-checkbox ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
labelcheckbox 的标签string''-
namecheckbox 的标示符string | number''-
valuecheckbox 的值string | number''-
shape形状，square为方形，circle为圆形'circle' | 'square'--
modelValue是否为选中状态（独立使用时）booleanfalse-
disabled是否禁用boolean--
labelDisabled是否禁止点击文本操作 checkboxboolean--
activeColor选中状态下的颜色，如设置此值，将会覆盖 checkboxGroup 的 activeColor 值string--
iconSize图标大小，单位pxstring | number--
labelSizelabel 的字体大小string | number''-
size组件的整体大小string | number--

Events ​

ux-checkbox ​

事件名说明回调参数版本
change某个checkbox状态发生变化时触发，回调为一个对象value: boolean-

Slots ​

ux-checkbox-group ​

插槽名说明版本
default放置 ux-checkbox 子组件-

ux-checkbox ​

插槽名说明版本
default自定义 label 内容（默认显示 label 文本）-

注意事项 ​

  • ux-checkbox 需放在 ux-checkbox-group 内才会被分组管理、参与选中联动；脱离 group 时由自身 model-value 控制，change 回调为布尔值。
  • 选中值由 group 的 v-model 维护，ux-checkbox 用 name（优先 value）匹配选中项，二者类型需与绑定值一致。
  • 超过 group 的 max 时不再加入并弹出「超过最大选择数量: N」提示（max 为 0 时不限制）。
  • ux-checkbox 的 disabled、label-disabled、size、icon-size、active-color 会覆盖 group 上的同名配置。
  • ux-checkbox 的 size 能解析出尺寸档（含数值档）时，label-size 不生效，字号取该档内的值（数值档下图标按 0.6、label 按 0.8 比例推导，并各自 clamp）。
  • label-disabled 为 true 时点击文本不触发选中，仅点击图标可切换。
  • App 端 ux-checkbox 根节点为块级 flex，H5 / 微信小程序为 inline-flex，同一行并排的独立 checkbox 换行表现可能不同。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5