152 lines
7.3 KiB
JSON
152 lines
7.3 KiB
JSON
{
|
||
"slug": "icon",
|
||
"end": "html",
|
||
"curated": true,
|
||
"summary": "纯 H5 图标：页尾脚本内置 311 个图标路径表，iconHtml({ name, size, tone }) 直接产出内联 SVG 字符串。",
|
||
"usage": [
|
||
"调用入口是脚本内的 iconHtml(opts)，opts 取 { name, size, tone, spin, label, color, icon, slot }，返回一段 HTML 字符串，再写进容器（Icon.html:151-192）。",
|
||
"图标路径表以 <script type=\"application/json\" id=\"kole-icon-data\"> 的形式内联在页面里（含 sw:1.5 描边与 311 个名字），脚本 JSON.parse 它，不需要任何外部请求（Icon.html:83,92-93）。",
|
||
"name 命中时才渲染 <svg class=\"kole-icon-icon__svg\" width=\"1em\" height=\"1em\">，viewBox 由「路径串 → viewBox」反查得出，非 24 网格的图标不会被拉伸（Icon.html:173-182）。",
|
||
"尺寸走两条路：关键字 small/default/large/xlarge 加对应类，其它值（如 '18px'、'2rem'）原样写进内联 font-size，因为 SVG 边长固定 1em（Icon.html:155-164,194-196）。",
|
||
"语义色 tone 六档（default 继承父级、brand/secondary/danger/success/warning），color 优先于 tone 直接写内联 color（Icon.html:159-163）。",
|
||
"无障碍是脚本自动决定的：有 label 就输出 role=\"img\" 加 aria-label，没有就加 aria-hidden=\"true\"，同一张图只改这两个属性（Icon.html:167-169）。"
|
||
],
|
||
"bestPractices": [
|
||
"name 未命中时不会猜图标也不会出错：有 slot 就渲染传入的 HTML 片段（示例里传的是 '<strong>?</strong>'），所以占位兜底要自己给（Icon.html:98-101,250-253）。",
|
||
"历史字段 icon（字形字符，默认 '★'）只在 name 为空且没有 slot 时使用，name 有值时 name 优先，老调用点因此不受影响（Icon.html:187-190,289-291）。",
|
||
"spin 的动画在样式表里配了 prefers-reduced-motion: reduce 时置 none，用 iconHtml({ spin: true }) 时无需自己处理降级（Icon.css:119,123-125）。",
|
||
"图标本身不是热区：演示页把图标塞进 <button class=\"kole-icon-button\"> 里，键盘可达与焦点环交给原生 button（Icon.html:269-274,130）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "attrs",
|
||
"note": "H5 端没有组件实例，API 是脚本函数 iconHtml(opts) 加一组类名：opts 里的 name/size/tone/spin/label/color/icon/slot 决定输出，生成的节点带 kole-icon-icon 及其变体类；图标数据表由页面内联 JSON 提供。",
|
||
"table": [
|
||
{
|
||
"name": "kole-icon-icon",
|
||
"type": "根类名",
|
||
"desc": "所有图标节点的基类，负责 1em 行内方块与 currentColor 继承"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--small",
|
||
"type": "尺寸类名",
|
||
"desc": "size=small，把 --kole-icon-size 设为 --kole-icon-size-16"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--default",
|
||
"type": "尺寸类名",
|
||
"desc": "size=default，--kole-icon-size-20"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--large",
|
||
"type": "尺寸类名",
|
||
"desc": "size=large，--kole-icon-size-24"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--xlarge",
|
||
"type": "尺寸类名",
|
||
"desc": "size=xlarge，固定 32px"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--brand",
|
||
"type": "色调类名",
|
||
"desc": "tone=brand，color 取 --kole-color-brand"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--secondary",
|
||
"type": "色调类名",
|
||
"desc": "tone=secondary，取 --kole-color-text-secondary"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--danger",
|
||
"type": "色调类名",
|
||
"desc": "tone=danger，取 --kole-color-error"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--success",
|
||
"type": "色调类名",
|
||
"desc": "tone=success，取 --kole-color-success"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--warning",
|
||
"type": "色调类名",
|
||
"desc": "tone=warning，取 --kole-color-warning"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon--spin",
|
||
"type": "状态类名",
|
||
"desc": "spin 为真时附加，1s 线性无限旋转，reduce 动效下停止"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon__svg",
|
||
"type": "结构类名",
|
||
"desc": "内联 SVG 节点，display:block、width/height 均为 1em、overflow visible"
|
||
},
|
||
{
|
||
"name": "kole-icon-icon__glyph",
|
||
"type": "结构类名",
|
||
"desc": "历史字形字符容器（icon 字段），行高 1、继承字体"
|
||
},
|
||
{
|
||
"name": "kole-icon-button",
|
||
"type": "场景类名",
|
||
"desc": "承载图标的按钮样式，最低高度取控件高度令牌"
|
||
},
|
||
{
|
||
"name": "kole-icon-primary",
|
||
"type": "场景修饰类名",
|
||
"desc": "主按钮配色（品牌底、反色文字），与 kole-icon-button 配合"
|
||
},
|
||
{
|
||
"name": "kole-icon-sort-head",
|
||
"type": "场景类名",
|
||
"desc": "可排序表头：inline-flex、无边框无底色，配合 aria-sort 变色"
|
||
},
|
||
{
|
||
"name": "kole-icon-empty",
|
||
"type": "场景类名",
|
||
"desc": "空状态容器：网格居中、列间距 8px，含 kole-icon-title 与 kole-icon-desc"
|
||
},
|
||
{
|
||
"name": "kole-icon-grid",
|
||
"type": "场景类名",
|
||
"desc": "图标网格：auto-fill 最小 96px 列，gap 取 --kole-space-8"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"label 有值输出 role=\"img\" 加 aria-label（示例里的「搜索（small）」「收藏（default）」），无值输出 aria-hidden=\"true\"，装饰性图标不会进读屏序列（Icon.html:167-169,239-245）。",
|
||
"内联 SVG 自身固定写 aria-hidden=\"true\" 与 focusable=\"false\"，语义统一由外层 span 承担，图标内部不会被重复播报（Icon.html:177）。",
|
||
"图标不作为唯一信息载体：颜色变化（tone）在演示里都与文字或 label 同时出现，色觉障碍用户不依赖颜色判断含义（Icon.html:41）。",
|
||
"图标自身不是热区，按钮与排序表头用原生 <button>（后者带 aria-sort）提供键盘可达与焦点环（Icon.html:269-278）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Icon.html",
|
||
"kind": "纯 H5 演示页（内联图标数据 + 原生脚本）",
|
||
"desc": "Icon.html —— 纯 H5 演示页：内联 311 名图标 JSON 表、iconHtml 渲染函数与七个场景区块的填充脚本"
|
||
},
|
||
{
|
||
"file": "frameworks/Icon.css",
|
||
"kind": "样式文件",
|
||
"desc": "Icon.css —— .kole-icon-icon 及尺寸/色调/旋转变体类与演示场景类（网格、排序表头、空状态）"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"icon-ex-1",
|
||
"icon-ex-2",
|
||
"icon-ex-4",
|
||
"icon-ex-5",
|
||
"icon-ex-6",
|
||
"icon-ex-7"
|
||
],
|
||
"notes": [
|
||
"iconHtml 的实现与选项语义：frameworks/Icon.html:151-192",
|
||
"内联 JSON 数据表与解析：frameworks/Icon.html:83,92-93",
|
||
"size 关键字与任意长度两条路径：frameworks/Icon.html:155-164,194-196",
|
||
"a11y 属性按 label 分流：frameworks/Icon.html:167-169",
|
||
"name 未命中回落 slot：frameworks/Icon.html:187-190,250-253",
|
||
"尺寸与色调类定义：frameworks/Icon.css:104-116；spin 与动效降级：frameworks/Icon.css:119-125",
|
||
"本页标记里还存有演示脚手架类（.demo/.demo-block/.demo-cell 等，Icon.html:10-18 内联样式），属页面外壳不进 table。"
|
||
]
|
||
}
|