75 lines
3.2 KiB
JSON
75 lines
3.2 KiB
JSON
{
|
||
"slug": "switch",
|
||
"end": "vue3",
|
||
"curated": true,
|
||
"summary": "Vue 3 开关：单按钮开合切换，带禁用与尺寸两个维度，状态以 is-on 类表达。",
|
||
"usage": [
|
||
"本端入参是 checked 而不是 modelValue，所以 v-model 接不通；标准写法是 :checked=\"notify\" 加 @change=\"notify = $event\"（Switch.vue3.vue:14）。",
|
||
"内部用 checked ref 以 props.checked 为初值，点击 toggle 时先改内部状态再回写，属于非受控实现：点击后按钮表现会立即切换（Switch.vue3.vue:13）。",
|
||
"可同时监听 update:modelValue 与 change，两者载荷都是布尔新值（Switch.vue3.vue:14）。",
|
||
"按钮文本固定为「切换」，不随状态变化，也不接受插槽定制（Switch.vue3.vue:2）。",
|
||
"size 声明默认 default，模板只加了 kole-switch-switch 类，未消费该值（Switch.vue3.vue:10）。"
|
||
],
|
||
"bestPractices": [
|
||
"因为内部 checked 只在初始化时读 props.checked，父子同时改值会出现不一致；需要严格受控请在外层用 :key 强制重建（Switch.vue3.vue:13）。",
|
||
"组件不提供 loading 或异步校验拦阻，开关会立即翻转；提交失败需要回滚时要额外传一次 checked 复位（Switch.vue3.vue:14）。",
|
||
"size 当前无渲染效果，尺寸差异只能通过外部 CSS 覆盖 kole-switch 类（Switch.vue3.vue:10）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "本端是内部 ref 参与的非受控实现（checked ref 初值取 props.checked），且 prop 名为 checked，与 update:modelValue 不成对。",
|
||
"table": [
|
||
{
|
||
"name": "checked",
|
||
"type": "Boolean",
|
||
"desc": "是否选中，默认 true；仅在初始化时被读取"
|
||
},
|
||
{
|
||
"name": "disabled",
|
||
"type": "Boolean",
|
||
"desc": "是否禁用，默认 false"
|
||
},
|
||
{
|
||
"name": "size",
|
||
"type": "String",
|
||
"desc": "尺寸，默认 default；当前模板未消费该值"
|
||
},
|
||
{
|
||
"name": "update:modelValue",
|
||
"type": "emit(payload: Boolean)",
|
||
"desc": "状态翻转时回写新值"
|
||
},
|
||
{
|
||
"name": "change",
|
||
"type": "emit(payload: Boolean)",
|
||
"desc": "与 update:modelValue 同载荷的独立事件"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"根节点是 button 且带 role=\"switch\" 与 :aria-checked=\"checked\"，开关语义与状态完整，键盘空格与回车均可切换（Switch.vue3.vue:2）。",
|
||
"按钮的可读名称始终是「切换」，没有 aria-label 说明它控制什么；建议业务补 aria-label 或在外层用文字标签关联（Switch.vue3.vue:2）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Switch.vue3.vue",
|
||
"kind": "Vue 3 组件",
|
||
"desc": "switch 的 Vue 3（<script setup>）实现源码"
|
||
},
|
||
{
|
||
"file": "frameworks/Switch.css",
|
||
"kind": "样式",
|
||
"desc": "该组件在 PC 端共用的样式表"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"switch-ex-1",
|
||
"switch-ex-2"
|
||
],
|
||
"notes": [
|
||
"frameworks/Switch.vue3.vue:8 — prop 为 checked，非 modelValue",
|
||
"frameworks/Switch.vue3.vue:13 — 内部状态只在初始化时读取 prop，非受控",
|
||
"frameworks/Switch.vue3.vue:2 — 原生 switch 语义与 aria-checked"
|
||
]
|
||
}
|