本文介绍在 dom 根节点动态渲染 tooltip 时，如何通过编程式焦点控制与焦点流重定向，使浮层内容自然融入页面原有 tab 顺序，确保键盘用户获得符合预期的无障碍体验。
本文介绍在 dom 根节点动态渲染 tooltip 时，如何通过编程式焦点控制与焦点流重定向，使浮层内容自然融入页面原有 tab 顺序，确保键盘用户获得符合预期的无障碍体验。
在构建自定义 Tooltip/Popover 组件时，一个常见但易被忽视的可访问性挑战是：当浮层通过 React-Popper 或类似方案挂载到
或应用根节点（而非触发器附近）时，其内部可聚焦元素（如 Close 按钮、操作按钮）会脱离原始语义上下文，被插入到浏览器默认 Tab 顺序的末尾——导致用户按 Tab 键时，焦点从触发器直接跳转至页面最底部，再“绕回”后续内容，严重破坏导航连贯性。这不是样式或动画问题，而是焦点管理（Focus Management）的结构性缺陷。理想行为应是：
✅ 触发器获得焦点 → Tooltip 显示 → 焦点自动移入 Tooltip 内第一个可聚焦元素；
✅ 用户在 Tooltip 内 Tab 导航完毕（如到达 Close 按钮并回车关闭）→ 焦点无缝回归到触发器之后的下一个页面级可聚焦元素，而非跳转至文档末尾。
关键实现策略：焦点流劫持与恢复
核心思路不是“修改全局 Tab 顺序”（不可行），而是在 Tooltip 失焦（blur）瞬间，主动计算并接管焦点流向。具体分三步：
- Tooltip 显示时：立即将焦点设入其内部首个可聚焦元素（如 button[type="button"] 或 input），可通过 useEffect + ref.current?.focus() 实现；
-
Tooltip 隐藏前（blur 事件）：监听 Tooltip 容器的 blur 事件，在事件处理函数中：
- 定位触发器 DOM 元素（需持有 triggerRef）；
- 调用 findNextFocusableElement(triggerRef.current) 扫描 DOM，查找触发器后逻辑上“下一个”的可聚焦节点；
- 使用 setTimeout(..., 0) 或 requestAnimationFrame 延迟执行 .focus()，规避 React 渲染时机冲突；
- 关闭 Tooltip：在焦点转移完成后，更新状态隐藏浮层。
以下是精简可靠的 findNextFocusableElement 实现（兼容 Shadow DOM，支持 tabindex >= 0、表单控件、链接等）：
function findNextFocusableElement(startEl, direction = 'next') {
const focusableSelectors = [
'button:not([disabled])',
'input:not([disabled]):not([type="hidden"])',
'select:not([disabled])',
'textarea:not([disabled])',
'a[href]:not([disabled])',
'[tabindex]:not([tabindex="-1"]):not([disabled])'
].join(', ');
const allFocusables = Array.from(
document.querySelectorAll(focusableSelectors)
).filter(el =>
el.offsetParent !== null &&
getComputedStyle(el).visibility !== 'hidden' &&
getComputedStyle(el).display !== 'none'
);
const currentIndex = allFocusables.indexOf(startEl);
if (currentIndex === -1) return null;
const targetIndex = direction === 'next'
? currentIndex + 1
: currentIndex - 1;
return targetIndex >= 0 && targetIndex <p>对应 Tooltip 的 blur 处理逻辑如下：</p><pre class="brush:php;toolbar:false;">const handleTooltipBlur = () => {
if (!triggerRef.current) return;
const nextEl = findNextFocusableElement(triggerRef.current);
if (nextEl) {
// 延迟确保 DOM 更新完成
setTimeout(() => {
nextEl.focus();
setTooltipVisible(false);
}, 0);
}
};注意事项与最佳实践
- 避免 tabindex="0" 滥用：不要为 Tooltip 容器本身添加 tabindex="0"，这会额外插入一个无意义的 Tab 停靠点，加剧顺序混乱；
- 处理 ESC 键关闭：务必在 Tooltip 内监听 Escape 键，并在关闭前同步调用 triggerRef.current?.focus()，确保键盘用户能快速返回触发器；
- 测试真实 Tab 流：使用纯键盘（不依赖鼠标）遍历整个页面，验证：触发器 → Tooltip 内部 → 页面后续元素，是否形成线性闭环；
- 性能优化建议：对大型页面，可缓存 allFocusables 数组，并在 DOM 变更时（如 MutationObserver）增量更新，而非每次 blur 都全量扫描；
- ARIA 支持：为 Tooltip 添加 role="dialog"（若含交互）或 role="tooltip"，配合 aria-labelledby / aria-describedby 关联触发器，进一步提升屏幕阅读器体验。
通过以上方法，你无需重构 DOM 挂载位置，即可让动态浮层真正“融入”页面焦点流——既满足技术约束，又坚守 WCAG 2.1 中 “Focus Order”（2.4.3）与 “Keyboard”（2.1.1）的成功标准。
