iter(g275): 新增相对时间组件

packages/skin/ui/src/index.ts

@@ -82,3 +82,4 @@ export { diffView } from './diffView.js';
 export { codeBlock } from './codeBlock.js';
 export { signaturePad } from './signaturePad.js';
 export { loading } from './loading.js';
+export { relativeTime } from './relativeTime.js';

packages/skin/ui/src/relativeTime.ts

@@ -0,0 +1,58 @@
+import { h } from '@ui-arch/frame';
+import type { RelativeTimeProps } from './types.js';
+
+// 缺省刷新间隔与切换绝对日期的阈值：30s 够用又不吵，7 天后再用「N 天前」已不如日期直观
+const TICK = 30_000;
+const MAX_AGO = 7 * 86_400;
+
+/*** 目标时间归一成毫秒时间戳；非法输入给 NaN，调用方按「未知」处理 ***/
+function toMs(value: string | number | Date): number {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number') return value < 1e12 ? value * 1000 : value; // 10 位按秒、13 位按毫秒
+  return new Date(value).getTime();
+}
+
+/*** 相对文案：刚刚 / N 分钟前 / N 小时前 / N 天前；未来时间反过来说「还有」 ***/
+function phrase(diffSec: number): string {
+  const future = diffSec < 0;
+  const s = Math.abs(diffSec);
+  const unit = (n: number, name: string): string => (future ? `还有 ${n} ${name}` : `${n} ${name}前`);
+  if (s < 60) return future ? '即将' : '刚刚';
+  if (s < 3600) return unit(Math.floor(s / 60), '分钟');
+  if (s < 86400) return unit(Math.floor(s / 3600), '小时');
+  return unit(Math.floor(s / 86400), '天');
+}
+
+/*** 补零：绝对日期要定宽，列表里才不会一行一个宽度 ***/
+const pad = (n: number): string => String(n).padStart(2, '0');
+
+/*** 绝对日期：超出阈值后显示，同时作悬停提示（精确到分钟就够，秒是噪音） ***/
+function absolute(ms: number): string {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/*** 相对时间：把时间戳渲染成「3 分钟前」并按间隔自动刷新；超阈值改显示绝对日期，title 始终给精确值 ***/
+export function relativeTime(props: RelativeTimeProps): HTMLElement {
+  const ms = toMs(props.value); // 目标时间（毫秒）
+  const tick = props.refresh ?? TICK; // 自动刷新间隔；传 0 关闭
+  const maxAgo = props.threshold ?? MAX_AGO; // 超过多少秒改用绝对日期
+  const el = h('time', { class: 'ua-reltime', datetime: Number.isNaN(ms) ? '' : new Date(ms).toISOString() }) as HTMLTimeElement;
+  if (Number.isNaN(ms)) { el.textContent = props.fallback ?? '—'; return el; } // 非法时间：不猜，给占位（缺省破折号）
+  el.title = absolute(ms); // 悬停即精确时间：相对文案永远不需要「点开看」
+  if (props.ariaLabel) el.setAttribute('aria-label', props.ariaLabel);
+
+  /*** 一次重绘：算差值 → 超阈值用绝对日期，否则相对文案 ***/
+  const paint = (): void => {
+    const diffSec = Math.round((Date.now() - ms) / 1000);
+    el.textContent = Math.abs(diffSec) > maxAgo ? absolute(ms) : phrase(diffSec);
+  };
+  paint();
+  if (tick > 0) {
+    const timer = window.setInterval(() => {
+      if (!el.isConnected) { window.clearInterval(timer); return; } // 已卸载：自断，避免列表反复挂载累积计时器
+      paint();
+    }, tick);
+  }
+  return el;
+}

packages/skin/ui/src/types.ts

@@ -1078,3 +1078,12 @@ export interface LoadingProps {
   spinnerSize?: number;                // 转圈直径（px）；缺省 20
   minHeight?: number;                  // 最小高度（px）；内容为空时兜住遮罩高度
 }
+
+/*** 相对时间入参 ***/
+export interface RelativeTimeProps {
+  value: string | number | Date;  // 目标时间：ISO 串 / 时间戳（10 位按秒、13 位按毫秒）/ Date
+  refresh?: number;               // 自动刷新间隔（ms）；缺省 30000，传 0 不刷新
+  threshold?: number;             // 超过该秒数改用绝对日期；缺省 7 天
+  fallback?: string;              // 时间非法时的占位文案；缺省「—」
+  ariaLabel?: string;             // 可访问名（如「下单时间」），让读屏知道这个时间是什么
+}

packages/skin/ui/ua.manifest.json

@@ -96,7 +96,8 @@
       "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
       "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮",
       "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）",
-      "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁"
+      "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁",
+      "relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -4259,6 +4260,46 @@
           "遮罩文案写明在等什么（「正在刷新订单」），读屏同一句也会播报；只要转圈就省略 text",
           "内容可能为空时给 minHeight，否则高度塌成 0 遮罩无处可盖"
         ]
+      },
+      {
+        "id": "relativeTime",
+        "title": "相对时间 RelativeTime",
+        "demo": "sec-reltime",
+        "props": [
+          {
+            "n": "value",
+            "t": "string | number | Date",
+            "d": "目标时间：ISO 串 / 时间戳（10 位按秒、13 位按毫秒）/ Date"
+          },
+          {
+            "n": "refresh",
+            "t": "number",
+            "d": "自动刷新间隔（ms）；缺省 30000，传 0 不刷新"
+          },
+          {
+            "n": "threshold",
+            "t": "number",
+            "d": "超过该秒数改用绝对日期；缺省 7 天"
+          },
+          {
+            "n": "fallback",
+            "t": "string",
+            "d": "时间非法时的占位文案；缺省「—」"
+          },
+          {
+            "n": "ariaLabel",
+            "t": "string",
+            "d": "可访问名（如「下单时间」），让读屏知道这个时间是什么"
+          }
+        ],
+        "example": "relativeTime({ value: row.createdAt, ariaLabel: '下单时间' })",
+        "steps": [
+          "把后端给的时间原样交进来：ISO 串、10 位秒级戳、13 位毫秒戳、Date 都认，不用自己 new Date",
+          "默认每 30 秒刷新一次文案（「3 分钟前」会在不刷新页面的情况下变「4 分钟前」）；列表里条数极多时可把 refresh 调大或传 0",
+          "超过 7 天自动改显示绝对日期（YYYY-MM-DD HH:mm），想更早切换就调小 threshold",
+          "精确时间放在 title：鼠标悬停可看，不必为「想知道具体哪天」再点开详情",
+          "时间非法（空串 / 格式错）不猜也不抛，显示 fallback（缺省「—」），列表不会因一条脏数据空白"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -5779,3 +5779,10 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
   color: var(--ua-color-text-secondary);
   font-size: var(--ua-font-size-sm);
 }
+
+/* ---- 相对时间：文字色与正文一致，靠 title 提供精确值，不做下划线等「可点」暗示（它不可点） ---- */
+.ua-reltime {
+  color: inherit;
+  font-variant-numeric: tabular-nums; /* 等宽数字：列表里时间列不左右抖动 */
+  white-space: nowrap; /* 「3 分钟前」不该被折成两行 */
+}