JS/React实现应用引导功能：如何将指定元素置于模态遮罩层上方？

问题根因 #

你遇到的是CSS层叠上下文的限制：只要目标元素的任意祖先元素创建了层叠上下文（触发条件包括但不限于祖先设置了非auto的z-index、transform属性、opacity<1、will-change指定了CSS属性等），子元素的z-index仅能在该祖先的层叠上下文内部排序，只要该祖先本身的层级低于遮罩层，子元素z-index设再高也无法突破父级限制。

优先方案：扩散阴影模拟遮罩（零DOM改动、无层级冲突） #

完全不需要额外的全局遮罩层，直接给目标元素加一个超大扩散半径的阴影当遮罩，目标元素自然高亮，从根源规避层叠上下文问题：

.highlight-target {
  position: relative;
  box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.7); /* 最后一个值为遮罩透明度，可自行调整 */
  z-index: 1; /* 仅需保证阴影在当前层叠上下文内不会被父级内部其他元素挡住即可 */
}

控制逻辑非常简单：引导激活时给对应id的元素加这个类，引导结束移除即可，不需要修改任何DOM结构，也不用处理层级问题。
补充：如果目标元素本身有圆角，给这个类加overflow: clip即可保证阴影和元素圆角匹配。

兼容方案：临时修改为fixed定位（适配已有全局遮罩的场景） #

如果业务逻辑必须保留全局遮罩层，可以用JS读取目标元素的视口位置，临时将它设为fixed定位脱离原有层叠上下文，自然就能放到遮罩层上方：

// 高亮激活逻辑
function enableHighlight(targetId, maskZIndex = 9999) {
  const el = document.getElementById(targetId)
  if (!el) return
  // 存储原始样式，后续恢复用
  el._originalStyle = {
    position: el.style.position,
    top: el.style.top,
    left: el.style.left,
    width: el.style.width,
    height: el.style.height,
    zIndex: el.style.zIndex
  }
  // 读取元素当前位置尺寸
  const rect = el.getBoundingClientRect()
  // 应用fixed定位，位置和原位置完全一致
  Object.assign(el.style, {
    position: 'fixed',
    top: `${rect.top}px`,
    left: `${rect.left}px`,
    width: `${rect.width}px`,
    height: `${rect.height}px`,
    zIndex: maskZIndex + 1 // 比遮罩层高1即可
  })
}

// 高亮关闭逻辑
function disableHighlight(targetId) {
  const el = document.getElementById(targetId)
  if (!el || !el._originalStyle) return
  // 恢复原始样式
  Object.assign(el.style, el._originalStyle)
  delete el._originalStyle
}

React场景极简封装示例 #

import { useEffect } from 'react'

// 自定义hook控制高亮
function useGuideHighlight(targetId, isActive) {
  useEffect(() => {
    const el = document.getElementById(targetId)
    if (!el) return
    if (isActive) {
      el.classList.add('highlight-target')
    } else {
      el.classList.remove('highlight-target')
    }
    return () => el.classList.remove('highlight-target')
  }, [targetId, isActive])
}

// 引导步骤组件调用
function GuideStep({ targetId, showTooltip }) {
  useGuideHighlight(targetId, showTooltip)
  return showTooltip ? <Tooltip /> : null
}

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