78 lines
3.8 KiB
JSON
78 lines
3.8 KiB
JSON
{
|
||
"slug": "buttongroup",
|
||
"end": "vue3",
|
||
"curated": true,
|
||
"summary": "Vue 3 按钮组，用 options 数据渲染，单选与多选由 multiple 切换，双向绑定走 modelValue。",
|
||
"usage": [
|
||
"单选与多选共用一个组件：multiple 为真时 `modelValue` 必须是数组，选中判断走 indexOf，点选用 splice/push 造出新数组再派发。",
|
||
"`v-model` 在本端是 `modelValue` 加 `update:modelValue`，同时还会多派发一个 change，两个事件的载荷是同一个值。",
|
||
"选项要写成 `options=[{ value, label, disabled? }]`：按钮文案取 label、选中比较取 value，组件没有默认插槽放自定义内容。",
|
||
"多选切换是非受控式数组拷贝：`(props.modelValue || []).slice()` 之后再增删，不直接改父组件传进来的那个数组。",
|
||
"尺寸只有 small 与 large 两个取值会让模板加类（`is-sm` / `is-lg`），size 是 `defineProps` 声明的第四个 prop，传 default 或其他值都不加类。"
|
||
],
|
||
"bestPractices": [
|
||
"多选下 modelValue 必须是数组：传字符串会让 indexOf 作用在字符串上，选中判断退化成子串命中，行为与预期不符。",
|
||
"`options[].disabled` 只跳过切换并给按钮加原生 disabled，不派发任何事件，父级收不到「点到禁用项」的信号。",
|
||
"同一个 next 值被派发两次（update:modelValue 与 change），父级两个都监听会把同一次点选处理两遍。"
|
||
],
|
||
"a11y": [
|
||
"每项是原生 `<button>` 且带 `:disabled`，键盘可聚焦，禁用项会被读屏器播报为不可用。",
|
||
"容器是普通 div，没有 `role=\"group\"` 或 radiogroup，读屏器不知道这是一组互斥选项。",
|
||
"选中态只落在 `.is-selected` 类上，没有 `aria-pressed` 或 `aria-checked`，读屏器读不出当前选中项。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "Vue 3 端的 API 载体是 4 个 props（options / modelValue / multiple / size）与 `update:modelValue`、`change` 两个事件，无插槽。",
|
||
"table": [
|
||
{
|
||
"name": "modelValue",
|
||
"type": "String | Array",
|
||
"desc": "双向绑定值（frameworks/ButtonGroup.vue3.vue:16）"
|
||
},
|
||
{
|
||
"name": "multiple",
|
||
"type": "Boolean",
|
||
"desc": "是否多选（契约：可选中（单选/多选）、可分隔）（frameworks/ButtonGroup.vue3.vue:17）"
|
||
},
|
||
{
|
||
"name": "options",
|
||
"type": "Array",
|
||
"desc": "选项数据（frameworks/ButtonGroup.vue3.vue:3）"
|
||
},
|
||
{
|
||
"name": "size",
|
||
"type": "String",
|
||
"desc": "尺寸（契约：支持尺寸统一、禁用）（frameworks/ButtonGroup.vue3.vue:2）"
|
||
},
|
||
{
|
||
"name": "change",
|
||
"type": "(val: any) => void",
|
||
"desc": "值变化时触发（frameworks/ButtonGroup.vue3.vue:20）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/ButtonGroup.vue3.vue",
|
||
"kind": "Vue 3",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/ButtonGroup.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"buttongroup-ex-1",
|
||
"buttongroup-ex-2"
|
||
],
|
||
"notes": [
|
||
"props 与 emits 的声明见 frameworks/ButtonGroup.vue3.vue:14-20。",
|
||
"选中判定见 frameworks/ButtonGroup.vue3.vue:22-24（多选走 indexOf，单选走全等）。",
|
||
"切换逻辑与双事件派发见 frameworks/ButtonGroup.vue3.vue:25-38，多选用 slice 拷贝后再改。",
|
||
"尺寸类只处理 small 与 large 两个取值，见 frameworks/ButtonGroup.vue3.vue:2。",
|
||
"该端无插槽：frameworks/ButtonGroup.vue3.vue 模板里未出现 slot，内容只能由 options 提供。"
|
||
]
|
||
}
|