LoadingOverlay
在页面或区块上覆盖统一加载状态。中文惯用名：加载遮罩；阻断范围与取消策略须在详情页说明。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.loading-overlay |
| 名称 | LoadingOverlay |
| 二级分类 | 反馈（feedback） |
| 用途 | 在页面或区块上覆盖统一加载状态 |
| 描述 | 中文惯用名：加载遮罩；阻断范围与取消策略须在详情页说明。 |
预览
静态结构：有 children 时根节点为 relative 容器（data-slot="loading-overlay"）包裹原内容；loading=true 时叠加绝对定位遮罩层（data-slot="loading-overlay-mask"，absolute inset-0 z-10、bg-background/70 半透明），居中 24px Spinner + 可选文案；loading=false 时只渲染 children。无 children 时退化为行内形态：loading=true 渲染 inline-flex 的 16px Spinner + 文案，loading=false 渲染 null。
DSL 结构
{
"type": "LoadingOverlay",
"props": {
"loading": true,
"text": "正在加载数据…"
},
"children": [
{
"type": "Table",
"props": {
"title": "数据表格"
}
}
]
}何时用
何时使用
- 在页面或区块上覆盖统一加载状态：表格刷新、卡片数据加载期间，遮住内容并阻断区块内操作。
- 加载期间原内容需要保留在原地（遮罩层半透明覆盖，内容不被卸载）。
- 无包裹内容时退化为独立 Spinner + 文案的行内加载指示。
何时不用
- 紧邻内容的局部「处理中」指示（按钮内、行内小图标）：使用 Spinner，二者不是可随意互换的视觉变体。
- 结构已知的首屏加载：使用 Skeleton 占位，减少布局跳动。
- 有明确进度的长任务：使用 Progress，遮罩不表达完成度。
- 全局页面级跳转加载：LoadingOverlay 只覆盖其包裹的区块，不替代路由级加载方案。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 覆盖区块（有 children） | relative 容器 + absolute 半透明遮罩（Spinner 居中） | 表格 / 卡片 / 表单区块加载，阻断区块内交互 |
| 独立加载指示（无 children） | inline-flex 的 16px Spinner + 文案；loading=false 时不渲染 | 无包裹内容的行内加载提示（如按钮旁的「加载中」） |
| 带文案 | Spinner 下方 / 旁侧附 text 说明 | 加载耗时较长时说明正在做什么（「正在保存…」） |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
loading | boolean | false | 是否处于加载态（显示覆盖层） |
text | string | — | 加载提示文案 |
children | ReactNode | — | 被覆盖区块（DSL 子树，经 Renderer children 机制渲染） |
className | string | — | 通用：根节点 class（与内置样式合并） |
style | CSSProperties | — | 通用：根节点内联样式 |
使用规范
- 阻断范围说明：遮罩层以 absolute inset-0 覆盖整个 relative 容器并置顶（z-10），加载期间区块内所有点击被遮罩拦截；Spinner 只是局部指示、不阻断周围交互——按是否需要阻断选择。
- 遮罩只覆盖自身包裹的区块：页面级阻断需包裹整个页面容器，勿误以为其会覆盖全屏。
- loading 绑定数据加载状态（如 dataSource 的 pending），请求结束（成功或失败）都要复位，失败时配合 Message / Alert 给出错误。
- 遮罩无取消入口：长任务需要取消时，在区块内自行提供取消按钮（遮罩半透明，下方按钮不可点，需另行设计）。
- 加载期间内容保留在原地（不被卸载），避免遮罩消失后的布局跳动。
正例
- ✓ 表格区块外包 LoadingOverlay：loading 绑定查询状态，text「正在加载数据…」，查询中表格不可点。
- ✓ 卡片内图表刷新：loading=true 时图表上覆半透明遮罩，数据返回后原图原位更新。
- ✓ 无包裹内容的行内场景：不包 children，loading 时展示「Spinner + 正在提交…」。
反例
- ✕ 用 LoadingOverlay 替代按钮内的局部 loading（应使用 Button loading / Spinner，遮罩会阻断整个区块）。
- ✕ 首屏结构已知的加载也用遮罩（应使用 Skeleton，避免白屏闪烁）。
- ✕ 请求失败后 loading 未复位，遮罩永久遮挡内容。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。