temp/UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

iter(g27): 抽出弹层 Esc 栈，多弹层只关最上层

Browse Source
This commit is contained in:
HIsheR
2026-10-26 11:37:45 +08:00
parent c6ce184aeb
commit d80e132a45
7 changed files with 67 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ua/backlog.json
+8
View File
@@ -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": "自补：既有组件可用性细节"
}
]
}
.ua/index.json
+5 -4
View File
@@ -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 与响应式函数"
]
llms-full.txt
+4 -3
View File
@@ -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 与响应式函数
packages/skin/ui/src/drawer.ts
+7 -5
View File
@@ -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<HTMLElement>('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;
}
packages/skin/ui/src/modal.ts
+7 -5
View File
@@ -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<HTMLElement>('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;
}
packages/skin/ui/src/overlay.ts
+32
View File
@@ -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;
}
};
}
packages/skin/ui/ua.manifest.json
+4 -3
View File
@@ -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 与响应式函数"
]