diff --git a/.ua/backlog.json b/.ua/backlog.json index 7910c8b..3e46404 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -705,5 +705,7 @@ { "id": "g43", "title": "select/menu/popover/image 的 Esc 接入统一弹层栈", "motivation": "四个弹层组件各自监听 document 的 Esc:多层叠加(如 popover 内再开 image 预览)时一次 Esc 全部关闭,与 modal/drawer 的 pushOverlay 栈行为不一致", "acceptance": "四个组件展开期入 Esc 栈、收起即释放;多层叠加时 Esc 后进先出逐层关闭;焦点归还触发器;npm run check 全绿", "status": "done", "notes": "自补:一致性修复;复用 overlay.ts 的 pushOverlay 栈" } , { "id": "g44", "title": "accordion 标题行方向键导航", "motivation": "标题是原生 button 只有 Enter/Space,行间移动要靠 Tab 逐个跳,与 tabs/tree 的 ↑↓/Home/End 键盘约定不一致", "acceptance": "↑↓ 在标题行间环形移动、Home/End 首尾直达,均跳过禁用行;焦点不在标题行不拦截;npm run check 全绿", "status": "done", "notes": "自补:可达性对齐;复用环形回绕取模模式" } + , + { "id": "g45", "title": "modal/drawer/image 打开时锁定背景滚动", "motivation": "模态弹层开着时背景页面仍可滚动,长页面里滚动会带着遮罩底下内容跑;非模态弹层(select/menu/popover/tooltip)不受影响", "acceptance": "overlay.ts 新增 lockScroll 引用计数:嵌套叠加只由最后一层还原 body;modal/drawer/image 预览接入,关闭即解锁;npm run check 全绿", "status": "done", "notes": "自补:缺陷修复;引用计数避免多层同开时提前解锁" } ] } diff --git a/packages/skin/ui/src/drawer.ts b/packages/skin/ui/src/drawer.ts index c9be368..e1b8c41 100644 --- a/packages/skin/ui/src/drawer.ts +++ b/packages/skin/ui/src/drawer.ts @@ -1,6 +1,6 @@ import { effect, h } from '@ui-arch/frame'; import type { DrawerProps } from './types.js'; -import { pushOverlay } from './overlay.js'; +import { lockScroll, pushOverlay } from './overlay.js'; /*** 抽屉:open 信号驱动侧滑面板,点遮罩 / × / Esc 关闭;Tab 焦点陷阱 + 关闭归还焦点,与 modal 的分工是不打断主视图、可从侧边保留上下文 ***/ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement { @@ -31,6 +31,7 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement let lastFocus: HTMLElement | null = null; // 打开前焦点宿主,关闭时归还 let release: (() => void) | null = null; // Esc 栈注销函数,关闭时释放 + let releaseLock: (() => void) | null = null; // 背景滚动锁解锁函数,全关才还原 const focusables = (): HTMLElement[] => Array.from(panel.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')) .filter((el) => !el.hasAttribute('disabled')); // 面板内可聚焦元素(排除禁用) @@ -38,10 +39,13 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement if (props.open()) { lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点 release ??= pushOverlay(close); // 入 Esc 栈:多弹层时只关最上层 + releaseLock ??= lockScroll(); // 模态期锁背景滚动 (panel.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素 } else { release?.(); // 出 Esc 栈 release = null; + releaseLock?.(); // 解锁背景滚动 + releaseLock = null; lastFocus?.focus(); // 关闭时归还焦点 lastFocus = null; } diff --git a/packages/skin/ui/src/image.ts b/packages/skin/ui/src/image.ts index 4c0e650..39e94d5 100644 --- a/packages/skin/ui/src/image.ts +++ b/packages/skin/ui/src/image.ts @@ -1,5 +1,5 @@ import { h } from '@ui-arch/frame'; -import { pushOverlay } from './overlay.js'; +import { lockScroll, pushOverlay } from './overlay.js'; import type { ImageProps } from './types.js'; /*** 图片:缩略图展示,点击 / 回车打开遮罩大图预览(Esc 或点击遮罩关闭),加载失败自动落占位;样式只消费 --ua-* 令牌 ***/ @@ -26,6 +26,7 @@ export function image(props: ImageProps): HTMLElement { /*** 打开全屏遮罩预览层;关闭时自清理、解绑键盘并归还焦点 ***/ function openViewer(src: string, alt?: string): void { let releaseEsc: (() => void) | null = null; // Esc 栈注销函数:预览层占一层,关闭即释放 + const releaseLock = lockScroll(); // 预览期锁背景滚动 const prev = document.activeElement as HTMLElement | null; // 焦点归还目标 const mask = h( 'div', @@ -35,6 +36,7 @@ function openViewer(src: string, alt?: string): void { const close = () => { mask.remove(); // 自清理:遮罩移除 + 出 Esc 栈 + 焦点归还 releaseEsc?.(); + releaseLock(); prev?.focus?.(); }; mask.addEventListener('click', close); diff --git a/packages/skin/ui/src/modal.ts b/packages/skin/ui/src/modal.ts index 47df6f2..123e687 100644 --- a/packages/skin/ui/src/modal.ts +++ b/packages/skin/ui/src/modal.ts @@ -1,6 +1,6 @@ import { effect, h } from '@ui-arch/frame'; import type { ModalProps } from './types.js'; -import { pushOverlay } from './overlay.js'; +import { lockScroll, pushOverlay } from './overlay.js'; /*** 弹窗:open 信号驱动显隐,点遮罩、× 或 Esc 触发 onClose;Tab 焦点陷阱 + 关闭归还焦点 ***/ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { @@ -25,6 +25,7 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { overlay.append(box); let lastFocus: HTMLElement | null = null; // 打开前焦点宿主,关闭时归还 let release: (() => void) | null = null; // Esc 栈注销函数,关闭时释放 + let releaseLock: (() => void) | null = null; // 背景滚动锁解锁函数,全关才还原 const focusables = (): HTMLElement[] => Array.from(box.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')) .filter((el) => !el.hasAttribute('disabled')); // 弹窗内可聚焦元素(排除禁用) @@ -34,10 +35,13 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { if (open) { lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点 release ??= pushOverlay(close); // 入 Esc 栈:多弹层时只关最上层 + releaseLock ??= lockScroll(); // 模态期锁背景滚动 (box.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素 } else { release?.(); // 出 Esc 栈 release = null; + releaseLock?.(); // 解锁背景滚动 + releaseLock = null; lastFocus?.focus(); // 关闭时归还焦点 lastFocus = null; } diff --git a/packages/skin/ui/src/overlay.ts b/packages/skin/ui/src/overlay.ts index 13c20ae..bcde8ed 100644 --- a/packages/skin/ui/src/overlay.ts +++ b/packages/skin/ui/src/overlay.ts @@ -30,3 +30,16 @@ export function pushOverlay(close: () => void): () => void { } }; } + +// —— 背景滚动锁:模态弹层(modal/drawer/image 预览)引用计数,全关才解锁 —— +let locks = 0; // 活跃模态层数 + +/*** 模态层打开时调用,返回解锁函数;嵌套叠加时只由最外层还原 body 内联样式 ***/ +export function lockScroll(): () => void { + if (locks === 0) document.body.style.overflow = 'hidden'; // 第一层才锁,避免相互覆盖 + locks++; + return () => { + locks--; + if (locks === 0) document.body.style.overflow = ''; // 全关解锁 + }; +}