From abfbb821b76c9b526297fe0d90025ec9bcf17009 Mon Sep 17 00:00:00 2001 From: HIsheR Date: Mon, 26 Oct 2026 13:51:40 +0800 Subject: [PATCH] =?UTF-8?q?iter(g102):=20=E7=84=A6=E7=82=B9=E9=99=B7?= =?UTF-8?q?=E9=98=B1=E4=B8=8B=E6=B2=89=E4=B8=BA=E5=85=B1=E4=BA=AB=E5=8A=A9?= =?UTF-8?q?=E6=89=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/backlog.json | 8 ++++++++ packages/skin/ui/src/drawer.ts | 18 ++---------------- packages/skin/ui/src/image.ts | 6 ++++-- packages/skin/ui/src/modal.ts | 18 ++---------------- packages/skin/ui/src/overlay.ts | 21 +++++++++++++++++++++ 5 files changed, 37 insertions(+), 34 deletions(-) diff --git a/.ua/backlog.json b/.ua/backlog.json index 33b3ab9..bef09ee 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -1172,6 +1172,14 @@ "acceptance": "新增 anchor(props)（packages/skin/ui/src/anchor.ts，< 200 行）：items/href/title/disabled、offset 偏移量、container 内滚容器、onChange 回调；滚动按目标位置高亮并同步 aria-current，点击平滑定位 + replaceState 回写 hash，prefers-reduced-motion 下瞬移；types/manifest/index/ui.css/demo/README/AGENTS/ARCHITECTURE 同步，npm run check 全绿", "notes": "自补：组件补充；样式全走令牌，选出态维持低视觉比重（accent 10% 底色 + 左侧 2px 指示条）", "status": "done" + }, + { + "id": "g102", + "title": "焦点陷阱下沉为共享助手，图片预览接上", + "motivation": "modal 与 drawer 各自复制了一份 25 行的 Tab 焦点陷阱（focusables + keydown 环形回绕），改一处漏一处；image 的全屏预览层是 role=dialog aria-modal，却完全没有焦点陷阱也没把焦点移进去，键盘用户 Tab 一下就穿到背后的页面", + "acceptance": "overlay.ts 新增 trapFocus(box, isOpen)：Tab / Shift+Tab 首尾环形，有无可用焦点与焦点在容器外的两种情况都拦回；modal / drawer 删掉本地实现改为调用（行为不变）；image 预览层补 tabindex=-1 + 打开即聚焦 + 全程锁焦点；npm run check 全绿", + "notes": "自补：一致性与无障碍；陷阱实现单一来源，后续新增模态层直接复用", + "status": "open" } ] } diff --git a/packages/skin/ui/src/drawer.ts b/packages/skin/ui/src/drawer.ts index 3c4f77e..b588a3e 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 { lockScroll, pushOverlay } from './overlay.js'; +import { lockScroll, pushOverlay, trapFocus } from './overlay.js'; let seq = 0; // 实例序号：给标题生成唯一 id，供 aria-labelledby 关联 @@ -38,9 +38,6 @@ 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')); // 面板内可聚焦元素（排除禁用） effect(() => { if (props.open()) { lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点 @@ -56,17 +53,6 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement lastFocus = null; } }); - overlay.addEventListener('keydown', (e: KeyboardEvent) => { - if (e.key !== 'Tab' || !props.open()) return; // 仅处理打开中的 Tab - const els = focusables(); - if (els.length === 0) { e.preventDefault(); return; } // 无可聚焦元素：拦截 Tab 防焦点逃逸 - const first = els[0]; - const last = els[els.length - 1]; - if (e.shiftKey && (document.activeElement === first || !panel.contains(document.activeElement))) { - e.preventDefault(); last.focus(); // Shift+Tab 到首位时回绕到末尾 - } else if (!e.shiftKey && (document.activeElement === last || !panel.contains(document.activeElement))) { - e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头 - } - }); + trapFocus(panel, () => props.open()); // Tab 焦点陷阱：与 modal 共用同一份实现 return overlay; } diff --git a/packages/skin/ui/src/image.ts b/packages/skin/ui/src/image.ts index 39e94d5..d66ce27 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 { lockScroll, pushOverlay } from './overlay.js'; +import { lockScroll, pushOverlay, trapFocus } from './overlay.js'; import type { ImageProps } from './types.js'; /*** 图片：缩略图展示，点击 / 回车打开遮罩大图预览（Esc 或点击遮罩关闭），加载失败自动落占位；样式只消费 --ua-* 令牌 ***/ @@ -30,7 +30,7 @@ function openViewer(src: string, alt?: string): void { const prev = document.activeElement as HTMLElement | null; // 焦点归还目标 const mask = h( 'div', - { class: 'ua-image-mask', role: 'dialog', 'aria-modal': 'true', 'aria-label': '图片预览' }, + { class: 'ua-image-mask', role: 'dialog', 'aria-modal': 'true', 'aria-label': '图片预览', tabindex: '-1' }, h('img', { class: 'ua-image-full', src, alt: alt ?? '' }), ); const close = () => { @@ -41,5 +41,7 @@ function openViewer(src: string, alt?: string): void { }; mask.addEventListener('click', close); releaseEsc = pushOverlay(close); // 入 Esc 栈：预览层压在最上面，Esc 先关它 + trapFocus(mask, () => true); // 预览层常开：Tab 全程锁在遮罩内（层内无控件，等于整体拦截） document.body.appendChild(mask); + mask.focus(); // 焦点移入预览层，读屏与键盘都不再落在背后的页面 } diff --git a/packages/skin/ui/src/modal.ts b/packages/skin/ui/src/modal.ts index 3abb770..a3b2795 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 { lockScroll, pushOverlay } from './overlay.js'; +import { lockScroll, pushOverlay, trapFocus } from './overlay.js'; let seq = 0; // 实例序号：给标题生成唯一 id，供 aria-labelledby 关联 @@ -31,9 +31,6 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { 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')); // 弹窗内可聚焦元素（排除禁用） effect(() => { const open = props.open(); overlay.classList.toggle('ua-open', open); // 显隐跟随信号 @@ -51,17 +48,6 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement { lastFocus = null; } }); - overlay.addEventListener('keydown', (e: KeyboardEvent) => { - if (e.key !== 'Tab' || !props.open()) return; // 仅处理打开中的 Tab - const els = focusables(); - if (els.length === 0) { e.preventDefault(); return; } // 无可聚焦元素：拦截 Tab 防焦点逃逸 - const first = els[0]; - const last = els[els.length - 1]; - if (e.shiftKey && (document.activeElement === first || !box.contains(document.activeElement))) { - e.preventDefault(); last.focus(); // Shift+Tab 到首位时回绕到末尾 - } else if (!e.shiftKey && (document.activeElement === last || !box.contains(document.activeElement))) { - e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头 - } - }); + trapFocus(box, () => props.open()); // Tab 焦点陷阱：与 drawer 共用同一份实现 return overlay; } diff --git a/packages/skin/ui/src/overlay.ts b/packages/skin/ui/src/overlay.ts index 3975024..8d3bc38 100644 --- a/packages/skin/ui/src/overlay.ts +++ b/packages/skin/ui/src/overlay.ts @@ -65,3 +65,24 @@ export function lockScroll(): () => void { if (locks === 0) document.body.style.overflow = ''; // 全关解锁 }; } + +/*** 焦点陷阱：Tab / Shift+Tab 在容器内首尾环形循环，容器内无可用焦点时整体拦截；焦点已在容器外则按方向拉回首尾 ***/ +export function trapFocus(box: HTMLElement, isOpen: () => boolean): void { + box.addEventListener('keydown', (e: KeyboardEvent) => { + if (e.key !== 'Tab' || !isOpen()) return; // 卫语句：只处理打开中的 Tab + const els = Array.from(box.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')) + .filter((el) => !el.hasAttribute('disabled')); // 容器内可聚焦元素（排除禁用） + if (!els.length) { e.preventDefault(); return; } // 卫语句：无可用焦点就整体拦截，防焦点逃逸 + const first = els[0]; + const last = els[els.length - 1]; + const active = document.activeElement; + const outside = !box.contains(active); // 焦点落在容器外：按方向重新拉回，而不是让它继续往外跑 + if (e.shiftKey && (active === first || outside)) { + e.preventDefault(); + last.focus(); // Shift+Tab 到首位回绕到末尾 + } else if (!e.shiftKey && (active === last || outside)) { + e.preventDefault(); + first.focus(); // Tab 到末位回绕到开头 + } + }); +}