iter(g273): 新增区域加载遮罩组件

2026-10-26 22:59:06 +08:00
parent 1cb9d7a25a
commit d6e4319151
12 changed files with 226 additions and 10 deletions
@@ -81,3 +81,4 @@ export { jsonViewer } from './jsonViewer.js';
 export { diffView } from './diffView.js';
 export { codeBlock } from './codeBlock.js';
 export { signaturePad } from './signaturePad.js';
+export { loading } from './loading.js';
@@ -0,0 +1,39 @@
+import { effect, h } from '@ui-arch/frame';
+import { spinner } from './spinner.js';
+import type { LoadingProps } from './types.js';
+
+// 缺省延迟：120ms 内的请求不闪遮罩，否则「点了就闪一下」比不显示更闹
+const DELAY = 120;
+
+/*** 区域加载遮罩：包住一块内容，active 为真时盖上层遮罩 + 转圈 + 文案；带延迟出场，快请求不闪、慢请求必有反馈 ***/
+export function loading(props: LoadingProps, ...children: unknown[]): HTMLElement {
+  const delay = props.delay ?? DELAY; // 延迟毫秒
+  let timer = 0;                       // 延迟计时器
+  const read = (): boolean => (typeof props.active === 'function' ? Boolean(props.active()) : props.active === true); // 布尔与信号同一口径
+  const mask = h(
+    'div',
+    { class: 'ua-loading-mask' },
+    spinner({ size: props.spinnerSize ?? 20, label: props.text ?? '内容加载中' }), // 转圈自带 role=status，这里只用它的可访问名
+    props.text ? h('span', { class: 'ua-loading-text' }, props.text) : null,
+  );
+  const wrap = h(
+    'div',
+    { class: 'ua-loading' },
+    h('div', { class: 'ua-loading-body' }, ...children), // 内容层：遮罩出现时整体降透明度，但仍留在原位不塌陷
+    mask,
+  );
+  if (props.minHeight !== undefined) wrap.style.minHeight = `${props.minHeight}px`; // 内容为空时也要撑出高度，遮罩才盖得住
+
+  /*** 状态落点：is-active 控制遮罩显隐，aria-busy 让读屏知道这块在等数据 ***/
+  const paint = (on: boolean): void => {
+    wrap.classList.toggle('is-active', on);
+    wrap.setAttribute('aria-busy', String(on));
+  };
+  effect(() => {
+    window.clearTimeout(timer);
+    if (!read()) { paint(false); return; } // 关得快：立刻收，不等延迟
+    timer = window.setTimeout(() => paint(true), delay); // 开得慢：先等一会儿，避免快速请求闪一下
+  });
+  paint(read()); // 首帧：初值为真时直接亮（延迟只管后续变化）
+  return wrap;
+}
@@ -1069,3 +1069,12 @@ export interface SignaturePadHandle {
  toDataURL(): string;                   // 取当前签字 PNG dataURL（未签也返回空白图）
  isEmpty(): boolean;                    // 是否尚未落笔
 }
+
+/*** 区域加载遮罩入参 ***/
+export interface LoadingProps {
+  active?: boolean | Signal<boolean>;  // 是否加载中：布尔直接置位，传信号则随状态显隐
+  text?: string;                       // 遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」）
+  delay?: number;                      // 出场延迟（ms）；缺省 120，快请求不闪遮罩
+  spinnerSize?: number;                // 转圈直径（px）；缺省 20
+  minHeight?: number;                  // 最小高度（px）；内容为空时兜住遮罩高度
+}
@@ -95,7 +95,8 @@
      "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
      "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
      "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮",
-      "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）"
+      "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）",
+      "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁"
    ],
    "keyTypes": [
      "ButtonProps",
@@ -4218,6 +4219,46 @@
          "需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」",
          "禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页"
        ]
+      },
+      {
+        "id": "loading",
+        "title": "区域加载遮罩 Loading",
+        "demo": "sec-loading",
+        "props": [
+          {
+            "n": "active",
+            "t": "boolean | Signal<boolean>",
+            "d": "是否加载中：布尔直接置位，传信号则随状态显隐"
+          },
+          {
+            "n": "text",
+            "t": "string",
+            "d": "遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」）"
+          },
+          {
+            "n": "delay",
+            "t": "number",
+            "d": "出场延迟（ms）；缺省 120，快请求不闪遮罩"
+          },
+          {
+            "n": "spinnerSize",
+            "t": "number",
+            "d": "转圈直径（px）；缺省 20"
+          },
+          {
+            "n": "minHeight",
+            "t": "number",
+            "d": "最小高度（px）；内容为空时兜住遮罩高度"
+          }
+        ],
+        "example": "loading({ active: busy, text: '正在刷新订单' }, dataTable({ ... }))",
+        "steps": [
+          "把要遮挡的那块内容作为 children 交进来，active 传布尔或信号：刷新时盖上遮罩，数据回来后自动收起",
+          "内容不隐藏、只降透明度——布局与尺寸原地保留，遮罩收起时不会跳一下",
+          "默认延迟 120ms 出场：接口快于这个时间就不闪遮罩；想立刻显示传 delay: 0",
+          "遮罩文案写明在等什么（「正在刷新订单」），读屏同一句也会播报；只要转圈就省略 text",
+          "内容可能为空时给 minHeight，否则高度塌成 0 遮罩无处可盖"
+        ]
      }
    ]
  }
@@ -5740,3 +5740,42 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
  color: var(--ua-color-text-faint);
  cursor: not-allowed;
 }
+
+/* ---- 区域加载遮罩：内容原样留在原位、只降透明度，遮罩盖在其上；不做模糊（糊字会让等待更焦虑） ---- */
+.ua-loading {
+  position: relative;
+  border-radius: var(--ua-radius-md);
+}
+
+.ua-loading-body {
+  transition: opacity var(--ua-duration-base) var(--ua-ease);
+}
+
+/* 遮罩：定位铺满整块，默认不可见也不拦事件；只有 is-active 才出场 */
+.ua-loading-mask {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--ua-space-2);
+  border-radius: inherit;
+  background: color-mix(in srgb, var(--ua-color-surface) var(--ua-alpha-strong), transparent);
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity var(--ua-duration-fast) var(--ua-ease), visibility var(--ua-duration-fast) var(--ua-ease);
+}
+
+.ua-loading.is-active .ua-loading-mask {
+  opacity: 1;
+  visibility: visible;
+}
+
+.ua-loading.is-active .ua-loading-body {
+  opacity: 0.5; /* 内容降透明度而不是隐藏：保留位置与尺寸，遮罩挡住操作但不让布局跳动 */
+}
+
+.ua-loading-text {
+  color: var(--ua-color-text-secondary);
+  font-size: var(--ua-font-size-sm);
+}