87 lines
3.7 KiB
JSON
87 lines
3.7 KiB
JSON
{
|
||
"slug": "autocomplete",
|
||
"end": "html",
|
||
"curated": true,
|
||
"summary": "纯 H5 自动补全：输入框配候选面板，脚本按关键字过滤并把命中片段包进 mark 高亮。",
|
||
"usage": [
|
||
"结构是 .kole-autocomplete 容器加 .kole-autocomplete-input 输入框与 .kole-autocomplete-pop 候选面板。",
|
||
"候选条目 .kole-autocomplete-item 由脚本拼字符串生成，选中态加 .is-active，空结果时渲染 .kole-autocomplete-empty。",
|
||
"点击或键盘选择用同一份索引：条目带 data-i，面板上挂 click 委托，textarea/input 挂 keydown 处理上下键与 Enter。",
|
||
"高亮用正则把命中片段替换成 <mark>…</mark>，因此候选是 innerHTML 渲染而非纯文本。",
|
||
"点击文档其它位置关闭面板，判断条件是 root.contains(e.target)。"
|
||
],
|
||
"bestPractices": [
|
||
"高亮走 innerHTML，候选文案若来自用户输入请先转义，否则会有 HTML 注入风险。",
|
||
"面板显隐用 style.display（示例如此），补 aria 状态时要注意与 display 同步。",
|
||
"active 索引在列表重建后要重置为 -1，否则过滤变短后旧索引会指向已不存在的条目。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "attrs",
|
||
"note": "H5 端没有 props，API 载体是类名（.kole-autocomplete 容器、输入框、候选面板、条目与 is-active、空态类）加 data-i 条目索引钩子，过滤与高亮全由页内脚本实现。",
|
||
"table": [
|
||
{
|
||
"name": "kole-autocomplete",
|
||
"type": "基础类名",
|
||
"desc": "自动补全根容器，脚本按它判断点击内外"
|
||
},
|
||
{
|
||
"name": "kole-autocomplete-input",
|
||
"type": "结构类名",
|
||
"desc": "原生输入框，键盘处理挂在它上面"
|
||
},
|
||
{
|
||
"name": "kole-autocomplete-pop",
|
||
"type": "结构类名",
|
||
"desc": "候选面板，靠 style.display 显隐"
|
||
},
|
||
{
|
||
"name": "kole-autocomplete-item",
|
||
"type": "结构类名",
|
||
"desc": "候选条目，可叠加 is-active"
|
||
},
|
||
{
|
||
"name": "is-active",
|
||
"type": "状态类名",
|
||
"desc": "键盘当前选中的候选"
|
||
},
|
||
{
|
||
"name": "kole-autocomplete-empty",
|
||
"type": "结构类名",
|
||
"desc": "无匹配结果时的提示节点"
|
||
},
|
||
{
|
||
"name": "data-i",
|
||
"type": "data-* 钩子",
|
||
"desc": "候选条目索引，点击时据此取选项值"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"输入框是原生 input，键盘可用；候选面板没有 role=\"listbox\" 与 aria-activedescendant。",
|
||
"面板显隐没有 aria-expanded 通知，读屏器不会被告知候选列表弹出或收起。",
|
||
"高亮用的 <mark> 元素本身带语义，读屏器会把它读作相关文本，这是可保留的做法。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/AutoComplete.html",
|
||
"kind": "纯 H5 演示页（内联样式 + 原生脚本）",
|
||
"desc": "AutoComplete.html —— 纯 H5 演示页：输入框与候选面板结构，含 3 个函数负责过滤、高亮与键盘处理"
|
||
},
|
||
{
|
||
"file": "frameworks/AutoComplete.css",
|
||
"kind": "样式文件",
|
||
"desc": "AutoComplete.css —— 本页组件类名的样式定义，由 AutoComplete.html 第 8 行的 <link rel=\"stylesheet\" href=\"AutoComplete.css\"> 引入"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"autocomplete-ex-1"
|
||
],
|
||
"notes": [
|
||
"候选面板结构见（frameworks/AutoComplete.html:18）",
|
||
"空态节点见（frameworks/AutoComplete.html:39）",
|
||
"条目选中态拼装见（frameworks/AutoComplete.html:44）",
|
||
"点击外部关闭面板见（frameworks/AutoComplete.html:39）",
|
||
"键盘处理挂载见（frameworks/AutoComplete.html:53）"
|
||
]
|
||
}
|