CheckboxGroup (复选框组)
数组 v-model 的多选表单字段:classic / pill / card 三种外观,可设数量上限并在被拦下时发出 invalid。
基础用法
v-model 是一个真正的数组 —— 这也是它和一排 KunCheckBox 的区别:一个多选表单字段,而不是几个各自为政的布尔值。
支持平台
已选:windows
Basic.vue
三种外观
classic
pill
card
Galgame
动画
漫画
轻小说
Variants.vue
卡片 + 图标
邮件通知
新回复有人回复我的主题或评论
新补丁关注的游戏有新补丁发布
每周精选每周一推送本周热门
Card.vue
数量上限
到达 max 后未选中的项不再可选,已选中的仍可取消;被拦下的点击会发出 invalid 事件。
题材标签(最多 3 个)
Max.vue
禁用
单个选项禁用
整组禁用
Disabled.vue
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue * | KunCheckBoxGroupValue[] | — | The selected values, two-way bound with `v-model`. Required: a checkbox group with no model has nothing to select into. |
| options * | readonly KunCheckBoxGroupOption<KunCheckBoxGroupValue>[] | — | The selectable options. `value` is what lands in the model; `label` is shown, and `description` / `icon` / `disabled` are optional per option. |
| ariaLabel | string | "" | Accessible name for the group. Not needed when `label` is set — that becomes the group's name. |
| className | string | "" | Extra classes, merged after the component's own classes so yours wins the conflict — KunUI's `rounded-kun-*` / `shadow-kun-*` scales included. |
| color | KunUIColor | "primary" | Semantic colour of the selected state and the focus ring. |
| disabled | boolean | false | Blocks the whole group and dims it. A single option is disabled through its own `disabled`. |
| error | string | "" | Error message below the group. |
| hideIndicator | boolean | false | `card` variant only: drop the checkbox-box indicator, signal selection with the tinted border/fill alone (the icon-card look). |
| label | string | "" | Visible label above the group, wired to it with `aria-labelledby`. |
| max | number | — | Cap on how many options can be selected at once. A click that would exceed it is blocked and emits `invalid` with `'max-reached'` (already-selected options can still be toggled off). |
| orientation | KunCheckBoxGroupOrientation | "vertical" | Stack the options vertically, or wrap them in a row. |
| rounded | KunUIRounded | — | `card` variant only — it is the only variant with a surface of its own to round. `classic` is a box plus a label, and `pill` is a pill by definition; both ignore this. |
| size | KunUISize | "md" | Box, icon and text scale — shared with KunCheckBox and KunRadioGroup, so equal `size` renders identically across the three. |
| variant | KunCheckBoxGroupVariant | "classic" | Presentation: `classic` box + label, `pill` filter chips, `card` bordered cards with an optional icon. |
事件
| 事件 | 回调参数 | 说明 |
|---|---|---|
| change | value: KunCheckBoxGroupValue[] | The new selection, after a user toggle only — a programmatic `v-model` write does not emit it. |
| invalid | reason: "max-reached" | A click was blocked because it would exceed `max`. |
| update:modelValue | value: KunCheckBoxGroupValue[] |