Zooming插件点击图片放大后被黑色背景遮挡无法显示问题

问题复现条件 #

• 场景：文档图片展示站引入Zooming插件实现点击放大功能，通过CDN引入资源，DOM加载完成后初始化实例，配置bgColor: 'rgba(0,0,0,1)'、customSize: '100%'，绑定所有带img-zoomable类的卡片图片。
• 异常表现：卡片hover交互正常，点击图片触发放大后仅可见局部缩放、平移动效，完整图片被纯黑全屏背景完全遮挡无法查看；将bgColor透明度调整为0时图片可正常显示，但无法隔离原页面背景，不符合预期。
• 已做排查：按官方文档提示移除所有父元素的overflow: hidden样式，确认未使用fixed定位的图片，问题仍未解决。相关代码包含三部分：SCSS样式（section初始设overflow:hidden，.block设overflow:auto，覆盖section、粒子容器、内容层、卡片、图片相关样式）、HTML结构（section下嵌套粒子容器、内容层、block、wrapper、card，卡片内放置两张带card-img img-zoomable类的文档图）、JS初始化代码（DOMContentLoaded事件中初始化Zooming实例绑定目标图片）。

根因分析 #

核心诱因是层叠上下文（Stacking Context）层级错位，和overflow属性无直接关联：

1. 旧版本Zooming的实现逻辑为：点击图片后直接在<body>末尾插入全屏黑色遮罩层，同时操作原图片节点添加transform属性实现缩放、平移动画，默认给遮罩层设置高z-index，动画状态的图片设置比遮罩层高1位的z-index，预期图片显示在遮罩上方。
2. 当图片的任意父级元素触发独立层叠上下文创建（触发条件包括但不限于：设置position: relative/absolute/fixed/sticky且z-index不为auto、设置transform/filter/perspective属性、opacity值小于1、overflow值不为visible、设置will-change属性），原图片节点无论设置多高的z-index，都无法跳出父级层叠上下文的层级限制，层级永远低于直接插入在body下的遮罩层。这就直接对应排查中观察到的现象：遮罩不透明时完全挡住图片，遮罩透明时图片可正常显示。
3. 次要排查项：页面中的#particles-js3粒子容器如果z-index设置过高，也可能遮挡放大后的图片，但该场景下调整bgColor透明度不会改变遮挡状态，因此不是核心原因。

修复方案 #

按优先级从高到低选择：

• 方案1（长期最优，无兼容隐患）：升级Zooming到2.x正式版本。2.x版本调整了实现逻辑，放大时会克隆原图片节点直接插入到body下做动画，完全脱离原父元素的层叠上下文、overflow属性限制，不需要额外修改业务代码即可解决遮挡问题，原有初始化配置可完全保留。
• 方案2（不升级插件版本，通过配置+逻辑兜底修复）：初始化时显式指定更高的z-index值，同时通过插件的打开/关闭回调临时调整父元素层级，示例代码如下：

document.addEventListener('DOMContentLoaded', () => {
  const zoomInstance = new Zooming({
    bgColor: 'rgba(0,0,0,1)',
    customSize: '100%',
    zIndex: 99999, // 配置为比页面所有固定元素（导航、弹窗、粒子层）都高的数值
    onOpen: () => {
      // 放大触发时临时调整所有图片父元素的层级与overflow
      document.querySelectorAll('.img-zoomable').forEach(img => {
        let parent = img.parentElement
        while (parent && parent !== document.body) {
          // 缓存原样式值，关闭时还原
          parent.dataset.originOverflow = parent.style.overflow
          parent.style.overflow = 'visible'
          const parentPosition = getComputedStyle(parent).position
          if (parentPosition !== 'static') {
            parent.dataset.originZIndex = parent.style.zIndex
            parent.style.zIndex = '100000'
          }
          parent = parent.parentElement
        }
      })
    },
    onClose: () => {
      // 关闭放大时还原所有父元素的原始样式
      document.querySelectorAll('.img-zoomable').forEach(img => {
        let parent = img.parentElement
        while (parent && parent !== document.body) {
          if (parent.dataset.originOverflow !== undefined) {
            parent.style.overflow = parent.dataset.originOverflow
            delete parent.dataset.originOverflow
          }
          if (parent.dataset.originZIndex !== undefined) {
            parent.style.zIndex = parent.dataset.originZIndex
            delete parent.dataset.originZIndex
          }
          parent = parent.parentElement
        }
      })
    }
  })
  zoomInstance.listen('.img-zoomable')
})

• 方案3（样式快速兜底）：添加全局CSS强制调整插件生成元素的层级，同时将背景粒子容器的z-index调整到内容层之下：

/* 粒子容器作为背景，降低层级 */
#particles-js3 {
  z-index: 0 !important;
  pointer-events: none;
}
/* 强制遮罩层级 */
.zooming-overlay {
  z-index: 99998 !important;
}
/* 强制放大状态的图片层级 */
.img-zoomable.is-zooming {
  z-index: 99999 !important;
  position: relative !important;
}

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