X-Next

Appearance

Checkbox 复选框 ​

用于多选或开关式勾选，适合权限配置、批量选择、偏好设置等场景。

何时使用 ​

  • 需要在一组互不排斥的选项中选择多个值。
  • 需要展示全选、半选、最多可选等状态。
  • 需要以单个布尔值表达是否启用某项配置。

基础用法 ​

未同意
vue
<template>
  <x-checkbox v-model="checked">同意协议</x-checkbox>
</template>

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

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

禁用状态 ​

vue
<template>
  <x-checkbox disabled>禁用未选</x-checkbox>
  <x-checkbox v-model="checked" disabled>禁用已选</x-checkbox>
</template>

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

const checked = ref(true);
</script>

半选状态 ​

vue
<template>
  <x-checkbox v-model="checkAll" :indeterminate="isIndeterminate">全选权限</x-checkbox>
  <x-checkbox-group v-model="values" :options="options" />
</template>

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

const values = ref(['read']);
const permissions = ['read', 'write', 'publish'];
const options = [
  { label: '读取', value: 'read' },
  { label: '写入', value: 'write' },
  { label: '发布', value: 'publish' },
];
const checkAll = computed({
  get: () => permissions.every((value) => values.value.includes(value)),
  set: (checked: boolean) => {
    values.value = checked ? [...permissions] : [];
  },
});
const isIndeterminate = computed(
  () => values.value.length > 0 && values.value.length < permissions.length,
);
</script>

复选框组 ​

vue
<template>
  <x-checkbox-group v-model="values" :options="options" />
</template>

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

const values = ref(['read']);
const options = [
  { label: '读取', value: 'read' },
  { label: '写入', value: 'write' },
  { label: '发布', value: 'publish' },
];
</script>

纵向排列 ​

vue
<template>
  <x-checkbox-group v-model="values" direction="vertical" :options="options" />
</template>

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

const values = ref(['email']);
const options = [
  { label: '邮件', value: 'email' },
  { label: '短信', value: 'sms', disabled: true },
  { label: '站内信', value: 'notice' },
];
</script>

最多可选 ​

vue
<template>
  <x-checkbox-group v-model="values" :options="options" :max="2" />
</template>

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

const values = ref(['read']);
const options = [
  { label: '读取', value: 'read' },
  { label: '写入', value: 'write' },
  { label: '发布', value: 'publish' },
  { label: '删除', value: 'delete' },
];
</script>

自定义文案 ​

vue
<template>
  <x-checkbox-group v-model="values" :options="options">
    <template #label="{ data }">
      <span>{{ data.label }}模块</span>
    </template>
  </x-checkbox-group>
</template>

自定义复选框图形 ​

vue
<template>
  <x-checkbox-group v-model="values" :options="options">
    <template #checkbox="{ checked, disabled }">
      <span :class="{ 'is-checked': checked, 'is-disabled': disabled }">
        {{ checked ? '✓' : '' }}
      </span>
    </template>
  </x-checkbox-group>
</template>

布尔值选项 ​

vue
<template>
  <x-checkbox-group v-model="values" :options="options" />
</template>

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

const values = ref([true]);
const options = [
  { label: '启用', value: true },
  { label: '停用', value: false },
];
</script>

事件 ​

vue
<template>
  <x-checkbox-group v-model="values" :options="options" @change="handleChange" />
</template>

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

const values = ref(['read']);
const handleChange = (value: Array<string | number | boolean>) => {
  console.log(value);
};
</script>

按需导入 ​

ts
import { Checkbox, CheckboxGroup } from 'x-next';

Checkbox Props ​

参数说明类型默认值
modelValue绑定值boolean | CheckboxValue[]undefined
defaultChecked默认是否选中，非受控模式booleanfalse
value选项值，在 CheckboxGroup 中使用CheckboxValuetrue
disabled是否禁用booleanfalse
indeterminate是否为半选状态booleanfalse

Checkbox Events ​

事件名说明回调参数
update:modelValue值更新时触发value: boolean | CheckboxValue[]
change值变化时触发value: boolean | CheckboxValue[], event: Event

Checkbox Slots ​

插槽名说明参数
default复选框文案-
checkbox自定义复选框图形{ checked, disabled }

CheckboxGroup Props ​

参数说明类型默认值
modelValue绑定值CheckboxValue[]undefined
defaultValue默认值，非受控模式CheckboxValue[][]
max最多可选数量number-
options选项数据Array<CheckboxValue | CheckboxOption>-
direction排列方向'horizontal' | 'vertical''horizontal'
disabled是否禁用booleanfalse

CheckboxGroup Events ​

事件名说明回调参数
update:modelValue值更新时触发value: CheckboxValue[]
change值变化时触发value: CheckboxValue[], event: Event

CheckboxGroup Slots ​

插槽名说明参数
default自定义复选框列表-
label自定义 options 文案{ data }
checkbox自定义复选框图形{ checked, disabled }

类型 ​

ts
type CheckboxValue = string | number | boolean;

interface CheckboxOption {
  label?: string | (() => VNode);
  value: CheckboxValue;
  disabled?: boolean;
  indeterminate?: boolean;
}