正确管理 Tooltip 焦点顺序提升可访问性

本文深入探讨了在 React 中实现自定义 Tooltip 组件时如何精准管理焦点顺序，以保障键盘用户和屏幕阅读器使用者的无障碍体验：通过动态计算触发元素后的下一个可聚焦节点、在 Tooltip 关闭时用零延迟 setTimeout 安全移交焦点，并规避常见陷阱（如误用 activeElement 或 requestAnimationFrame），让脱离 DOM 原位渲染的 Tooltip 完全融入页面原生 Tab 流，既不打断操作连贯性，也不破坏语义结构，真正实现符合 WCAG 2.1 和 WAI-ARIA 最佳实践的专业级可访问性。

本文介绍在 React 中实现自定义 Tooltip 组件时，如何通过动态计算焦点流、手动接管 focus 事件并合理延迟聚焦，使脱离 DOM 原位置渲染的 Tooltip 内容无缝融入页面默认 Tab 顺序，满足 WCAG 2.1 可访问性要求。

本文介绍在 React 中实现自定义 Tooltip 组件时，如何通过动态计算焦点流、手动接管 focus 事件并合理延迟聚焦，使脱离 DOM 原位置渲染的 Tooltip 内容无缝融入页面默认 Tab 顺序，满足 WCAG 2.1 可访问性要求。

在构建可访问的 UI 组件时，焦点管理（Focus Management）是核心挑战之一，尤其当组件（如 Tooltip、Popover、Modal）采用 Portal 方式挂载到 或根节点下时——其 DOM 位置与触发元素（Trigger）完全分离，导致浏览器原生 Tab 顺序断裂：用户从 Trigger 按 Tab 键后，焦点不会进入 Tooltip，而是跳转到页面中下一个全局可聚焦元素（如页脚链接），严重破坏操作流与屏幕阅读器体验。

根本解法不是“强行聚焦 Tooltip 内第一个按钮”（这会跳过中间元素），而是重建焦点逻辑链：当 Tooltip 关闭时，主动定位 Trigger 后的下一个自然可聚焦元素，并将焦点准确移交过去。这需要两个关键能力：

1. 精准识别 Tab 键预期的下一个焦点目标；
2. 在 DOM 更新完成、React 渲染同步后安全触发 focus()。

以下为推荐实现方案（基于 React + React-Popper）：

✅ 正确的焦点恢复逻辑

// 工具函数：查找指定元素后的下一个可聚焦元素（按文档顺序）
function findNextFocusableElement(
  startEl: HTMLElement,
  root: Document | ShadowRoot = document
): HTMLElement | null {
  const allFocusables = Array.from(
    root.querySelectorAll<HTMLElement>(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    )
  ).filter(el => 
    el.offsetParent !== null && 
    getComputedStyle(el).visibility !== 'hidden' &&
    getComputedStyle(el).display !== 'none'
  );

  const startIndex = allFocusables.indexOf(startEl);
  return startIndex >= 0 && startIndex + 1 < allFocusables.length
    ? allFocusables[startIndex + 1]
    : null;
}

// Tooltip 组件内事件处理
const handleTooltipBlur = () => {
  if (!triggerRef.current) return;

  const nextEl = findNextFocusableElement(triggerRef.current);
  if (nextEl) {
    // 使用 setTimeout 确保 React 完成状态更新 & DOM 重排
    // 避免因异步渲染导致 focus 失效（常见于 Portal 挂载/卸载场景）
    setTimeout(() => {
      nextEl.focus({ preventScroll: true });
    }, 0);
  }
  setTooltipVisible(false);
};

⚠️ 关键注意事项

• 不要依赖 document.activeElement 在 blur 事件中判断：此时焦点可能尚未转移，或已被浏览器抢占；
• 避免 requestAnimationFrame 替代 setTimeout：RAF 不保证 DOM 更新完成，尤其在 SSR 或 Suspense 场景下更不可靠；
• preventScroll: true 是必要选项：防止聚焦时意外滚动页面，影响键盘用户上下文感知；
• 需监听 keydown 补充 Escape 支持：当用户按 Esc 关闭 Tooltip 时，同样应恢复至 Trigger 后的下一个元素（而非回退到 Trigger 自身）；
• 对无序列表/动态内容需增强健壮性：若页面存在大量动态插入节点，建议缓存焦点序列或使用 MutationObserver 监听变化后重新索引。

? 总结

浮动 Tooltip 的焦点可访问性不在于“让 Tooltip 被 Tab 到”，而在于确保它出现和消失都不打断原有焦点流。通过主动计算 trigger → tooltip → nextElement 的闭环路径，并用零延迟 setTimeout 安全移交焦点，即可在不修改第三方页面结构的前提下，实现符合 WAI-ARIA Authoring Practices 的专业级交互体验。最终效果：用户从 Trigger Tab 进入 Tooltip，再 Tab 即自然抵达页面中原本该出现的下一个控件——焦点秩序完整、语义清晰、无障碍友好。

到这里，我们也就讲完了《正确管理 Tooltip 焦点顺序提升可访问性》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！