本文介绍在 dom 根节点动态渲染 tooltip 时，如何保持语义化、可访问的焦点流：通过监听触发器失焦、主动查找并跳转至下一个逻辑焦点元素，确保键盘用户导航不跳过中间内容。
本文介绍在 dom 根节点动态渲染 tooltip 时，如何保持语义化、可访问的焦点流：通过监听触发器失焦、主动查找并跳转至下一个逻辑焦点元素，确保键盘用户导航不跳过中间内容。
在构建自定义 Tooltip/Popover 组件时，一个常见但易被忽视的可访问性挑战是：当 Tooltip 被挂载到
或 React Root 节点（而非触发器的 DOM 邻近位置）时，其内部可聚焦元素（如 Close 按钮、操作按钮）会脱离原始视觉与逻辑层级，导致 Tab 键导航出现“跳跃”——例如从触发按钮直接跳到页面末尾的某个链接，中间所有内容被绕过。这不仅违反 WCAG 2.4.3（Focus Order）原则，也破坏了屏幕阅读器用户的线性浏览体验。单纯在 Tooltip 显示时 .focus() 到首个按钮（如 closeBtn.focus()）仅解决了“进入 Tooltip”的问题，却未解决“退出 Tooltip 后该聚焦何处”的关键环节。
✅ 正确解法：动态恢复焦点链
核心思路是 将 Tooltip 视为触发器的逻辑延伸，而非孤立模态层。因此，当用户离开 Tooltip（例如按 Tab 离开最后一个按钮，或点击关闭），焦点不应“坠入文档末尾”，而应回归到视觉上紧邻触发器之后的下一个可聚焦元素——即原本 Tab 顺序中触发器之后的那个节点。
实现分三步：
- 监听 Tooltip 容器的 blur 事件（推荐委托至 Tooltip 根元素，避免为每个子按钮重复绑定）；
- 计算触发器（Trigger）在当前文档中的逻辑后继焦点元素；
- 延迟聚焦该元素，并同步隐藏 Tooltip（延迟用于规避浏览器焦点重置竞争）。
以下是一个健壮的 findNextFocusableElement 实现（兼容
function findNextFocusableElement(startEl) {
const allFocusables = Array.from(
document.querySelectorAll(
'button:not([disabled]), a[href]:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex="0"], [contenteditable="true"]'
)
);
const startIndex = allFocusables.indexOf(startEl);
if (startIndex === -1) return null;
// 从触发器之后开始查找第一个可聚焦元素
for (let i = startIndex + 1; i <p>在 Tooltip 组件中集成该逻辑：</p><pre class="brush:php;toolbar:false;">const handleTooltipBlur = () => {
if (!triggerRef.current) return;
const nextEl = findNextFocusableElement(triggerRef.current);
setTooltipVisible(false);
if (nextEl) {
// 使用 setTimeout 确保 DOM 更新完成且 Tooltip 已卸载
setTimeout(() => {
nextEl.focus();
}, 0);
} else {
// 安全兜底：聚焦回触发器
triggerRef.current.focus();
}
};
// Tooltip 根元素绑定 onBlur
<div ref="{tooltipRef}" onblur="{handleTooltipBlur}" tabindex="{-1}" blur tab>
{/* Tooltip 内容：Close 按钮、操作项等 */}
<button onclick="{hide}">Close</button>
<button>Confirm</button>
</div>⚠️ 关键注意事项
- 不要依赖 document.activeElement 在 blur 中判断来源：blur 事件触发时，焦点可能已移至新元素或 body，状态不可靠；
- 避免硬编码 tabIndex 顺序：DOM 动态变化（如 SPA 路由切换、条件渲染）会使预设索引失效；
- 移动端与键盘导航需一致：此方案对键盘 Tab 和屏幕阅读器的虚拟光标均有效，但需额外测试 VoiceOver/NVDA 的读取顺序；
- 性能优化建议：对大型页面，可缓存 allFocusables 数组并在 DOM 变更时（如 MutationObserver）增量更新，而非每次重新查询。
通过该方案，Tooltip 不再是焦点流的“黑洞”，而是成为触发器自然延伸的一部分——用户从按钮 Tab 进入 Tooltip，再 Tab 离开时，无缝抵达下一个业务相关控件，真正实现无障碍优先的交互设计。
