106 lines
4.2 KiB
JSON
106 lines
4.2 KiB
JSON
{
|
||
"slug": "dropdown",
|
||
"end": "html",
|
||
"curated": true,
|
||
"summary": "纯 H5 下拉菜单：触发器与面板靠 hidden 切换，菜单项用 data-key 标识选项。",
|
||
"usage": [
|
||
"触发器是 <button class=\"kole-dropdown-trigger\" role=\"button\" tabindex=\"0\" aria-haspopup=\"listbox\" aria-expanded=\"false\">，用 onclick=\"toggle()\" 调页内脚本。",
|
||
"面板 .kole-dropdown-panel 默认加 hidden，开合就是翻转这个属性，示范了最轻的显隐方案。",
|
||
"菜单项写 .kole-dropdown-item 加 role=\"menuitem\" 与 tabindex=\"0\"，选项标识放 data-key。",
|
||
"分隔线不写内容：加 .kole-dropdown-divider 类即可；危险项加 .is-danger、禁用项加 .is-disabled 与 pointer-events:none。"
|
||
],
|
||
"bestPractices": [
|
||
"点外部关闭挂在 document 上并用 dd.contains(e.target) 判断，避免面板内点击被误关。",
|
||
"禁用项除了 .is-disabled 还要在脚本里判一次类名，示例用 pointer-events:none 兜底，但键盘仍可能聚焦到它。",
|
||
"aria-expanded 目前固定写在标记里，切换时应同步改成 true/false，否则读屏器状态与实际面板不一致。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "attrs",
|
||
"note": "H5 端没有 props，API 载体是类名（触发器/面板/菜单项与 is-disabled、is-danger 状态类）加 data-key 钩子与 role/aria 标注，开合由页内 toggle 脚本控制 hidden。",
|
||
"table": [
|
||
{
|
||
"name": "kole-dropdown",
|
||
"type": "基础类名",
|
||
"desc": "下拉菜单根容器，脚本按它定位内部节点"
|
||
},
|
||
{
|
||
"name": "kole-dropdown-trigger",
|
||
"type": "结构类名",
|
||
"desc": "触发器按钮，带 aria-haspopup 与 aria-expanded"
|
||
},
|
||
{
|
||
"name": "kole-dropdown-panel",
|
||
"type": "结构类名",
|
||
"desc": "菜单面板，默认 hidden，展开时移除"
|
||
},
|
||
{
|
||
"name": "kole-dropdown-item",
|
||
"type": "结构类名",
|
||
"desc": "菜单项，带 role=\"menuitem\" 与 data-key"
|
||
},
|
||
{
|
||
"name": "is-disabled",
|
||
"type": "状态类名",
|
||
"desc": "禁用项：置灰、悬停不换背景"
|
||
},
|
||
{
|
||
"name": "is-danger",
|
||
"type": "状态类名",
|
||
"desc": "危险项，文字用错误色"
|
||
},
|
||
{
|
||
"name": "kole-dropdown-divider",
|
||
"type": "结构类名",
|
||
"desc": "菜单分隔线"
|
||
},
|
||
{
|
||
"name": "ico",
|
||
"type": "结构类名",
|
||
"desc": "菜单项前置图标容器"
|
||
},
|
||
{
|
||
"name": "data-key",
|
||
"type": "data-* 钩子",
|
||
"desc": "菜单项标识，脚本按它读取选中项"
|
||
},
|
||
{
|
||
"name": "hidden",
|
||
"type": "原生属性",
|
||
"desc": "面板显隐开关，toggle 脚本翻转它"
|
||
},
|
||
{
|
||
"name": "aria-haspopup",
|
||
"type": "原生属性",
|
||
"desc": "触发器上取值为 listbox，声明弹出的是列表"
|
||
},
|
||
{
|
||
"name": "aria-expanded",
|
||
"type": "原生属性",
|
||
"desc": "触发器展开状态，标记里默认写 false"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"触发器声明了 role=\"button\"、aria-haspopup=\"listbox\" 与 tabindex=\"0\"，但 aria-expanded 在脚本里没有同步更新，需要自行补齐。",
|
||
"菜单项带 role=\"menuitem\" 与 tabindex=\"0\" 可聚焦，但没有方向键与 Esc 处理。",
|
||
"禁用项靠 pointer-events:none 阻止鼠标点击，键盘仍可聚焦触发，建议加 aria-disabled=\"true\" 并拦截按键。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Dropdown.html",
|
||
"kind": "纯 H5 演示页（内联样式 + 原生脚本）",
|
||
"desc": "Dropdown.html —— 纯 H5 演示页：触发器与菜单面板结构，含 toggle 与外部点击关闭脚本"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"dropdown-ex-1"
|
||
],
|
||
"notes": [
|
||
"触发器的语义标注见（frameworks/Dropdown.html:41）",
|
||
"分隔线结构见（frameworks/Dropdown.html:32）",
|
||
"面板开合直接翻转 hidden，见（frameworks/Dropdown.html:56）",
|
||
"禁用项配色规则见（frameworks/Dropdown.html:30）",
|
||
"外部点击关闭的判定见（frameworks/Dropdown.html:66）"
|
||
]
|
||
}
|