99 lines
5.0 KiB
JSON
99 lines
5.0 KiB
JSON
{
|
||
"slug": "emptypro",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端空状态组件：type 选场景，icon/title/desc 逐项覆盖预置，两个按钮经 onAction/onSecondary 回调。",
|
||
"usage": [
|
||
"入参解构为 { type = 'empty', icon, title, desc, actionText, secondaryText, onAction, onSecondary }，场景与文案全部走 props（EmptyPro.jsx:11）。",
|
||
"覆盖规则是「非空 props 优先，否则取 PRESET[type]，再否则兜底」：icon || p.icon || '📭'、title || p.title || '暂无数据'、desc || p.desc || ''（EmptyPro.jsx:12-17）。",
|
||
"两个按钮只在有文案时出现：actionText 存在才渲染 .primary 主按钮并绑 onAction，secondaryText 存在才渲染次按钮并绑 onSecondary；两者都没有时整个 .kole-empty-actions 不输出（EmptyPro.jsx:23-28）。",
|
||
"描述为空时节点不渲染（{resolved.desc ? ... : null}），空状态会自然收紧为「插画 + 标题」（EmptyPro.jsx:22）。",
|
||
"回调是不带参数的：onClick={onAction} / onClick={onSecondary}，业务侧如需事件对象需自己在包装函数里取（EmptyPro.jsx:25-26）。",
|
||
"组件不接 className 之类透传，其余属性会因未被解构而丢弃；要调布局请在父层包容器（EmptyPro.jsx:11,19）。"
|
||
],
|
||
"bestPractices": [
|
||
"四个场景（empty/permission/search/error）的差异只在 PRESET 里，新增场景要改组件源码；业务自定义文案请直接用 icon/title/desc 三项覆盖（EmptyPro.jsx:4-9,14-16）。",
|
||
"onAction 与 onSecondary 只在这两个按钮上生效，不需要在父层判断按钮是否存在；只传 onAction 不传 actionText 则按钮不出现（EmptyPro.jsx:23-26）。",
|
||
"示例里给组件加了 role=\"status\"（<KoleEmptyPro type=\"empty\" role=\"status\" ... />），但组件并不转发未知属性，该 role 不会落到 DOM 上（EmptyPro.jsx:11,19）。",
|
||
"type 传了 PRESET 里没有的值时回退成空对象，最终仍显示「暂无数据」，不会出现空标题（EmptyPro.jsx:12-16）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端 API 全是 props：type 选场景，icon/title/desc 单项覆盖预置，actionText/secondaryText 控制按钮是否出现，onAction/onSecondary 是仅有的两个回调；没有插槽或 ref 句柄。",
|
||
"table": [
|
||
{
|
||
"name": "type",
|
||
"type": "'empty' | 'permission' | 'search' | 'error'，默认 'empty'",
|
||
"desc": "选择 PRESET 场景，决定默认插画与文案"
|
||
},
|
||
{
|
||
"name": "icon",
|
||
"type": "string",
|
||
"desc": "覆盖插画文本（emoji），非空时优先于预置"
|
||
},
|
||
{
|
||
"name": "title",
|
||
"type": "string",
|
||
"desc": "覆盖标题，非空时优先于预置"
|
||
},
|
||
{
|
||
"name": "desc",
|
||
"type": "string",
|
||
"desc": "覆盖描述；解析结果为空则不渲染该节点"
|
||
},
|
||
{
|
||
"name": "actionText",
|
||
"type": "string",
|
||
"desc": "主按钮文案，非空才渲染主按钮"
|
||
},
|
||
{
|
||
"name": "secondaryText",
|
||
"type": "string",
|
||
"desc": "次按钮文案，非空才渲染次按钮"
|
||
},
|
||
{
|
||
"name": "onAction",
|
||
"type": "() => void",
|
||
"desc": "主按钮点击回调，无参数"
|
||
},
|
||
{
|
||
"name": "onSecondary",
|
||
"type": "() => void",
|
||
"desc": "次按钮点击回调，无参数"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"组件自身不输出 role 或 aria-live，动态把内容换成空状态时读屏器不会播报；需要在业务侧包一层 role=\"status\" 容器（EmptyPro.jsx:19）。",
|
||
"两个操作按钮是原生 <button>，键盘可达与 Enter/Space 触发由浏览器提供（EmptyPro.jsx:25-26）。",
|
||
"插画是 emoji 文本节点，读屏器可能朗读其名称；纯装饰时应由业务侧换成 aria-hidden 的图片或图标组件（EmptyPro.jsx:20）。",
|
||
"场景差异只由文案承担（标题里写明「无访问权限」「未找到结果」），不依赖插画或颜色，信息传达不因色觉差异缺失（EmptyPro.jsx:4-8,21）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/EmptyPro.jsx",
|
||
"kind": "React 组件",
|
||
"desc": "EmptyPro.jsx —— React 实现：PRESET 表、覆盖解析与条件渲染的按钮组"
|
||
},
|
||
{
|
||
"file": "frameworks/EmptyPro.css",
|
||
"kind": "样式文件",
|
||
"desc": "EmptyPro.css —— 组件 import 的 .kole-empty 系列样式与 .primary 主按钮配色"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"emptypro-ex-1",
|
||
"emptypro-ex-2",
|
||
"emptypro-ex-3",
|
||
"emptypro-ex-4"
|
||
],
|
||
"notes": [
|
||
"props 解构与默认 type：frameworks/EmptyPro.jsx:11",
|
||
"PRESET 四场景：frameworks/EmptyPro.jsx:4-9",
|
||
"覆盖解析 resolved：frameworks/EmptyPro.jsx:12-17",
|
||
"按钮条件渲染与回调绑定：frameworks/EmptyPro.jsx:23-26",
|
||
"描述节点的条件渲染：frameworks/EmptyPro.jsx:22",
|
||
"示例代码里写的 role=\"status\" 不会生效——组件不转发剩余 props；这一点按实现记录，未把 role 写进 table。"
|
||
]
|
||
}
|