Checkbox 多选框
在一组备选项中进行多选。
WARNING
label 作为 value 来使用已经被 废弃, label 只用来表示展示的文字
基础用法(勾选框形态)
单独使用可以表示两种状态之间的切换,写在标签中的内容为 checkbox 后的介绍。
通过 v-model 绑定 Boolean 变量,选中时值为 true。支持 size 设置尺寸、disabled 禁用、border 渲染带边框样式。w-checkbox 标签中的内容(或 label 属性)将成为复选框后的描述。
配置式选项 1.3.4
除了手写 w-checkbox 子组件,还可以通过 options 属性以数据驱动的方式配置选项,适合选项来自接口数据的场景。
options 中每项支持 label(展示文字)、value(选中值)、disabled(禁用)字段,也支持透传 w-checkbox 的其它属性(如 border)。通过 type="button" 将选项渲染为按钮形态;当数据字段名不同时,可通过 props 自定义 label / value / disabled 对应的字段名。
多选框组
适用于多个勾选框绑定到同一个数组的情景,通过是否勾选来表示这一组选项中选中的项。
在 w-checkbox-group 中使用 v-model 绑定 Array 类型的变量即可。在 w-checkbox 组件中,value 是选择框的值,与数组中的元素值相对应:如果指定的值存在于数组中,就处于选中状态,反之亦然。如果该组件下没有被传入内容,那么 label 将会作为 checkbox 后的介绍。
按钮样式
按钮样式的多选组合。round 圆角按钮组;discrete 离散按钮组(按钮不相连);plain 轻量级按钮组。属性可组合使用。
只需要把 w-checkbox 元素替换为 w-checkbox-button 元素即可。 此外,WinDesign Next 还提供了size属性。
长文本省略
多语言场景下,选项文本可能较长。当多选框所在容器宽度受限(如固定宽度的分组、栅格列)时,选项保持单行显示,超出部分以省略号截断,鼠标悬浮在选项文字上可通过原生 title 查看完整内容。
按钮组排列方向
direction="vertical" 纵向排列,默认 horizontal 横向排列。
Checkbox API
Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 选中项绑定值 | string / number / boolean | — |
| value | 选中状态的值(只有在checkbox-group或者绑定对象类型为array时有效) | string / number / boolean / object | — |
| label | 选中状态的值,只有在绑定对象类型为 array 时有效。 如果没有 value, label则作为value使用 | string / number / boolean / object | — |
| true-value | 选中时的值 | string / number | — |
| false-value | 没有选中时的值 | string / number | — |
| disabled | 是否禁用 | boolean | false |
| border | 是否显示边框 | boolean | false |
| size | Checkbox 的尺寸 | enum | — |
| name | 原生 name 属性 | string | — |
| checked | 当前是否勾选 | boolean | false |
| indeterminate | 设置不确定状态,仅负责样式控制 | boolean | false |
| validate-event | 输入时是否触发表单的校验 | boolean | true |
| tight 1.3.4 | 是否开启紧凑版(左右间距均为 8px) | boolean | false |
| tabindex | 输入框的 tabindex | string / number | — |
| id | input id | string | — |
| aria-controls a11y | 与 aria-control一致, 当 indeterminate为 true时生效 | string | — |
| aria-label a11y | 原生 aria-label 属性 | string | — |
| true-label deprecated | 选中时的值 | string / number | — |
| false-label deprecated | 没有选中时的值 | string / number | — |
| controls a11y deprecated | 和 aria-control一致。当 indeterminate 为 true 时生效 | string | — |
Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | Function |
Slots
| 插槽名 | 说明 |
|---|---|
| default | 自定义默认内容 |
CheckboxGroup API
Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | object | [] |
| size | 多选框组尺寸 | enum | — |
| disabled | 是否禁用 | boolean | false |
| min | 可被勾选的 checkbox 的最小数量 | number | — |
| max | 可被勾选的 checkbox 的最大数量 | number | — |
| aria-label a11y | 原生 aria-label属性 | string | — |
| text-color | 当按钮为活跃状态时的字体颜色 | string | — |
| fill | 当按钮为活跃状态时的边框和背景颜色 | string | — |
| tag | 复选框组元素标签 | string | div |
| validate-event | 是否触发表单验证 | boolean | true |
| options 1.3.4 | 配置式选项数据 | object | — |
| props 1.3.4 | 自定义 options 中 value / label / disabled 的字段名 | object | object |
| type 1.3.4 | 渲染选项的组件形态 | enum | checkbox |
| direction 1.3.4 | 横向/纵向排列 | enum | horizontal |
| discrete 1.3.4 | 按钮组是否离散(按钮不相连) | boolean | false |
| plain 1.3.4 | 轻量级按钮组 | boolean | false |
| round 1.3.4 | 圆角按钮样式(仅按钮样式组可用) | boolean | false |
| tight 1.3.4 | 是否开启紧凑版(左右间距均为 8px) | boolean | false |
| show-badge 1.3.4 | 是否显示右上角角标(仅 checkbox-button 有效) | boolean | false |
| label a11y deprecated | 原生 aria-label属性 | string | — |
Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | Function |
Slots
| 插槽名 | 说明 | 子标签 |
|---|---|---|
| default | 自定义默认内容 | Checkbox / Checkbox-button |
CheckboxButton API
Attributes
| 名称 | 详情 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 选中项绑定值(独立使用时) | string / number / boolean | — |
| size | 按钮尺寸,也可设置在 checkbox-group 上 | enum | — |
| value | 选中状态的值,只有在绑定对象类型为 array 时有效。 | string / number / boolean / object | — |
| label | 选中状态的值,只有在绑定对象类型为 array 时有效。 如果没有 value, label则作为value使用 | string / number / boolean / object | — |
| true-value | 选中时的值 | string / number | — |
| false-value | 没有选中时的值 | string / number | — |
| disabled | 是否禁用 | boolean | false |
| name | 原生 name 属性 | string | — |
| checked | 当前是否勾选 | boolean | false |
| tabindex | 输入框的 tabindex | string / number | — |
| validate-event | 输入时是否触发表单的校验 | boolean | true |
| self-badge 1.3.4 | 独立使用时自带圆角(border-radius: 4px)并显示选中角标 | boolean | false |
| show-overflow 1.3.4 | 文字超出时显示省略号 | boolean | false |
| tight 1.3.4 | 是否开启紧凑版(左右间距均为 8px) | boolean | false |
| true-label deprecated | 选中时的值 | string / number | — |
| false-label deprecated | 没有选中时的值 | string / number | — |
Slots
| 插槽名 | 描述 |
|---|---|
| default | 自定义默认内容 |
Copyright 2025 Winning Health 版权所有

