64 lines
4.3 KiB
JSON
64 lines
4.3 KiB
JSON
{
|
||
"slug": "messagepro",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端的 MessagePro：用 ref 暴露命令式 API（success/error/warning/info/loading），消息列表存在组件内部 state。",
|
||
"usage": [
|
||
"命令式调用是本端核心：组件用 forwardRef + useImperativeHandle 暴露 open / close / success / error / warning / info / loading，父组件拿 ref 调 `host.current.success('保存成功')`（frameworks/MessagePro.jsx:6,19-27）。",
|
||
"五个便捷方法与一个通用 open：success 等方法内部都转成 `open({ type, content: c, duration: d })`，type 决定图标与 is-${type} 类名（frameworks/MessagePro.jsx:22-26,32）。",
|
||
"消息队列是组件内部 state：open 里 `setList(l => [...l, {...}])` 追加，close 里按 id 过滤移除，父组件不能直接读写列表（frameworks/MessagePro.jsx:7,10,13）。",
|
||
"自动消失靠定时器：`const d = opts.duration == null ? duration : opts.duration; if (d > 0) setTimeout(() => close(id), d)`，即单条可覆盖组件级 duration（frameworks/MessagePro.jsx:14,15）。",
|
||
"只有 duration 一个 props（默认 3000）：其余能力全部来自 ref 上的方法（frameworks/MessagePro.jsx:6）。",
|
||
"关闭按钮是可控的：`{m.closable !== false ? <span className=\"kole-message-close\" onClick={() => close(m.id)}>✕</span> : null}`，open 时传 closable: false 可不显示（frameworks/MessagePro.jsx:13,35）。"
|
||
],
|
||
"bestPractices": [
|
||
"必须挂载组件再调用：ref 指向的实例要先渲染在页面里，否则 host.current 为 null（frameworks/MessagePro.jsx:6,19）。",
|
||
"duration 传 0 或负数可让消息不自动消失（判据是 d > 0 才设定时器）（frameworks/MessagePro.jsx:15）。",
|
||
"每条消息可单独覆盖时长：第五个便捷方法的第二参就是 duration，传 undefined 才回落到组件 prop（frameworks/MessagePro.jsx:14,22-26）。",
|
||
"列表项以自增 id 为 key，同一时刻的多条消息不会串（frameworks/MessagePro.jsx:8,12,31）。"
|
||
],
|
||
"a11y": [
|
||
"消息容器是普通 div，没有 role=\"status\" / aria-live，新消息不会被读屏器主动播报（frameworks/MessagePro.jsx:30）。",
|
||
"图标是字符（✓ / ✕ / ! / i / …）且没有 aria-hidden，读屏器会把符号与正文连读（frameworks/MessagePro.jsx:4,33）。",
|
||
"关闭控件是 <span> 而不是按钮：键盘不可聚焦，也不可回车触发（frameworks/MessagePro.jsx:35）。",
|
||
"文案由调用方传入（content），要可访问就得在 content 里写完整句子而不是只写短词（frameworks/MessagePro.jsx:13）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体不是 props 而是 ref 上的命令式方法（open / close / success / error / warning / info / loading）；唯一的 prop 是 duration（自动关闭毫秒数），没有 onXxx 回调与 v-model。",
|
||
"table": [
|
||
{
|
||
"name": "onClick",
|
||
"type": "事件",
|
||
"desc": "open 时关闭控件的原生点击名，走内部 close(id) 移除该条消息（frameworks/MessagePro.jsx:35）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/MessagePro.jsx",
|
||
"kind": "React",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/MessagePro.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"messagepro-ex-1",
|
||
"messagepro-ex-2",
|
||
"messagepro-ex-3",
|
||
"messagepro-ex-4",
|
||
"messagepro-ex-5"
|
||
],
|
||
"notes": [
|
||
"组件签名与 props 见 frameworks/MessagePro.jsx:6（只解构 duration，默认 3000）；forwardRef 与 useImperativeHandle 见第 6、19-27 行。",
|
||
"消息队列的增删见 frameworks/MessagePro.jsx:10（close）与 13（open）；自动关闭定时器见 14-15 行。",
|
||
"关闭控件的条件渲染与 onClick 见 frameworks/MessagePro.jsx:35；图标映射表见第 4 行。",
|
||
"实现缺口：无 aria-live / role=\"status\"、关闭控件是 span 而非 button（frameworks/MessagePro.jsx:30,35）；按实现写，未补。",
|
||
"table 只有 1 行：consumedApi 把第 35 行的内部 close 调用识别为事件，但对外契约其实是 ref 方法，故本页以命令式 API 叙述（frameworks/MessagePro.jsx:19-27）。"
|
||
]
|
||
}
|