Floating UI 在 Iframe 中使用 FloatingPortal 时的焦点顺序问题分析

问题背景

Floating UI 是一个流行的 JavaScript 库，用于创建浮动 UI 元素（如工具提示、弹出框等）。在实际应用中，开发者经常需要将 Floating UI 组件嵌入到 iframe 中，特别是在构建微前端架构或第三方小部件时。

核心问题

当 Floating UI 的 FloatingPortal 与 iframe 结合使用时，会出现键盘焦点顺序异常的问题。具体表现为：

1. 使用 initialFocus={-1} 配置时：

   • 打开弹出框后按 Tab 键，焦点不会移动到弹出框内的第一个可聚焦元素
   • 焦点会直接跳转到宿主页面的第一个可聚焦元素

2. 使用默认 initialFocus 配置时：

   • 虽然能正确聚焦到弹出框内的第一个元素
   • 但在遍历完弹出框内所有元素后，焦点不会回到 iframe 内的下一个元素
   • 而是跳转到宿主页面的第一个可聚焦元素

技术原因分析

问题的根源在于 Floating UI 的 tabbable 工具函数当前实现方式。该函数在查找可聚焦元素时，默认只在根文档(document)中搜索，而没有考虑 iframe 拥有独立文档上下文的特性。

当组件被放置在 iframe 中时，需要特别处理以下几点：

1. 文档上下文隔离：iframe 内的文档与主页面文档是隔离的，拥有各自的 DOM 树
2. 焦点范围限制：键盘导航应该限制在当前 iframe 文档范围内
3. 焦点循环逻辑：焦点在 iframe 内元素间的移动应该遵循 iframe 的 DOM 结构

解决方案建议

针对这个问题，开发者可以考虑以下几种解决方案：

1. 修改 tabbable 工具函数：

   • 增强函数以支持 iframe 文档上下文
   • 在查找可聚焦元素时，从当前组件所在的 document 开始搜索

2. 自定义焦点管理：

   • 实现自定义的 FloatingFocusManager
   • 明确指定焦点移动的范围和顺序

3. 上下文感知的 Portal 实现：

   • 确保 FloatingPortal 能感知 iframe 上下文
   • 自动将焦点管理限制在当前 iframe 内

最佳实践

在使用 Floating UI 与 iframe 结合时，建议遵循以下实践：

1. 明确指定 Portal 的容器为 iframe 内的元素
2. 为 iframe 内的 Floating UI 组件提供独立的焦点管理
3. 测试键盘导航在各种边界情况下的行为
4. 考虑使用 try-catch 包装可能跨文档的操作

总结

Floating UI 在 iframe 环境中的焦点管理问题是一个典型的跨文档上下文挑战。理解 iframe 的文档隔离特性是解决此类问题的关键。开发者需要特别注意组件在不同文档上下文中的行为差异，并采取适当的措施确保一致的用户体验。

随着微前端架构的普及，这类跨边界 UI 交互问题将变得越来越常见。前端开发者在设计可嵌入组件时，应该从一开始就考虑 iframe 集成场景，确保组件的可访问性和键盘导航行为符合预期。