144 lines
7.3 KiB
JSON
144 lines
7.3 KiB
JSON
{
|
||
"slug": "notificationpro",
|
||
"end": "html",
|
||
"curated": true,
|
||
"summary": "纯 H5 右上角通知：脚本注入 window.KoleNotify，调 success/error 等方法即弹出一条可关闭的卡片。",
|
||
"usage": [
|
||
"入口是挂在 window 上的命令式对象 KoleNotify，按钮直接写 onclick=\"KoleNotify.success('审批通过', '订单 ORD-2024 已通过主管审批')\"，不写任何 DOM 结构（NotificationPro.html:12-15）。",
|
||
"四种类型各有同名快捷方法 success / error / warning / info，签名统一为 (title, desc, duration)；需要标题与描述以外的组合时用 KoleNotify.open({ type, title, desc, duration })（NotificationPro.html:39-45）。",
|
||
"宿主容器 .kole-notification-wrap 由脚本自己创建并 append 到 body，页面里不需要预留占位节点（NotificationPro.html:20-22）。",
|
||
"每条通知的节点结构由脚本拼 innerHTML 生成：图标 .kole-notification-icon、正文 .kole-notification-body 里再分标题与描述，尾部是 .kole-notification-close（NotificationPro.html:27-30）。",
|
||
"停留时长由 duration 决定，省略时取 4500ms；传 0 或负数则不自动消失，只能点关闭图标移除（NotificationPro.html:35-36）。",
|
||
"调用方法返回一个 close 函数，可以在业务逻辑里提前收起该条通知，而不必模拟点击关闭图标（NotificationPro.html:33,37）。"
|
||
],
|
||
"bestPractices": [
|
||
"关闭交互绑在 .kole-notification-close 的 click 上并直接 removeChild，所以每条通知只被移除一次；业务侧不要把返回的 close 与关闭图标的点击混用（NotificationPro.html:33-34）。",
|
||
"自动关闭用 setTimeout 实现，没有清理逻辑；页面跳转前批量收起时请保留各条 open 返回的 close 句柄（NotificationPro.html:36）。",
|
||
"图标字形来自脚本内的 ICON 映射表（success/error/warning/info → ✓/✕/!/i），类型传错会回退成 i 而不是报错，写类型时请对齐 KoleNotification.css 的 is-* 类（NotificationPro.html:19,26）。",
|
||
"演示页把四个按钮直接写在 body 里给 onclick 用，真实项目里建议把 KoleNotify 脚本放到 body 末尾，确保调用时 wrap 已挂载（NotificationPro.html:17-46）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "attrs",
|
||
"note": "H5 端没有组件实例与 props，对外 API 是一个挂在 window 上的命令式对象 KoleNotify（含四个快捷方法与 open），视觉与类型态由 .kole-notification 加 is-* 状态类表达，关闭行为绑在 .kole-notification-close 上。",
|
||
"table": [
|
||
{
|
||
"name": "KoleNotify",
|
||
"type": "window 上的全局对象",
|
||
"desc": "通知的唯一入口，脚本初始化时挂载，页面内直接调用"
|
||
},
|
||
{
|
||
"name": "success",
|
||
"type": "(title, desc, duration) => close",
|
||
"desc": "弹出一条成功通知，返回可提前收起的 close 函数"
|
||
},
|
||
{
|
||
"name": "error",
|
||
"type": "(title, desc, duration) => close",
|
||
"desc": "弹出一条错误通知；与 success 仅类型不同"
|
||
},
|
||
{
|
||
"name": "warning",
|
||
"type": "(title, desc, duration) => close",
|
||
"desc": "弹出一条警告通知"
|
||
},
|
||
{
|
||
"name": "info",
|
||
"type": "(title, desc, duration) => close",
|
||
"desc": "弹出一条信息通知，也是类型缺省时的回退值"
|
||
},
|
||
{
|
||
"name": "open",
|
||
"type": "(opts) => close",
|
||
"desc": "底层方法，opts 为 { type, title, desc, duration }，快捷方法都由它派生"
|
||
},
|
||
{
|
||
"name": "kole-notification-wrap",
|
||
"type": "结构类名",
|
||
"desc": "右上角固定容器，z-index 3000，脚本自动创建并挂到 body"
|
||
},
|
||
{
|
||
"name": "kole-notification",
|
||
"type": "基础类名",
|
||
"desc": "单条通知卡片：白底、圆角 8px、投影 0 4px 12px"
|
||
},
|
||
{
|
||
"name": "kole-notification-icon",
|
||
"type": "状态类名",
|
||
"desc": "图标底色取 --kole-color-success"
|
||
},
|
||
{
|
||
"name": "kole-notification-title",
|
||
"type": "状态类名",
|
||
"desc": "图标底色取 --kole-color-error"
|
||
},
|
||
{
|
||
"name": "kole-notification-desc",
|
||
"type": "状态类名",
|
||
"desc": "图标底色取 --kole-color-warning"
|
||
},
|
||
{
|
||
"name": "kole-notification-close",
|
||
"type": "状态类名",
|
||
"desc": "图标底色取 --kole-color-brand"
|
||
},
|
||
{
|
||
"name": "kole-notification-icon",
|
||
"type": "结构类名",
|
||
"desc": "18×18 圆形图标位，底色随 is-* 变化"
|
||
},
|
||
{
|
||
"name": "kole-notification-body",
|
||
"type": "结构类名",
|
||
"desc": "正文容器（flex:1），内放标题与描述"
|
||
},
|
||
{
|
||
"name": "kole-notification-title",
|
||
"type": "结构类名",
|
||
"desc": "标题文字，14px/500，取 --kole-color-text-title"
|
||
},
|
||
{
|
||
"name": "kole-notification-desc",
|
||
"type": "结构类名",
|
||
"desc": "描述文字，13px，取 --kole-color-text-secondary"
|
||
},
|
||
{
|
||
"name": "kole-notification-close",
|
||
"type": "结构类名",
|
||
"desc": "关闭图标位，click 事件上绑定移除自身节点的逻辑"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"图标、正文、标题、描述四个节点各自带 aria-live=\"polite\"（NotificationPro.html:27-30），新通知插入后会被读屏器播报，但同一容器内重复声明四次属于冗余，业务侧替换节点时保留正文那一处即可。",
|
||
"关闭图标是 <span role=\"status\">，不是 button，也没有 tabindex，键盘用户无法聚焦并关闭通知，只能等 duration 到期（NotificationPro.html:30）。",
|
||
"类型只在图标底色上体现，标题与描述文本里没有「成功/失败」字样，色觉障碍用户需要靠文案自行判断严重程度（NotificationPro.html:27-29）。",
|
||
"卡片由脚本动态创建并直接 append，不参与页面初始焦点顺序；它是在右上角浮层里出现的，不会打断当前输入焦点（NotificationPro.html:31）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/NotificationPro.html",
|
||
"kind": "纯 H5 演示页（内联样式 + 原生脚本）",
|
||
"desc": "NotificationPro.html —— 纯 H5 演示页：四个类型按钮的 onclick 调用，以及 30 行原生脚本实现的 KoleNotify 全局 API"
|
||
},
|
||
{
|
||
"file": "frameworks/NotificationPro.css",
|
||
"kind": "样式文件",
|
||
"desc": "NotificationPro.css —— .kole-notification 系列类名与 is-* 状态色，由演示页 <link> 引入"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"notificationpro-ex-1",
|
||
"notificationpro-ex-2",
|
||
"notificationpro-ex-3",
|
||
"notificationpro-ex-4"
|
||
],
|
||
"notes": [
|
||
"全局入口与四个快捷方法：frameworks/NotificationPro.html:39-45",
|
||
"宿主容器自动创建：frameworks/NotificationPro.html:20-22",
|
||
"节点结构与 aria-live：frameworks/NotificationPro.html:27-30",
|
||
"默认时长 4500 与 setTimeout 自动关闭：frameworks/NotificationPro.html:35-36",
|
||
"四类状态类配色：frameworks/NotificationPro.css:9-12",
|
||
"契约 contract.dims 声明了 state=expanded/collapsed（折叠态），但 NotificationPro.css 里没有任何折叠相关类名，实现只支持展开态；按实现写，未把折叠写进 table。"
|
||
]
|
||
}
|