MUI Base UI 中 Safari 浏览器下 Tooltip 组件焦点显示问题解析

问题背景

在 MUI Base UI 项目中，Tooltip 组件在 Safari 浏览器中存在一个特殊的显示问题。当用户通过键盘操作（如 Tab 键）聚焦到带有 Tooltip 的元素时，Tooltip 可能会在不应该显示的情况下弹出。这个问题主要源于 Safari 浏览器对 CSS 伪类 :focus-visible 的支持存在缺陷。

技术原理

:focus-visible 是一个 CSS 伪类，用于区分元素是通过键盘操作（需要视觉反馈）还是鼠标点击（可能不需要视觉反馈）获得的焦点。现代浏览器通常能正确区分这两种交互方式，但 Safari 的实现存在一些特殊情况。

在底层实现上，MUI Base UI 使用了 Floating UI 库来处理 Tooltip 的定位和显示逻辑。Floating UI 为了兼容 Safari，实现了一个 polyfill（兼容性补丁）来检测 :focus-visible 状态。这个 polyfill 依赖于 keyboardModalityRef.current 这个标志位来判断当前是否是键盘操作。

问题根源

问题的核心在于 Safari 的特殊行为：

1. 在页面初始加载时，keyboardModalityRef.current 默认被设置为 true
2. 这个标志位只有在检测到 onPointerDown 事件（通常是鼠标/触摸操作）时才会被设置为 false
3. 在某些场景下（比如对话框中的第一个可聚焦元素），用户可能直接通过键盘聚焦，但浏览器尚未触发任何指针事件

这就导致了 Tooltip 在不恰当的时机显示出来，因为系统错误地认为当前是键盘操作模式。

解决方案与变通方法

目前项目中有以下几种处理方式：

1. 临时解决方案：在对话框等场景中，将初始焦点(initialFocus)设置在：

   • 没有 Tooltip 的元素上
   • 或者直接设置在弹出框本身

2. 长期解决方案：需要修改 Floating UI 库中的相关实现，可能的方向包括：

   • 移除或改进现有的 polyfill
   • 实现更可靠的焦点检测机制
   • 针对 Safari 的特殊情况进行专门处理

开发者建议

对于使用 MUI Base UI 的开发者，如果遇到此问题：

1. 在 Safari 环境下特别注意 Tooltip 的显示行为
2. 在对话框等需要键盘导航的场景中，谨慎设置初始焦点
3. 关注项目更新，等待官方修复方案

这个问题虽然不会影响功能，但会影响用户体验，特别是在强调无障碍访问的场景下。开发者应当根据实际需求选择适当的临时解决方案，或者等待官方修复。