线上 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 的构建,红框是为了看清焦点位置加的观察描边,库本身样式没动):
连按 Tab 的结果更说明问题:
修复后同样的操作:
数字对照:
| 场景 | 0.2.11 | 0.2.12 |
|---|---|---|
| 打开后焦点位置 | 背后触发器 | 面板内第一个可聚焦元素 |
| 4 次 Tab 落在面板内 | 1/4 | 4/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 前 .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 | 输入框 | 取消 → 确定 → 输入框 |
| ImagePreview | 3 | 关闭 | 上一张 → 下一张 → 关闭 |
| ActionSheet | 3 | 第一项 | 复制链接 → 取消 → 分享给朋友 |
| Tour | 3 | 关闭(×) | 跳过 → 下一步 → × |
| Drawer | 1 | 关闭 | 关闭 → 关闭 |
单按钮的 alert 值得单独说:可聚焦项只有 1 个,循环长度就是 1。测下来连续 5 次 Tab,5 次都留在同一个按钮上——看起来像「Tab 坏了」,其实是正确的:面板里没有第二个可以去的地方。
换成另一种实现会怎样
很自然的想法:用原生 <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" 就完了」,而是三个独立机制的组合:
- 焦点移入:打开时给键盘一个落点;
- 焦点循环:首尾拦截,中间交给浏览器;
- 焦点还原:关闭后回到原处,且必须和 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 试):