diff --git a/.ua/index.json b/.ua/index.json index d6ebd88..226d29c 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T14:56:09.624Z", + "generatedAt": "2026-10-26T14:58:51.630Z", "repoRoot": ".", "packages": [ { @@ -224,7 +224,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", @@ -4347,6 +4348,46 @@ "需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」", "禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页" ] + }, + { + "id": "loading", + "title": "区域加载遮罩 Loading", + "demo": "sec-loading", + "props": [ + { + "n": "active", + "t": "boolean | Signal", + "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 遮罩无处可盖" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index d9a754a..f6f78f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架 -- `packages/skin/ui`（@ui-arch/ui）：81 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：82 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private） - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 6b5f21b..98ffd4c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 81 个组件 + ui.css +│ │ └── ui/ # 82 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/README.md b/README.md index 18334f4..96cc54d 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全 npm run changelog # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移） ``` -## 组件（共 81 个） +## 组件（共 82 个） -accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · signaturePad · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark +accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · loading · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · signaturePad · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark -分组：表单（button / copyButton / signaturePad / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / codeBlock / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。 +分组：表单（button / copyButton / signaturePad / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / loading / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / codeBlock / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。 ## 可访问性约定 @@ -34,7 +34,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup |---|---| | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） | | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） | -| `packages/skin/ui` | @ui-arch/ui：81 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | +| `packages/skin/ui` | @ui-arch/ui：82 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） | | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server | | `apps/demo` | 交互演示（esbuild 打包成单文件） | diff --git a/apps/demo/main.ts b/apps/demo/main.ts index c146a51..48dc9f9 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -50,6 +50,7 @@ import { inputTag, grid, link, + loading, list, carousel, treeSelect, @@ -1795,6 +1796,23 @@ const content = h( return h('div', null, pad.el, h('div', { class: 'out' }, () => (sign() ? '已签字（dataURL 长度 ' + sign().length + '）' : '尚未签字'))); })(), ), + section( + 'sec-loading', + '区域加载遮罩', + 'loading：把要遮挡的块交进 children，active 为真时盖上遮罩；默认延迟 120ms 出场——接口快于这个时间就不闪，慢于它必有反馈。', + (() => { + const busy = signal(false); + const box = loading({ + active: busy, + text: '正在刷新订单', + minHeight: 120, + }, card({ title: '订单概览' }, typography({ variant: 'paragraph', type: 'secondary', content: '这里是一块会被整体刷新的内容：遮罩盖住时它仍在原位、只是变淡。' }))); + return h('div', { style: 'display:flex;flex-direction:column;gap:8px' }, + button({ label: '切换刷新状态', onClick: () => busy(!busy()) }), + box, + ); + })(), + ), ); // 悬浮按钮：fixed 定位，挂 body 不参与页面布局 diff --git a/llms-full.txt b/llms-full.txt index e67cab3..fbbb482 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T14:56:09.624Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T14:58:51.630Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -2315,6 +2315,32 @@ const pad = signaturePad({ value: sign, height: 140 }); mount('#box', () => pad. 现场演示：apps/docs/demo.html#sec-sign +### loading — 区域加载遮罩 Loading + +参数： + +- active：boolean | Signal —— 是否加载中：布尔直接置位，传信号则随状态显隐 +- text：string —— 遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」） +- delay：number —— 出场延迟（ms）；缺省 120，快请求不闪遮罩 +- spinnerSize：number —— 转圈直径（px）；缺省 20 +- minHeight：number —— 最小高度（px）；内容为空时兜住遮罩高度 + +示例： + +``` +loading({ active: busy, text: '正在刷新订单' }, dataTable({ ... })) +``` + +手把手： + +1. 把要遮挡的那块内容作为 children 交进来，active 传布尔或信号：刷新时盖上遮罩，数据回来后自动收起 +2. 内容不隐藏、只降透明度——布局与尺寸原地保留，遮罩收起时不会跳一下 +3. 默认延迟 120ms 出场：接口快于这个时间就不闪遮罩；想立刻显示传 delay: 0 +4. 遮罩文案写明在等什么（「正在刷新订单」），读屏同一句也会播报；只要转圈就省略 text +5. 内容可能为空时给 minHeight，否则高度塌成 0 遮罩无处可盖 + +现场演示：apps/docs/demo.html#sec-loading + API 速览： - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调 @@ -2400,6 +2426,7 @@ API 速览： - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计 - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮 - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty） +- loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁 一行用法： diff --git a/llms.txt b/llms.txt index bfbbda7..529f302 100644 --- a/llms.txt +++ b/llms.txt @@ -130,6 +130,7 @@ - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计 - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮 - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty） + - loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')` - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调 diff --git a/packages/skin/ui/src/index.ts b/packages/skin/ui/src/index.ts index c948cfa..b37887b 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -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'; diff --git a/packages/skin/ui/src/loading.ts b/packages/skin/ui/src/loading.ts new file mode 100644 index 0000000..aa43c18 --- /dev/null +++ b/packages/skin/ui/src/loading.ts @@ -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; +} diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index dc067ae..4f81da0 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -1069,3 +1069,12 @@ export interface SignaturePadHandle { toDataURL(): string; // 取当前签字 PNG dataURL（未签也返回空白图） isEmpty(): boolean; // 是否尚未落笔 } + +/*** 区域加载遮罩入参 ***/ +export interface LoadingProps { + active?: boolean | Signal; // 是否加载中：布尔直接置位，传信号则随状态显隐 + text?: string; // 遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」） + delay?: number; // 出场延迟（ms）；缺省 120，快请求不闪遮罩 + spinnerSize?: number; // 转圈直径（px）；缺省 20 + minHeight?: number; // 最小高度（px）；内容为空时兜住遮罩高度 +} diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 7e11510..ed5e457 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -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", + "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 遮罩无处可盖" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index 5f087d5..5c8456d 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -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); +}