弹窗打开后按 Tab,焦点跑回了背后的页面:4 个组件的焦点陷阱只做了一半

41 阅读9分钟

线上 0.2.11 版本,我用键盘打开「到期提醒」弹窗,然后按 Tab:焦点没有进入弹窗,还留在背后的触发按钮上。连按 4 次,只有 1 次碰巧走进面板,其余 3 次跑去了页面其它地方。

查下来,6 个弹层组件里 4 个只接了「Esc 关闭」,没接「焦点陷阱」。补完之后:Tab 3 次在面板内循环一圈,Esc 关闭后 13–34ms 焦点回到原处。

role="dialog" 只解决「读得出」,不解决「用得了」

一个弹层要能被键盘用,需要三件事同时成立:

条件作用缺了会怎样
role="dialog" + aria-modal="true"告诉读屏「这是一个模态层」读屏仍会念背后的内容
打开时把焦点移进面板键盘操作有落点用户要先 Tab 穿过后面的页面才够得着弹窗
Tab / Shift+Tab 在面板内循环不会跑出弹层焦点走到浏览器地址栏或背后的按钮
关闭后焦点还原回到原来的位置键盘用户丢失上下文,要重新从头 Tab

我核对了 6 个弹层组件:Dialog、Drawer 早就接好了焦点陷阱(useFocusTrap),而 MessageBox、ImagePreview、Tour、ActionSheet 只有 useEscapeStack。也就是说它们「能按 Esc 关」,但打开后焦点还留在触发按钮上。

这个问题在鼠标用户手里完全看不出来——鼠标点哪就是哪,不需要焦点。只有真的用键盘走一遍才会暴露。

实测:同一操作,修复前后

先看修复前(安装 0.2.11 的构建,红框是为了看清焦点位置加的观察描边,库本身样式没动):

0.2.11:弹窗已经打开,红色焦点框还在背后的「会员到期提醒」上

连按 Tab 的结果更说明问题:

0.2.11 连按 4 次 Tab:1 次碰巧进了面板,3 次跑到面板外

修复后同样的操作:

0.2.12:打开后焦点直接落在弹窗里的「确定」上

0.2.12:连续 Tab 始终停在面板内,不会跑到背后的页面

数字对照:

场景0.2.110.2.12
打开后焦点位置背后触发器面板内第一个可聚焦元素
4 次 Tab 落在面板内1/44/4
Tab 循环一圈无规律按可聚焦项数次 Tab 回到起点
Esc 后焦点原地不动还原到触发器(13–34ms)

源码:陷阱其实只有三段

useFocusTrap 的核心就三件事:收集可聚焦元素、在首尾之间拦截 Tab、关闭时还原。

export const FOCUSABLE_SELECTOR =
  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';

function onKeydown(event: KeyboardEvent) {
  if (event.key !== "Tab") return;
  const nodes = getFocusable();
  const first = nodes[0];
  const last = nodes[nodes.length - 1];
  if (event.shiftKey && activeEl === first) {
    event.preventDefault();
    last.focus();
  } else if (!event.shiftKey && activeEl === last) {
    event.preventDefault();
    first.focus();
  }
}

关键点是只拦首尾两个位置:焦点在中间时交给浏览器默认行为,它自己会走到下一个;只有从最后一个再往后、或从第一个往前时才 preventDefault() 手动跳。这样既不改浏览器正常的 Tab 顺序,也能覆盖「循环」这件事。

坑 1:缓存的列表会过期

最初的实现是这样的:

function trapFocusIn() {
  focusableNodes = Array.from(el.querySelectorAll(FOCUSABLE_SELECTOR)); // 只收集一次
  focusableNodes[0].focus();
}

打开时收集一次,之后 Tab 都用这份缓存。问题是弹层内容会变:

  • Tour 每一步的按钮数量可能不同(上一步/下一步/完成);
  • MessageBox 的 prompt 形态会多出一个输入框;
  • ActionSheet 的禁用项在打开后可能被业务改成可用。

缓存过期后,last 可能指向一个已经从 DOM 移除的按钮,Tab 就再也跳不出去了。所以改成每次 Tab 都重新收集——面板里最多几个元素,这点查询成本可以忽略。

坑 2:不可见节点混进了列表

选择器只排除了 disabled,没排除「看得见但不可聚焦」的情况:

  • 被 display: none 藏起来的按钮;
  • 在 aria-hidden="true" 容器里的元素(装饰性图标按钮);
  • 用 visibility: hidden 保留占位的元素。

这些元素能通过 querySelectorAll,focus() 却不会生效——于是「最后一个」永远聚焦不上,Tab 在它前面就断了。

修法是加一层可见性过滤:

return Array.from(el.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter((node) => {
  if (node.hidden) return false;
  if (node.closest('[aria-hidden="true"]')) return false;
  const check = (node as HTMLElement & { checkVisibility?: (o?: object) => boolean }).checkVisibility;
  return typeof check === "function"
    ? check.call(node, { visibilityProperty: true, displayProperty: true, contentVisibilityAuto: true })
    : true;
});

checkVisibility() 能识别祖先的 display: none,但 jsdom 没有这个 API,所以保留了「没有就按可见处理」的降级——否则单测里所有按钮都会被过滤掉,测试假绿。

坑 3:焦点可能已经在容器外

还有一种路径:弹层开着,用户点了地址栏又点回页面,此时 document.activeElement 是 body。再按 Tab,浏览器会从文档开头重新走一遍——直接穿过弹层背后的内容。

原来的代码只在「焦点恰好是第一个或最后一个」时拦截,这种情况完全没管。补一条兜底:

if (!activeEl || !el.contains(activeEl)) {
  event.preventDefault();
  (event.shiftKey ? last : first).focus();
  return;
}

只要焦点不在面板里,下一次 Tab 就把它拉回面板。

我以为是 A,实测是 B

第一处:我以为「0.2.11 的问题是 Tab 完全进不了面板」。

实测 4 次 Tab 的结果是 [面板外, 面板内, 面板外, 面板外]——有 1 次碰巧进去了。原因很朴素:弹层的 DOM 在 body 末尾,如果触发按钮后面的页面元素刚好结束,Tab 会顺势走进 teleport 出来的弹层。

这比「完全进不去」更隐蔽:随便试两下,看起来是能用的,只有走到面板最后一个按钮再按 Tab,才会发现焦点跑回了页面。

第二处:我以为「关闭后焦点还原是同步的,耗时 0」。

用页内 performance.now() 量了 4 次,实际是 13.4ms / 17.5ms / 21.3ms / 34.3ms。因为还原要经过一条链:

Esc 键 → useEscapeStack 回调 → close() → emit update:modelValue
→ 父级更新 props → watch(active) 触发 → restoreFocus()

每一环都是一次微任务/渲染帧,加起来就是十几毫秒。对用户无感,但它解释了为什么「关闭动画还没结束,焦点就已经回去了」——两者不是同一个时机,动画是 CSS transition,焦点是 Vue 的 watch。

第三处:我以为「应该等打开动画结束再把焦点移进去」。

实测焦点在 5.8–14ms 就进入面板,而 rn-zoom 的进场过渡是 --rn-duration-normal,也就是 200ms——焦点比动画早一个数量级。一开始担心「聚焦到还没显示完的元素上会不会失效」,实测不会:focus() 只要求元素在 DOM 里、可聚焦,动画中的 transform 与 opacity 不影响它。

反过来推演:如果等 transitionend 再聚焦,键盘用户在这 200ms 内按下的 Tab/Enter 会落到 body 上——弹窗看起来还没出现,输入已经丢了。所以「立即聚焦」不是偷懒,是必要的。

Esc 栈:为什么不能每个组件自己监听

如果每个弹层都各自 document.addEventListener("keydown", ...),那两层弹层同时打开时,一次 Esc 会把两层一起关掉——因为它们都在监听同一个 document。

所以 useEscapeStack 维护的是一个栈:打开时入栈,关闭时出栈,Esc 只调用栈顶的回调。实测「抽屉 + 提示框」两层:

两层叠加时按 Esc:只关掉最上面的提示框,抽屉还在,焦点回到抽屉的关闭按钮

数字:Esc 前 .rn-drawer: 1 / .rn-messagebox: 1;Esc 后 .rn-drawer: 1 / .rn-messagebox: 0,焦点落在 .rn-drawer__close 上。

焦点还原也配合了栈:提示框打开时,lastFocused 记的是抽屉里的按钮;它关闭时还原回去,而不是还原到页面顶部。两个机制(焦点陷阱、Esc 栈)必须是同一套栈序,否则会出现「关了提示框、焦点回到页面」的错位。

四个组件的落点实测

补上之后逐个用键盘走了一遍(Tab 进入、Tab 循环、Esc 还原):

组件面板内可聚焦打开后焦点Tab 顺序实测
MessageBox(alert)1确定确定 → 确定(5/5 不离开)
MessageBox(prompt)3输入框取消 → 确定 → 输入框
ImagePreview3关闭上一张 → 下一张 → 关闭
ActionSheet3第一项复制链接 → 取消 → 分享给朋友
Tour3关闭(×)跳过 → 下一步 → ×
Drawer1关闭关闭 → 关闭

MessageBox prompt:打开后焦点落在输入框,Tab 顺序为 取消 → 确定 → 输入框

ImagePreview:打开后焦点在关闭按钮上,轮播箭头在 Tab 顺序里

ActionSheet:打开后焦点在第一个操作项「分享给朋友」

Tour:打开后焦点在右上角关闭按钮

Drawer:面板里只有一个可聚焦元素(关闭按钮)

单按钮的 alert 值得单独说:可聚焦项只有 1 个,循环长度就是 1。测下来连续 5 次 Tab,5 次都留在同一个按钮上——看起来像「Tab 坏了」,其实是正确的:面板里没有第二个可以去的地方。

单按钮 alert:连续 5 次 Tab 都停在「确定」上,不会跑到地址栏

Esc 关闭后:焦点回到「单独打开提示框」,再按 Enter 可以直接重新打开

换成另一种实现会怎样

很自然的想法:用原生 <dialog>,showModal() 自带焦点陷阱和 Esc,为什么还要自己写?

推演一下代价:

方案能省掉什么代价
原生 <dialog showModal>焦点陷阱、Esc、背景 inert遮罩样式/动画要重做;多层 <dialog> 的栈序与现有 useEscapeStack 冲突;Safari 旧版行为差异
给背景加 inert阻止 Tab 进入背景不解决「面板内循环」与「关闭还原」;且要动态标记整棵兄弟树
继续用 composable——要自己维护焦点列表与还原点(本文这几个坑)

inert 是个好补充:它能从根上阻止背景被聚焦,比拦截 Tab 更彻底。但它不提供循环——焦点走到面板最后一个仍然会离开(到浏览器 UI),还是得自己拦。所以现在保留 composable,inert 留作后续增强。

验证:单测和真机各证明一半

新增 7 个用例(四个组件各 1–3 个),全量 875 个用例 / 104 个文件通过。但单测能证明的有限:

document.dispatchEvent(new KeyboardEvent("keydown", { key: "Tab" }));
expect(document.activeElement).toBe(firstButton);

dispatchEvent 只派发事件,不会触发浏览器的默认 Tab 行为。它能证明「处理函数把焦点移回了第一个」,不能证明「真实浏览器里焦点真的会在面板内循环」。

所以又去真机走了一遍:键盘聚焦触发器、Enter 打开、连续 Tab、Esc 关闭,每一步都读 document.activeElement 和 :focus-visible。上面那些数字全部来自真机,不是单测推断。

结论

弹层的键盘可用性不是「加了 role="dialog" 就完了」,而是三个独立机制的组合:

  1. 焦点移入:打开时给键盘一个落点;
  2. 焦点循环:首尾拦截,中间交给浏览器;
  3. 焦点还原:关闭后回到原处,且必须和 Esc 栈共用同一个顺序。

四个组件的问题都不是「写错了」,而是「只做了一半」——Esc 栈有了,焦点陷阱没有。这类缺口在鼠标操作下完全无感,只能靠键盘走一遍才发现。

自查:三步确认焦点陷阱真的生效

不用读源码,控制台里三步就能验证:

// 1) 打开弹层后,焦点在面板里吗
const panel = document.querySelector(".rn-messagebox");
panel.contains(document.activeElement);   // 期望 true

// 2) 把焦点放到面板最后一个可聚焦元素上,按一次 Tab
//    期望回到面板第一个元素,而不是页面其它地方

// 3) Esc 关闭后,焦点回到打开前的元素吗
//    期望 document.activeElement 是那个触发按钮

我这次就是先用这三步在 0.2.11 上看到第 1 步返回 false,才确认问题不在示例、而在组件。

ruanno-ui@0.2.12 已发布,文档站已同步(Playground 里可以自己按 Tab 试):

changelog:0.2.12 记录四个弹层的焦点陷阱修复


在线示例:ui.ruanno.top/components/… 源码:gitee.com/ruanno-top/…