介绍
用于在选中和非选中状态之间进行切换。
引入
代码演示
基础用法
通过 `v-model` 绑定复选框的勾选状态。
禁用状态
通过设置 `disabled` 属性可以禁用复选框。
自定义形状
将 `shape` 属性设置为 `square`,复选框的形状会变成方形。
自定义颜色
通过 `checked-color` 属性设置选中状态的图标颜色。
自定义大小
通过 `icon-size` 属性可以自定义图标的大小。
自定义图标
通过 `icon` 插槽自定义图标,可以通过 `slotProps` 判断是否为选中状态.
禁用文本点击
设置 `label-disabled` 属性后,点击图标以外的内容不会触发复选框切换。
复选框组
复选框可以与复选框组一起使用,复选框组通过 `v-model` 数组绑定复选框的勾选状态。
水平排列
将 `direction` 属性设置为 `horizontal` 后,复选框组会变成水平排列。
限制最大可选数
通过 `max` 属性可以限制复选框组的最大可选数。
全选与反选
通过 `CheckboxGroup` 实例上的 `toggleAll` 方法可以实现全选与反选。
搭配单元格组件使用
此时你需要再引入 `Cell` 和 `CellGroup` 组件,并通过 `Checkbox` 实例上的 toggle 方法触发切换。
API
Checkbox Props
参数 | 说明 | 类型 | 默认值 | |
---|---|---|---|---|
v-model (value) | 是否为选中状态 | boolean | false | |
name | 标识符 | any | - | |
shape | 形状,可选值为 square | string | round | |
disabled | 是否禁用复选框 | boolean | false | |
label-disabled | 是否禁用复选框文本点击 | boolean | false | |
label-position | 文本位置,可选值为 left | string | right | |
icon-size | 图标大小,默认单位为 px | number 、 string | 20px | |
checked-color | 选中状态颜色 | string | #1989fa | |
bind-group | 是否与复选框组绑定 | boolean | true |
CheckboxGroup Props
参数 | 说明 | 类型 | 默认值 | |
---|---|---|---|---|
v-model (value) | 所有选中项的标识符 | any[] | - | |
disabled | 是否禁用所有复选框 | boolean | false | |
max | 最大可选数,0 为无限制 | number 、 string | 0 | |
direction v2.5.0 | 排列方向,可选值为 horizontal | string | vertical | |
icon-size | 所有复选框的图标大小,默认单位为 px | number 、 string | 20px | |
checked-color | 所有复选框的选中状态颜色 | string | #1989fa |
Checkbox Events
事件名 | 说明 | 回调参数 | |
---|---|---|---|
change | 当绑定值变化时触发的事件 | checked: boolean | |
click | 点击复选框时触发 | event: Event |
CheckboxGroup Events
事件名 | 说明 | 回调参数 | |
---|---|---|---|
change | 当绑定值变化时触发的事件 | names: any[] |
Checkbox Slots
名称 | 说明 | 参数 | |
---|---|---|---|
default | 自定义文本 | - | |
icon | 自定义图标 | checked: boolean |
CheckboxGroup 方法
通过 ref 可以获取到 CheckboxGroup 实例并调用实例方法,详见
。
方法名 | 说明 | 参数 | 返回值 | |
---|---|---|---|---|
toggleAll | 切换所有复选框,传 true 为选中,false 为取消选中,不传参为取反 | options?: boolean 、 object | - |
toggleAll 方法示例
Checkbox 方法
通过 ref 可以获取到 Checkbox 实例并调用实例方法,详见
。
方法名 | 说明 | 参数 | 返回值 | |
---|---|---|---|---|
toggle | 切换选中状态,传 true 为选中,false 为取消选中,不传参为取反 | checked?: boolean | - |
样式变量
组件提供了下列 Less 变量,可用于自定义样式,使用方法请参考
。
名称 | 默认值 | 描述 | |
---|---|---|---|
@checkbox-size | 20px | - | |
@checkbox-border-color | @gray-5 | - | |
@checkbox-transition-duration | @animation-duration-fast | - | |
@checkbox-label-margin | @padding-xs | - | |
@checkbox-label-color | @text-color | - | |
@checkbox-checked-icon-color | @blue | - | |
@checkbox-disabled-icon-color | @gray-5 | - | |
@checkbox-disabled-label-color | @gray-5 | - | |
@checkbox-disabled-background-color | @border-color | - |