73 lines
4.1 KiB
JSON
73 lines
4.1 KiB
JSON
{
|
||
"slug": "loadingoverlay",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端的 LoadingOverlay：visible 为假返回 null，inline 与 dark 拼类名，text 有值才渲染文案行。",
|
||
"usage": [
|
||
"可见性是提前返回：`if (!visible) return null;` 让遮罩完全不进 DOM，父组件用 useState 控制开关（frameworks/LoadingOverlay.jsx:5）。",
|
||
"两个布尔 prop 通过字符串拼接进类名：`kole-loading-overlay` 后依次追加 ` is-inline` 与 ` is-dark`（frameworks/LoadingOverlay.jsx:7）。",
|
||
"文案是条件渲染：`{text ? <div className=\"kole-loading-text\">{text}</div> : null}`，空串时不渲染文案行（frameworks/LoadingOverlay.jsx:9）。",
|
||
"旋转指示器是无条件渲染的空 div `.kole-loading-spinner`，动画由 CSS 提供（frameworks/LoadingOverlay.jsx:8）。",
|
||
"组件没有任何回调型 props，也无 children：它不报告加载开始或结束，只按 visible 显示（frameworks/LoadingOverlay.jsx:4）。"
|
||
],
|
||
"bestPractices": [
|
||
"全屏还是局部由 inline 决定：局部遮罩要配合父容器的 position: relative 才不会盖住整页（frameworks/LoadingOverlay.jsx:7）。",
|
||
"text 为空时不渲染文案行，想保留占位高度需自己传空格或补样式（frameworks/LoadingOverlay.jsx:9）。",
|
||
"关闭只能靠父组件把 visible 改回 false，组件没有任何自动消失逻辑（frameworks/LoadingOverlay.jsx:5）。",
|
||
"dark 只影响类名，配色由 LoadingOverlay.css 决定，样式未导入时两个外观没有差别（frameworks/LoadingOverlay.jsx:7）。"
|
||
],
|
||
"a11y": [
|
||
"遮罩与文案都没有 role=\"status\" / aria-live，读屏器不会在加载开始时播报（frameworks/LoadingOverlay.jsx:7-10）。",
|
||
"旋转指示器是空 div，也没有 aria-hidden 或文本替代，读屏器读不到「加载中」这件事（frameworks/LoadingOverlay.jsx:8）。",
|
||
"组件不设置 aria-busy、也不拦截焦点，键盘用户仍可 Tab 到被遮住的背景元素（frameworks/LoadingOverlay.jsx:7）。",
|
||
"可见文案走 text prop（frameworks/LoadingOverlay.jsx:9），传入具体动作（如「正在提交」）比留空更利于读屏用户理解。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体是 4 个 props（visible / text / inline / dark），全部为展示型、没有 onXxx 回调；可见性由父组件持有，没有 v-model 类双向入口。",
|
||
"table": [
|
||
{
|
||
"name": "dark",
|
||
"type": "Boolean",
|
||
"desc": "为真时类名追加 is-dark（frameworks/LoadingOverlay.jsx:7）"
|
||
},
|
||
{
|
||
"name": "inline",
|
||
"type": "Boolean",
|
||
"desc": "为真时类名追加 is-inline，配合父容器相对定位（frameworks/LoadingOverlay.jsx:7）"
|
||
},
|
||
{
|
||
"name": "text",
|
||
"type": "String",
|
||
"desc": "文案，非空才渲染 .kole-loading-text（frameworks/LoadingOverlay.jsx:9）"
|
||
},
|
||
{
|
||
"name": "visible",
|
||
"type": "Boolean",
|
||
"desc": "为假时组件 return null，整块不进 DOM（frameworks/LoadingOverlay.jsx:5）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/LoadingOverlay.jsx",
|
||
"kind": "React",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/LoadingOverlay.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"loadingoverlay-ex-1"
|
||
],
|
||
"notes": [
|
||
"props 解构见 frameworks/LoadingOverlay.jsx:4，共 4 个；提前返回见第 5 行；类名拼接见第 7 行；文案条件渲染见第 9 行。",
|
||
"消费核验：4 个 prop 全部参与渲染（visible 控渲染、inline / dark 拼类名、text 条件渲染），无未接线 prop（frameworks/LoadingOverlay.jsx:5-9）。",
|
||
"实现缺口：无 aria-live / role=\"status\"、无 aria-busy、不拦焦点（frameworks/LoadingOverlay.jsx:7-10）；按实现写，未补。",
|
||
"a11y 依据：spinner 是空 div 见 frameworks/LoadingOverlay.jsx:8；全套 aria 属性在文件中不存在。"
|
||
]
|
||
}
|