Checkbox 复选框

介绍

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

代码演示

基础用法

通过 v-model 绑定复选框的勾选状态。

<z-checkbox v-model="checked">复选框</z-checkbox>
import { ref } from 'vue'
const checked = ref(true)

禁用状态

通过设置 disabled 属性可以禁用复选框。

<z-checkbox v-model="checked" disabled>复选框</z-checkbox>

自定义形状

shape 属性设置为 square,复选框的形状会变成方形。

<z-checkbox-group v-model="checked" shape="square">
  <z-checkbox name="a">复选框 a</z-checkbox>
  <z-checkbox name="b">复选框 b</z-checkbox>
</z-checkbox-group>
import { ref } from 'vue';
const checked = ref(['a', 'b']);

自定义颜色

通过 checked-color 属性设置选中状态的图标颜色。

<z-checkbox v-model="checked" checked-color="#ee0a24">复选框</z-checkbox>

自定义大小

通过 icon-size 属性可以自定义图标的大小。

<z-checkbox v-model="checked" icon-size="48rpx">复选框</z-checkbox>

自定义图标

通过 icon 插槽自定义图标,可以通过 slotProps 判断是否为选中状态.

<z-checkbox v-model="checked">
  自定义图标
  <template #icon>
    <image
      class="img-icon"
      :src="checked ? activeIcon : inactiveIcon"
    />
  </template>
</z-checkbox>

<style>
  .img-icon {
    width: 40rpx;
    height: 40rpx;
  }
</style>
import { ref } from 'vue';
const activeIcon =
  'https://cdn.zebraui.com/zebra-ui/images/assets/demo-select.png'
const inactiveIcon =
  'https://cdn.zebraui.com/zebra-ui/images/assets/demo-noselect.png'

左侧文本

label-position 属性设置为 'left',可以将文本位置调整到复选框左侧。

<z-checkbox v-model="checked" label-position="left">复选框</z-checkbox>

禁用文本点击

设置 label-disabled 属性后,点击图标以外的内容不会触发复选框切换。

<z-checkbox v-model="checked" label-disabled>复选框</z-checkbox>

复选框组

复选框可以与复选框组一起使用,复选框组通过 v-model 数组绑定复选框的勾选状态。

<z-checkbox-group v-model="checked">
  <z-checkbox name="a">复选框 a</z-checkbox>
  <z-checkbox name="b">复选框 b</z-checkbox>
</z-checkbox-group>

水平排列

direction 属性设置为 horizontal 后,复选框组会变成水平排列。

<z-checkbox-group v-model="checked" direction="horizontal">
  <z-checkbox name="a">复选框 a</z-checkbox>
  <z-checkbox name="b">复选框 b</z-checkbox>
</z-checkbox-group>

限制最大可选数

通过 max 属性可以限制复选框组的最大可选数。

<z-checkbox-group v-model="checked" :max="2">
  <z-checkbox name="a">复选框 a</z-checkbox>
  <z-checkbox name="b">复选框 b</z-checkbox>
  <z-checkbox name="c">复选框 c</z-checkbox>
</z-checkbox-group>

全选与反选

通过 CheckboxGroup 实例上的 toggleAll 方法可以实现全选与反选。

<z-checkbox-group v-model="checked" ref="checkboxGroup">
  <z-checkbox name="a">复选框 a</z-checkbox>
  <z-checkbox name="b">复选框 b</z-checkbox>
  <z-checkbox name="c">复选框 c</z-checkbox>
</z-checkbox-group>

<z-button type="primary" @click="checkAll">全选</z-button>
<z-button type="primary" @click="toggleAll">反选</z-button>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref([]);
    const checkboxGroup = ref(null);
    const checkAll = () => {
      checkboxGroup.value.toggleAll(true);
    }
    const toggleAll = () => {
      checkboxGroup.value.toggleAll();
    },

    return {
      checked,
      checkAll,
      toggleAll,
      checkboxGroup,
    };
  },
};

搭配单元格组件使用

搭配单元格组件使用时,需要再引入 CellCellGroup 组件,并通过 Checkbox 实例上的 toggle 方法触发切换。

<z-checkbox-group v-model="checked">
  <z-cell-group inset>
    <z-cell
      v-for="(item, index) in list"
      clickable
      :key="item"
      :title="`复选框 ${item}`"
      @click="toggle(index)"
    >
      <template #right-icon>
        <z-checkbox
          :name="item"
          :ref="el => checkboxRefs[index] = el"
          @click.stop
        />
      </template>
    </z-cell>
  </z-cell-group>
</z-checkbox-group>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref([]);
    const checkboxRefs = ref([]);
    const toggle = (index) => {
      checkboxRefs.value[index].toggle();
    };
    return {
      list: ['a', 'b'],
      toggle,
      checked,
      checkboxRefs,
    };
  },
};

不确定状态

通过 indeterminate 设置复选框是否为不确定状态。

<z-checkbox
  v-model="isCheckAll"
  :indeterminate="isIndeterminate"
  @change="checkAllChange"
>
  全选
</z-checkbox>

<z-checkbox-group v-model="checkedResult" @change="checkedResultChange">
  <z-checkbox v-for="item in list" :key="item" :name="item">
    复选框 {{ item }}
  </z-checkbox>
</z-checkbox-group>
import { ref } from 'vue';

export default {
  setup() {
    const list = ['a', 'b', 'c', 'd']

    const isCheckAll = ref(false);
    const checkedResult = ref(['a', 'b', 'd']);
    const isIndeterminate = ref(true);

    const checkAllChange = (val: boolean) => {
      checkedResult.value = val ? list : []
      isIndeterminate.value = false
    }

    const checkedResultChange = (value: string[]) => {
      const checkedCount = value.length
      isCheckAll.value = checkedCount === list.length
      isIndeterminate.value = checkedCount > 0 && checkedCount < list.length
    }

    return {
      list,
      isCheckAll,
      checkedResult,
      checkAllChange,
      isIndeterminate,
      checkedResultChange
    };
  },
};

API

Checkbox Props

参数说明类型默认值
v-model是否为选中状态booleanfalse
name标识符,通常为一个唯一的字符串或数字any-
shape形状,可选值为 squarestringround
disabled是否禁用复选框booleanfalse
label-disabled是否禁用复选框文本点击booleanfalse
label-position文本位置,可选值为 leftstringright
icon-size图标大小,默认单位为 pxnumber | string20px
checked-color选中状态颜色string#1989fa
bind-group是否与复选框组绑定booleantrue
indeterminate是否为不确定状态booleanfalse

CheckboxGroup Props

参数说明类型默认值
v-model所有选中项的标识符any-
disabled是否禁用所有复选框booleanfalse
max最大可选数,0 为无限制number | string0
direction排列方向,可选值为 horizontalstringvertical
icon-size所有复选框的图标大小,默认单位为 pxnumber | string20px
checked-color所有复选框的选中状态颜色string#1989fa
shape形状,可选值为 squarestringround

Checkbox Events

事件名说明回调参数
change当绑定值变化时触发的事件checked: boolean
click点击复选框时触发event: MouseEvent

CheckboxGroup Events

事件名说明回调参数
change当绑定值变化时触发的事件names: any

Checkbox Slots

名称说明参数
default自定义文本{ checked: boolean, disabled: boolean }
icon自定义图标{ checked: boolean, disabled: boolean }

CheckboxGroup 方法

通过 ref 可以获取到 CheckboxGroup 实例并调用实例方法。

方法名说明参数返回值
toggleAll切换所有复选框,传 true 为选中,false 为取消选中,不传参为取反options?: boolean | object-

toggleAll 方法示例

import { ref } from 'vue';

const checkboxGroupRef = ref();

// 全部反选
checkboxGroupRef?.value.toggleAll();
// 全部选中
checkboxGroupRef?.value.toggleAll(true);
// 全部取消
checkboxGroupRef?.value.toggleAll(false);

// 全部反选,并跳过禁用的复选框
checkboxGroupRef?.value.toggleAll({
  skipDisabled: true,
});
// 全部选中,并跳过禁用的复选框
checkboxGroupRef?.value.toggleAll({
  checked: true,
  skipDisabled: true,
});

Checkbox 方法

通过 ref 可以获取到 Checkbox 实例并调用实例方法。

方法名说明参数返回值
toggle切换选中状态,传 true 为选中,false 为取消选中,不传参为取反checked?: boolean-

主题定制

样式变量

组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件

名称默认值描述
--z-checkbox-size40rpx-
--z-checkbox-border-colorvar(--z-gray-5)-
--z-checkbox-durationvar(--z-duration-fast)-
--z-checkbox-label-marginvar(--z-padding-xs)-
--z-checkbox-label-colorvar(--z-text-color)-
--z-checkbox-checked-icon-colorvar(--z-primary-color)-
--z-checkbox-disabled-icon-colorvar(--z-gray-5)-
--z-checkbox-disabled-label-colorvar(--z-text-color-3)-
--z-checkbox-disabled-backgroundvar(--z-border-color)-