使用 Driver.js 指引时遮挡 fixed 元素的问题与解决方案

旺仔不是汪2025-04-23 10:37

在前端项目中使用 Driver.js 实现用户引导功能时，遇到了一个和层级相关的问题。引导步骤中需要高亮 sidebar（侧边栏）中的某个菜单项，而该 sidebar 是通过 position: fixed 实现固定定位的。在实际运行中，发现该菜单项虽然被 Driver.js 正确识别为高亮目标，但在页面上却完全被遮罩层盖住，导致用户看不到应被高亮的内容。

问题现象

页面中有一个 position: fixed 的 sidebar。
在 Driver.js 引导过程中，遮罩层和高亮层覆盖了整个页面。
目标菜单项被正确选中为高亮目标，但视觉上被遮罩层覆盖，显示为空白。

原因分析

Driver.js 的引导功能通过在页面中添加遮罩层和高亮层实现聚焦效果：

#driver-page-overlay: 用于构建遮罩
#driver-highlighted-element-stage: 构造高亮区域

这两个 DOM 元素的 z-index 值非常高，通常超过普通页面元素。在目标元素是 position: fixed 且 z-index 较低时，即使被高亮，也会被遮罩层挡住，无法正常显示。

解决方案

上网查询后找到解决方案：调整样式，将 Driver.js 的默认遮罩层透明化，并使用 outline 实现遮罩效果，避免直接盖住目标元素。

添加如下 CSS 即可修复：

css 复制代码

div#driver-highlighted-element-stage,
div#driver-page-overlay {
    background: transparent !important;
    outline: 5000px solid rgba(0, 0, 0, 0.75);
}

原理说明

background: transparent !important;
移除 Driver.js 默认的深色遮罩背景，防止直接覆盖目标元素。
outline: 5000px solid rgba(0, 0, 0, 0.75);
使用大范围的 outline 替代遮罩效果。outline 不会覆盖目标元素，只在其外部渲染，因此不会遮挡被高亮的内容。

这种做法本质上是在不影响高亮元素的前提下，模拟出类似遮罩聚焦的效果，兼容 position: fixed 元素。

总结

Driver.js 在处理 position: fixed 元素时可能出现层级遮挡的问题，主要由于遮罩层 z-index 较高导致目标元素被覆盖。通过使用透明背景和 outline 替代默认遮罩样式，可以在不干扰页面结构的前提下修复该问题，确保高亮内容可见。