From d80e132a45010e8fedf1bae035a1e861ccce7707 Mon Sep 17 00:00:00 2001 From: HIsheR Date: Mon, 26 Oct 2026 11:37:45 +0800 Subject: [PATCH] =?UTF-8?q?iter(g27):=20=E6=8A=BD=E5=87=BA=E5=BC=B9?= =?UTF-8?q?=E5=B1=82=20Esc=20=E6=A0=88=EF=BC=8C=E5=A4=9A=E5=BC=B9=E5=B1=82?= =?UTF-8?q?=E5=8F=AA=E5=85=B3=E6=9C=80=E4=B8=8A=E5=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/backlog.json | 8 ++++++++ .ua/index.json | 9 +++++---- llms-full.txt | 7 ++++--- packages/skin/ui/src/drawer.ts | 12 +++++++----- packages/skin/ui/src/modal.ts | 12 +++++++----- packages/skin/ui/src/overlay.ts | 32 +++++++++++++++++++++++++++++++ packages/skin/ui/ua.manifest.json | 7 ++++--- 7 files changed, 67 insertions(+), 20 deletions(-) create mode 100644 packages/skin/ui/src/overlay.ts diff --git a/.ua/backlog.json b/.ua/backlog.json index c2a953e..18678cb 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -572,6 +572,14 @@ "acceptance": "var(--ua-*) 必须是 tokens.css 已定义或组件自设变量，否则 verify 失败；ua tokens / llms-full 令牌清单统一取 tokens.css（补全字号与复合间距）；npm run check 全绿", "status": "done", "notes": "自补：门禁改进；负向测试 var(--ua-color-textt) 已被拦截" + }, + { + "id": "g27", + "title": "弹层 Esc 栈：多弹层只关最上层", + "motivation": "modal 与 drawer 各自往 document 挂 keydown，叠加打开时一次 Esc 会把所有弹层全关；实例销毁也不摘监听", + "acceptance": "modal/drawer 共用 overlay.ts 的 Esc 栈，后开先关；栈空自动摘全局监听；npm run check 全绿", + "status": "open", + "notes": "自补：既有组件可用性细节" } ] } diff --git a/.ua/index.json b/.ua/index.json index 597ca78..b974af7 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T03:34:43.829Z", + "generatedAt": "2026-10-26T03:37:32.721Z", "repoRoot": ".", "packages": [ { @@ -1399,9 +1399,10 @@ "steps": [ "创建布尔信号 open = signal(false)，弹窗初始隐藏", "把 open 传给 modal，其余参数为弹窗内容子节点", - "打开：open(true)；关闭：open(false)，点遮罩或 × 会自动写回 false", + "打开：open(true)；关闭：open(false)，点遮罩、× 或 Esc 会自动写回 false；多弹层叠加时 Esc 只关最上层（后开先关）", "入场自带遮罩淡入 + 弹窗上浮动画", - "底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm'" + "底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm'", + "打开后 Tab 焦点锁在弹窗内，关闭自动把焦点还给打开前的元素" ] }, { @@ -1454,7 +1455,7 @@ "steps": [ "创建布尔信号 open = signal(false)，传给 drawer；其余参数为面板内容子节点", "打开后从侧边滑出：placement: 'right'（默认）或 'left'，width 控制宽度（窄屏自动收到 92vw）", - "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素", + "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素，Esc 只关最上层弹层", "底部操作按钮放进 footer；与 modal 的分工：modal 是强打断的确认，drawer 保留主视图上下文做详情/编辑", "面板内容与 modal 一样接受任意 DOM 与响应式函数" ] diff --git a/llms-full.txt b/llms-full.txt index c063901..8fd7a0c 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T03:34:43.829Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T03:37:32.721Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -797,9 +797,10 @@ const open = signal(false); modal({ title: '确认操作', open, onClose: () => 1. 创建布尔信号 open = signal(false)，弹窗初始隐藏 2. 把 open 传给 modal，其余参数为弹窗内容子节点 -3. 打开：open(true)；关闭：open(false)，点遮罩或 × 会自动写回 false +3. 打开：open(true)；关闭：open(false)，点遮罩、× 或 Esc 会自动写回 false；多弹层叠加时 Esc 只关最上层（后开先关） 4. 入场自带遮罩淡入 + 弹窗上浮动画 5. 底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm' +6. 打开后 Tab 焦点锁在弹窗内，关闭自动把焦点还给打开前的元素 现场演示：apps/docs/demo.html#sec-tabs-modal @@ -825,7 +826,7 @@ const open = signal(false); drawer({ title: '详情', open, width: 360, onClose: 1. 创建布尔信号 open = signal(false)，传给 drawer；其余参数为面板内容子节点 2. 打开后从侧边滑出：placement: 'right'（默认）或 'left'，width 控制宽度（窄屏自动收到 92vw） -3. 点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素 +3. 点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素，Esc 只关最上层弹层 4. 底部操作按钮放进 footer；与 modal 的分工：modal 是强打断的确认，drawer 保留主视图上下文做详情/编辑 5. 面板内容与 modal 一样接受任意 DOM 与响应式函数 diff --git a/packages/skin/ui/src/drawer.ts b/packages/skin/ui/src/drawer.ts index 3234e57..c9be368 100644 --- a/packages/skin/ui/src/drawer.ts +++ b/packages/skin/ui/src/drawer.ts @@ -1,5 +1,6 @@ import { effect, h } from '@ui-arch/frame'; import type { DrawerProps } from './types.js'; +import { pushOverlay } from './overlay.js'; /*** 抽屉：open 信号驱动侧滑面板，点遮罩 / × / Esc 关闭；Tab 焦点陷阱 + 关闭归还焦点，与 modal 的分工是不打断主视图、可从侧边保留上下文 ***/ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement { @@ -29,15 +30,19 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement overlay.append(panel); let lastFocus: HTMLElement | null = null; // 打开前焦点宿主，关闭时归还 + let release: (() => void) | null = null; // Esc 栈注销函数，关闭时释放 const focusables = (): HTMLElement[] => Array.from(panel.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')) .filter((el) => !el.hasAttribute('disabled')); // 面板内可聚焦元素（排除禁用） effect(() => { if (props.open()) { lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点 + release ??= pushOverlay(close); // 入 Esc 栈：多弹层时只关最上层 (panel.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素 - } else if (lastFocus) { - lastFocus.focus(); // 关闭时归还焦点 + } else { + release?.(); // 出 Esc 栈 + release = null; + lastFocus?.focus(); // 关闭时归还焦点 lastFocus = null; } }); @@ -53,8 +58,5 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头 } }); - document.addEventListener('keydown', (e: KeyboardEvent) => { - if (e.key === 'Escape' && props.open()) close(); - }); return overlay; } diff --git a/packages/skin/ui/src/modal.ts b/packages/skin/ui/src/modal.ts index 19f79ed..47df6f2 100644 --- a/packages/skin/ui/src/modal.ts +++ b/packages/skin/ui/src/modal.ts @@ -1,5 +1,6 @@ import { effect, h } from '@ui-arch/frame'; import type { ModalProps } from './types.js'; +import { pushOverlay } from './overlay.js'; /*** 弹窗：open 信号驱动显隐，点遮罩、× 或 Esc 触发 onClose；Tab 焦点陷阱 + 关闭归还焦点 ***/ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { @@ -23,6 +24,7 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { ); overlay.append(box); let lastFocus: HTMLElement | null = null; // 打开前焦点宿主，关闭时归还 + let release: (() => void) | null = null; // Esc 栈注销函数，关闭时释放 const focusables = (): HTMLElement[] => Array.from(box.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')) .filter((el) => !el.hasAttribute('disabled')); // 弹窗内可聚焦元素（排除禁用） @@ -31,9 +33,12 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { overlay.classList.toggle('ua-open', open); // 显隐跟随信号 if (open) { lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点 + release ??= pushOverlay(close); // 入 Esc 栈：多弹层时只关最上层 (box.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素 - } else if (lastFocus) { - lastFocus.focus(); // 关闭时归还焦点 + } else { + release?.(); // 出 Esc 栈 + release = null; + lastFocus?.focus(); // 关闭时归还焦点 lastFocus = null; } }); @@ -49,8 +54,5 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头 } }); - document.addEventListener('keydown', (e: KeyboardEvent) => { - if (e.key === 'Escape' && props.open()) close(); // Esc 关闭当前打开的弹窗 - }); return overlay; } diff --git a/packages/skin/ui/src/overlay.ts b/packages/skin/ui/src/overlay.ts new file mode 100644 index 0000000..13c20ae --- /dev/null +++ b/packages/skin/ui/src/overlay.ts @@ -0,0 +1,32 @@ +/*** 弹层键盘栈：维护打开顺序，Esc 只关最上层，避免多个弹层（含嵌套）被一次全关 ***/ + +// —— 状态集中声明 —— +const stack: { close: () => void }[] = []; // 打开中的弹层，后进先出 +let bound = false; // 全局 keydown 监听只挂一次，栈空时摘除 + +/*** 全局 Esc 分发：只把事件交给栈顶弹层，其余保持不动 ***/ +const onKeydown = (e: KeyboardEvent) => { + if (e.key !== 'Escape') return; // 卫语句：只关心 Esc + const top = stack[stack.length - 1]; + if (!top) return; // 卫语句：栈空无事可做 + e.preventDefault(); + top.close(); +}; + +/*** 注册一个打开的弹层，返回注销函数（弹层关闭时务必调用，否则栈不清理） ***/ +export function pushOverlay(close: () => void): () => void { + if (!bound) { + document.addEventListener('keydown', onKeydown); // 首个弹层才挂全局监听 + bound = true; + } + const entry = { close }; + stack.push(entry); + return () => { + const i = stack.indexOf(entry); + if (i >= 0) stack.splice(i, 1); // 出栈：允许非栈顶关闭 + if (!stack.length && bound) { + document.removeEventListener('keydown', onKeydown); // 栈空摘监听，避免泄漏 + bound = false; + } + }; +} diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 67a7555..b529bd3 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -1270,9 +1270,10 @@ "steps": [ "创建布尔信号 open = signal(false)，弹窗初始隐藏", "把 open 传给 modal，其余参数为弹窗内容子节点", - "打开：open(true)；关闭：open(false)，点遮罩或 × 会自动写回 false", + "打开：open(true)；关闭：open(false)，点遮罩、× 或 Esc 会自动写回 false；多弹层叠加时 Esc 只关最上层（后开先关）", "入场自带遮罩淡入 + 弹窗上浮动画", - "底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm'" + "底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm'", + "打开后 Tab 焦点锁在弹窗内，关闭自动把焦点还给打开前的元素" ] }, { @@ -1325,7 +1326,7 @@ "steps": [ "创建布尔信号 open = signal(false)，传给 drawer；其余参数为面板内容子节点", "打开后从侧边滑出：placement: 'right'（默认）或 'left'，width 控制宽度（窄屏自动收到 92vw）", - "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素", + "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素，Esc 只关最上层弹层", "底部操作按钮放进 footer；与 modal 的分工：modal 是强打断的确认，drawer 保留主视图上下文做详情/编辑", "面板内容与 modal 一样接受任意 DOM 与响应式函数" ]