67 lines
3.9 KiB
JSON
67 lines
3.9 KiB
JSON
{
|
||
"slug": "checkboxcard",
|
||
"end": "vue3",
|
||
"curated": true,
|
||
"summary": "Vue 3 卡片式多选：v-model 绑选项值数组，点卡片由组件 slice 出新数组回传。",
|
||
"usage": [
|
||
"v-model 走 modelValue + update:modelValue：写 v-model 绑一个数组即完成多选双向绑定，组件对外只发这一个事件。",
|
||
"options 每项必须有 value：选中判断就是 modelValue.indexOf(o.value)（CheckboxCard.vue3.vue:4），只给 label 不给 value 的选项点了不会选中。",
|
||
"组件用 <script setup> 的 defineProps 声明 3 个 prop（第 16-20 行），模板里直接按 options / modelValue / cols 名字访问，没有 this。",
|
||
"toggle 先 props.modelValue.slice() 复制，再 splice 或 push，最后 emit 整个新数组（第 23-28 行），直接改传入的数组不会触发重渲染。",
|
||
"cols 由 defineProps 声明（默认 3），第 2 行把它拼进内联 gridTemplateColumns 的 repeat；选项数不是 cols 整数倍时最后一行留空。",
|
||
"选项可带 icon 与 desc，分别渲染成 .kole-checkcard-icon 与 .kole-checkcard-desc，两者都有 v-if 守卫，不传就不出这两层；字段的消费全在 <script setup> 的模板里，没有额外的 prop 开关。"
|
||
],
|
||
"bestPractices": [
|
||
"只传 modelValue 不监听 update:modelValue，勾选会停在原状态：组件只回传新数组，从不回写自己收到的 prop（第 27 行）。",
|
||
"在父层手动接事件时必须整体替换数组，而不是往旧数组里推进去，否则 Vue 3 的响应式引用判断不会认为变了。",
|
||
"卡片上的 .kole-checkcard-mark 是纯装饰方块，选中外观完全由 is-selected 类驱动，想让选中更显眼要改样式而不是加结构。"
|
||
],
|
||
"a11y": [
|
||
"卡片是 div 加 @click，没有 checkbox 角色也没有 aria-checked，读屏器不会播报选中状态。",
|
||
"键盘用户 Tab 不到卡片上：没有 tabindex 与按键处理，只有鼠标可点；需要键盘可达时应在业务侧补真 input 或按钮。",
|
||
"图标位是纯文本字符（emoji 之类），对读屏器会当正文念出来，装饰性图标建议干脆不要写进 options。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "Vue 3 端载体是 defineProps 声明的 3 个 prop（options / modelValue / cols）加 defineEmits 里唯一的 update:modelValue 事件；组件不提供插槽，选项内容全部由 options 数据驱动（frameworks/CheckboxCard.vue3.vue:16-21）。",
|
||
"table": [
|
||
{
|
||
"name": "cols",
|
||
"type": "Number",
|
||
"desc": "列数（frameworks/CheckboxCard.vue3.vue:2）"
|
||
},
|
||
{
|
||
"name": "modelValue",
|
||
"type": "Array",
|
||
"desc": "双向绑定值（frameworks/CheckboxCard.vue3.vue:4）"
|
||
},
|
||
{
|
||
"name": "options",
|
||
"type": "Array",
|
||
"desc": "选项数据（契约：以卡片形式展示多选选项）（frameworks/CheckboxCard.vue3.vue:3）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/CheckboxCard.vue3.vue",
|
||
"kind": "Vue 3",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/CheckboxCard.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"checkboxcard-ex-1"
|
||
],
|
||
"notes": [
|
||
"props 与事件声明见 frameworks/CheckboxCard.vue3.vue:16-21：defineProps 三项，defineEmits 只有 update:modelValue。",
|
||
"选中判断在 frameworks/CheckboxCard.vue3.vue:4（modelValue.indexOf(o.value)），数组复制与回传在 frameworks/CheckboxCard.vue3.vue:23-28。",
|
||
"cols 拼进内联 gridTemplateColumns 见 frameworks/CheckboxCard.vue3.vue:2，默认值 3 见 frameworks/CheckboxCard.vue3.vue:19。",
|
||
"契约声明的驱动维度 selection / innerActions / state 属设计词汇层，未作为 prop 写入本页。"
|
||
]
|
||
}
|