React onMouseEnter/onMouseLeave事件触发不稳定bug求助

DevOps 小满

2026-8-30

问题根因

这个问题不是React事件封装的bug，是浏览器原生事件机制+Portal渲染特性共同导致的：

浏览器mouseenter/mouseleave事件依赖UI线程的鼠标位置采样触发，当鼠标移动速度过快，两次采样间隔内鼠标直接跨过元素边界，就会出现离开事件漏触发的情况，这是原生层面的已知特性，和React无关。
通过Portal渲染的Tooltip默认挂载在body节点下，不属于触发元素的DOM子树，如果没有做额外的状态互斥、边界判断，快速划过时多个触发元素会依次触发进入事件，但对应的离开事件漏触发，最终就会残留多个同时展示的Tooltip面板。

排查步骤

先给onMouseEnter、onMouseLeave绑定控制台日志，快速滑动时确认是否只有进入事件打印、没有对应离开事件，先排除自身状态更新闭包、逻辑分支判断错误的问题。
检查Tooltip渲染的层级和位置，确认Tooltip弹出时有没有遮挡触发元素的边界区域，导致鼠标实际移到了Tooltip节点上，打断了原触发元素的离开事件触发。
检查状态更新逻辑，确认进入新元素触发展示时，有没有重置之前其他元素的Tooltip展示状态。

解决方案

按实现成本从低到高，可选以下方案，组合使用稳定性更高：

改用全局唯一的激活状态管理
不要给每个触发项单独维护展示布尔值，改成全局存储当前激活Tooltip对应的唯一标识，触发进入事件时直接覆盖激活值，不管之前有没有未关闭的Tooltip，都会自动替换，从状态层面避免多面板同时展示。示例代码：

// 不推荐：每个项单独维护状态，漏触发时会残留多个true值
// const [tooltipVisibleMap, setTooltipVisibleMap] = useState({})

// 推荐：全局唯一激活ID，同一时间只会有一个Tooltip展示
const [activeTooltipId, setActiveTooltipId] = useState(null)

const handleMouseEnter = (itemId) => {
  setActiveTooltipId(itemId)
}
const handleMouseLeave = () => {
  setActiveTooltipId(null)
}

增加鼠标位置兜底判断
针对快速移动漏触发离开事件的问题，给列表容器绑定统一的mousemove监听，每次鼠标移动时判断当前位置是否在对应触发元素+Tooltip面板的区域范围内，如果不在就直接清空激活状态，补上漏触发的关闭逻辑。核心逻辑示例：

const listContainerRef = useRef(null)

useEventListener('mousemove', (e) => {
  if (!activeTooltipId) return
  const triggerNode = document.querySelector(`[data-item-id="${activeTooltipId}"]`)
  const tooltipNode = document.querySelector('.global-tooltip-panel')
  if (!triggerNode) return

  const isOnTrigger = triggerNode.contains(e.target)
  const isOnTooltip = tooltipNode?.contains(e.target)
  // 鼠标既不在触发元素上也不在Tooltip上，强制关闭
  if (!isOnTrigger && !isOnTooltip) {
    setActiveTooltipId(null)
  }
}, listContainerRef.current)

增加悬停防抖逻辑
给进入事件加100ms左右的延迟触发，快速划过时如果鼠标在元素上停留时间不足阈值，就不弹出Tooltip，既可以解决快速滑动漏事件导致的多面板问题，也能优化交互，避免鼠标误划过弹出多余提示。注意离开时要清除延迟定时器，避免状态错乱：
```
const hoverTimerRef = useRef(null)

const handleMouseEnter = (itemId) => {
  clearTimeout(hoverTimerRef.current)
  hoverTimerRef.current = setTimeout(() => {
    setActiveTooltipId(itemId)
  }, 100)
}
const handleMouseLeave = () => {
  clearTimeout(hoverTimerRef.current)
  setActiveTooltipId(null)
}
```

生产环境如果不想手动处理这些边缘场景，可以直接用成熟的无头组件库的Tooltip组件，这类组件内部已经处理了快速移动漏事件、Portal边界判断、鼠标热区容错等问题，不需要重复踩坑。

内容的提问来源于stack exchange，提问作者yeln