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 对应的字段名。

基础用法:通过 options 配置选项
按钮形态:type="button"
自定义字段名:props

多选框组 ​

适用于多个勾选框绑定到同一个数组的情景,通过是否勾选来表示这一组选项中选中的项。

在 w-checkbox-group 中使用 v-model 绑定 Array 类型的变量即可。在 w-checkbox 组件中,value 是选择框的值,与数组中的元素值相对应:如果指定的值存在于数组中,就处于选中状态,反之亦然。如果该组件下没有被传入内容,那么 label 将会作为 checkbox 后的介绍。

默认
indeterminate 属性用以表示 checkbox 的不确定状态,一般用于实现全选的效果
使用 min 和 max 属性能够限制可以被勾选的项目的数量。

按钮样式 ​

按钮样式的多选组合。round 圆角按钮组;discrete 离散按钮组(按钮不相连);plain 轻量级按钮组;tight 紧凑按钮组(文字左右内边距收窄为 8px);show-badge 角标样式(需配合 plain,仅在选中项上显示,与 round 互斥)。属性可组合使用,可在顶部勾选属性手动查看组合效果。

只需要把 w-checkbox 元素替换为 w-checkbox-button 元素即可。 此外,WinDesign Next 还提供了size属性。

长文本省略 ​

多语言场景下,选项文本可能较长。当多选框所在容器宽度受限(如固定宽度的分组、栅格列)时,选项保持单行显示,超出部分以省略号截断,鼠标悬浮在选项文字上可通过原生 title 查看完整内容。

默认样式
带边框

按钮文字省略 1.3.4 ​

设置 w-checkbox-button 的 show-overflow 属性后,按钮文字保持单行显示,超出部分以省略号截断,可与 tight 组合使用;也可在 w-checkbox-group 上统一开启(对组内所有按钮生效),或通过 options 配置项为单个选项设置 showOverflow。注意:show-overflow 需要配合宽度使用——按钮本身或其所在容器需要有限定宽度(如固定宽度、flex 收缩或栅格列),否则按钮会随内容自动撑开,不会出现省略。

按钮组排列方向 ​

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是否禁用booleanfalse
border是否显示边框booleanfalse
sizeCheckbox 的尺寸enum—
name原生 name 属性string—
checked当前是否勾选booleanfalse
indeterminate设置不确定状态,仅负责样式控制booleanfalse
validate-event输入时是否触发表单的校验booleantrue
tight 1.3.4是否开启紧凑版(左右间距均为 8px)booleanfalse
tabindex输入框的 tabindexstring / number—
idinput idstring—
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是否禁用booleanfalse
min可被勾选的 checkbox 的最小数量number—
max可被勾选的 checkbox 的最大数量number—
aria-label a11y原生 aria-label属性string—
text-color当按钮为活跃状态时的字体颜色string—
fill当按钮为活跃状态时的边框和背景颜色string—
tag复选框组元素标签stringdiv
validate-event是否触发表单验证booleantrue
options 1.3.4配置式选项数据object—
props 1.3.4自定义 options 中 value / label / disabled 的字段名objectobject
type 1.3.4渲染选项的组件形态enumcheckbox
direction 1.3.4横向/纵向排列enumhorizontal
discrete 1.3.4按钮组是否离散(按钮不相连)booleanfalse
plain 1.3.4轻量级按钮组booleanfalse
round 1.3.4圆角按钮样式(仅按钮样式组可用)booleanfalse
tight 1.3.4是否开启紧凑版(左右间距均为 8px),透传给组内 checkbox / checkbox-buttonbooleanfalse
show-overflow 1.3.4按钮文字超出时显示省略号,用于透传给组内 checkbox-button(仅按钮样式组可用)booleanfalse
show-badge 1.3.4是否显示右上角角标(仅 checkbox-button 有效;需配合 plain 且仅在选中项上显示,与 round 互斥)booleanfalse
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是否禁用booleanfalse
name原生 name 属性string—
checked当前是否勾选booleanfalse
tabindex输入框的 tabindexstring / number—
validate-event输入时是否触发表单的校验booleantrue
self-badge 1.3.4独立使用时自带圆角(border-radius: 4px)并显示选中角标booleanfalse
show-overflow 1.3.4文字超出时显示省略号(需配合按钮或容器的限定宽度使用,仅 checkbox-button 有效)booleanfalse
tight 1.3.4是否开启紧凑版(左右间距均为 8px)booleanfalse
true-label deprecated选中时的值string / number—
false-label deprecated没有选中时的值string / number—

Slots ​

插槽名描述
default自定义默认内容

Copyright 2025 Winning Health 版权所有