PIUI 高质量开源组件库

# Checkbox 复选框

表单组件-多选框。主要用于一组可选项多项选择，或者单独用于标记切换某种状态。

# 平台差异说明

App H5 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序
√ √ √ √ √ √ √

# 示例

# 基础用法

可通过v-model | value：设定是否选中

<template>
  <pi-checkbox v-model="base">复选框</pi-checkbox>
</template>

<script>
export default {
  data() {
    return {
      base: true
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13

# 搭配checkbox-group使用推荐使用

推荐通过搭配checkbox-group使用，可快速设置一组选中值，更方便对多选场景进行数据初始化

提示

  1. 每项checkbox需要设置name属性
  2. checkbox-group设置的value应该是一个数组，包含的name的checkbox将会被选中
<template>
  <pi-checkbox-group v-model="checkboxGroup">
    <pi-checkbox name="A">选项一</pi-checkbox>
    <pi-checkbox name="B">选项二</pi-checkbox>
    <pi-checkbox name="C">选项三</pi-checkbox>
  </pi-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      checkboxGroup: ['A', 'C'], // 搭配checkbox-group使用
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 自定义颜色

可自定义激活颜色，设置 active-color 属性指定激活颜色

<template>
  <pi-checkbox-group v-model="customColor" direction="vertical" active-color="#ff6a00">
    <pi-checkbox name="square" shape="square" active-color="#ff6a00">
      方形（默认）
    </pi-checkbox>
    <pi-checkbox
      name="square-fill"
      shape="square"
      active-color="#ff6a00"
      active-mode="fill"
    >
      方形（填充）
    </pi-checkbox>
    <pi-checkbox name="round" shape="round" active-color="#ff6a00">
      圆形
    </pi-checkbox>
    <pi-checkbox name="round-fill" shape="round" active-mode="fill" active-color="#ff6a00">
      圆形（填充）
    </pi-checkbox>
    <pi-checkbox name="dot" shape="dot" active-color="#ff6a00">
      圆点
    </pi-checkbox>
    <pi-checkbox name="dot-fill" shape="dot" active-color="#ff6a00" active-mode="fill">
      圆点（填充）
    </pi-checkbox>
    <pi-checkbox name="text" shape="text" active-color="#ff6a00">文字</pi-checkbox>
    <pi-checkbox name="text-fill" shape="text" active-color="#ff6a00" active-mode="fill">
      文字（填充）
    </pi-checkbox>
  </pi-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      customColor: [
        // 自定义颜色
        'square',
        'round',
        'dot',
        'text',
        'square-fill',
        'round-fill',
        'dot-fill',
        'text-fill'
      ],
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# 自定义形状

可自定义复选框的形状，设置 shape 属性指定形状，有以下形状可供选择：

  1. square: 方形（默认）
  2. round: 圆形
  3. dot: 圆点
  4. text: 文字
<template>
  <pi-checkbox-group v-model="customShape" direction="vertical">
    <pi-checkbox name="square" shape="square">方形（默认）</pi-checkbox>
    <pi-checkbox name="round" shape="round">圆形</pi-checkbox>
    <pi-checkbox name="dot" shape="dot">圆点</pi-checkbox>
    <pi-checkbox name="text" shape="text">文字</pi-checkbox>
  </pi-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      customShape: ['square', 'round', 'dot', 'text'], // 自定义形状
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 填充模式

可自定义复选框的填充模式，设置 active-mode 属性指定形状，有以下填充模式可供选择：

  1. line: 线框（默认）
  2. line-circle: 线环：中间打钩和圆点不显示
  3. fill: 填充
  4. fill-circle: 填充环：中间打钩和圆点不显示
<template>
  <pi-checkbox-group v-model="customFill" direction="vertical">
    <pi-checkbox name="square" shape="square" active-mode="line">
      方形
    </pi-checkbox>
    <pi-checkbox name="square-circle" shape="square" active-mode="line-circle">
      方形（线环）
    </pi-checkbox>
    <pi-checkbox name="square-fill-circle" shape="square" active-mode="fill-circle">
      方形（填充环）
    </pi-checkbox>
    <pi-checkbox name="round" shape="round" active-mode="line">
      圆形
    </pi-checkbox>
    <pi-checkbox name="round-circle" shape="round" active-mode="line-circle">
      圆形（线环）
    </pi-checkbox>
    <pi-checkbox name="round-fill-circle" shape="round" active-mode="fill-circle">
      圆形（填充环）
    </pi-checkbox>
    <pi-checkbox name="dot" shape="dot" active-mode="fill">圆点</pi-checkbox>
    <pi-checkbox name="dot-circle" shape="dot" active-mode="line-circle">
      圆点（线环）
    </pi-checkbox>
    <pi-checkbox name="dot-fill-circle" shape="dot" active-mode="fill-circle">
      圆点（填充环）
    </pi-checkbox>
  </pi-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
        customFill: ['square', 'round', 'dot', 'text'], // 填充模式
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# 禁用

如果需要禁止用户勾选，可设置 disabled 禁用复选框

注意

disabled 只是禁止用户选择，仍然可以通过value设置其选中

<template>
  <pi-checkbox-group v-model="customShapeDisabled" direction="vertical">
    <pi-checkbox name="square" shape="square" disabled>方形（默认）</pi-checkbox>
    <pi-checkbox name="round" shape="round" disabled>圆形</pi-checkbox>
    <pi-checkbox name="dot" shape="dot" disabled>圆点</pi-checkbox>
    <pi-checkbox name="text" shape="text" disabled>文字</pi-checkbox>
  </pi-checkbox-group>
  <pi-checkbox-group v-model="customFillDisabled" direction="vertical">
    <pi-checkbox name="square" shape="square" active-mode="fill" disabled>
      方形（默认）
    </pi-checkbox>
    <pi-checkbox name="round" shape="round" active-mode="fill" disabled>圆形</pi-checkbox>
    <pi-checkbox name="dot" shape="dot" active-mode="fill" disabled>圆点</pi-checkbox>
    <pi-checkbox name="text" shape="text" active-mode="fill" disabled>文字</pi-checkbox>
  </pi-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      customShapeDisabled: ['dot', 'text'], // 自定义形状（禁用）
      customFillDisabled: ['dot', 'text'], // 填充模式（禁用）
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 最多选择数量

如果需要限制用户勾选的数量，可设置 max 设置最大可选数量

<template>
  <pi-checkbox-group v-model="max2" max="2">
    <pi-checkbox name="A">
      选项一
    </pi-checkbox>
    <pi-checkbox name="B">
      选项二
    </pi-checkbox>
    <pi-checkbox name="C">
      选项三
    </pi-checkbox>
  </pi-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      max2: ['A', 'B'], // 最多选择2项
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 全选与反选

checkbox-group提供了toggleSelect方法可实现全选与反选，可以通过this.$refs.checkboxGroup.toggleSelect调用

<template>
  <pi-card>
    <pi-section slot="title" padding="0" title="全选与反选" />
    <template slot="body">
      <pi-checkbox-group
        ref="checkboxGroup"
        v-model="toggleSelected"
        direction="vertical"
        active-mode="fill"
      >
        <pi-checkbox name="A">
          选项一
        </pi-checkbox>
        <pi-checkbox name="B">
          选项二
        </pi-checkbox>
        <pi-checkbox name="C">
          选项三
        </pi-checkbox>
        <pi-checkbox name="D">
          选项三
        </pi-checkbox>
      </pi-checkbox-group>
    </template>
    <template slot="footer">
      <pi-button
        :custom-style="{ marginRight: '24rpx' }"
        size="small"
        type="primary"
        @click="handleSelectAll"
      >
        全选
      </pi-button>
      <pi-button size="small" type="secondary" @click="handleUnSelectAll">
        反选
      </pi-button>
    </template>
  </pi-card>
</template>

<script>
export default {
  data() {
    return {
      toggleSelected: ['A', 'C', 'D'] // 全选与反选
    },
    methods: {
      handleSelectAll() {
        this.$refs.checkboxGroup.toggleSelect(true)
      },
      handleUnSelectAll() {
        this.$refs.checkboxGroup.toggleSelect(false)
      }
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

# API

# Checkbox Props

参数 说明 类型 必选 默认值
v-model(value) 是否为选中状态 Boolean false -
customStyle 自定义样式，对象形式 Object false -
customClass 自定义样式类，字符串形式 String false -
name checkbox组件的标示符 String | Number false -
shape 形状 'square' 'round' 'dot' 'text' false round
borderRadius 当shape为square的时候，设置圆角，单位rpx String | Number false 8
border 边框大小，单位rpx String | Number false 2
disabled 是否禁用复选框 Boolean false false
readonly 是否只读模式 Boolean false false
size checkbox大小，单位rpx String | Number false 40
iconSize checkbox icon 大小，单位rpx String | Number false 24
activeColor 选中时图标的颜色 String false -
activeMode 激活模式 'line'-线框模式 'line-circle' - 线环 'fill'-实底 'fill-circle 填充环' false line

# Checkbox Slots

名称 描述 插槽内容
default checkbox 默认插槽 -

# Checkbox Events

事件名 描述 参数
change 勾选状态发生变化 true|false

# CheckboxGroup Props

注意

CheckboxGroup与Checkbox同名的属性，相当于整体设置，会覆盖Checkbox的属性

名称 描述 类型 必选 默认值
value 初始值 — false -
customStyle 自定义样式，对象形式 Object false {}
customClass 自定义样式类 String false ''
max 最大可选数，0为无限制 String | Number false 0
direction 排列方向 '' 'horizontal' 'vertical' false ''
shape 形状 'round' 'square' 'dot' 'text' false ''
border 边框大小，单位rpx String | Number false 0
disabled 是否禁用复选框 Boolean false false
size checkbox大小，单位rpx String | Number false 0
iconSize checkbox icon 大小，单位rpx String | Number false 0
activeColor 选中时图标的颜色 String false ''
activeMode 激活模式 '' 'line' 'fill' false ''

# CheckboxGroup Slots

名称 描述 插槽内容
default CheckboxGroup 默认插槽 -

# CheckboxGroup Events

事件名 描述 参数
change 包含的Checkbox发生变化 当前选中的Checkbox name集合
Last updated: 2021/11/20 上午11:18:39

← Switch 开关 →

10:44