弹窗内透明 PNG 显示异常排查与修复记录

问题现象

在弹窗组件中使用带透明通道的 PNG 图片时，设计预期为图片上方区域透明，但实际在页面中看起来像是白底，没有呈现透明效果。

本次问题涉及的组件与资源：

• 组件：src/pages/landing/v1/components/insurance/InsuranceModal.vue
• 图片：src/static/landing/v1/insurance/imgtoubaoshengji.png

根因分析

1. 图片资源本身不是根因

检查后确认该 PNG 文件带有 alpha 通道，属于 RGBA 图片，因此不是“图片导出时丢失透明通道”导致的问题。

2. 真正问题在于弹窗结构层级

问题的关键不是图片没有透明，而是图片的透明区域后面承接的是白色弹窗主体，所以视觉上看起来像“透明失效”。

错误认知通常是：

• 透明 PNG 没生效

实际情况是：

• PNG 的透明区域是正常的
• 但透明区域后方正好是白色背景容器
• 所以看到的仍然是白色

3. 原始结构的问题点

如果图片直接放在白底弹窗容器内部，例如：

<view class="modal-content">
  <view class="modal-header-image">
    <image class="header-image" />
  </view>
  <view class="introduction-section" />
</view>

并且 .modal-content 设置了白底：

.modal-content {
  background-color: #fff;
}

那么图片透明区域透出来的就是 .modal-content 的白色背景，而不是遮罩层或页面底层。

正确修复思路

核心原则：透明图片区域必须脱离白色内容容器，单独作为上层结构渲染。

本次采用的修复方式是把头图从白色内容主体中拆出来，形成两层结构：

• 外层：整体弹窗容器 modal-shell
• 上层：图片区域 modal-header-image
• 下层：白色内容区 modal-content

修复后的结构

<view class="modal-mask">
  <view class="modal-shell">
    <view class="modal-header-image">
      <image src="/static/landing/v1/insurance/imgtoubaoshengji.png" class="header-image" mode="widthFix" />
    </view>

    <view class="modal-content">
      <view class="introduction-section" />
      <view class="health-declaration-section" />
      <view class="modal-footer" />
    </view>
  </view>
</view>

这样处理后：

• 顶部图片不再属于白底内容区
• PNG 透明区域后面承接的是遮罩层或页面底层
• 视觉上就能正确显示透明效果

关键样式处理

1. 新增外层弹窗结构容器

.modal-shell {
  width: 100%;
  max-height: 96vh;
  display: flex;
  flex-direction: column;
}

作用：

• 用于承载“顶部图片层 + 底部内容层”
• 将结构从单一白底容器拆分为分层结构

2. 头图区域独立渲染

.modal-header-image {
  width: 100%;
  max-height: 60vh;
  line-height: 0;
  flex-shrink: 0;

  .header-image {
    width: 100%;
    display: block;
    background-color: transparent;
  }
}

作用：

• line-height: 0 用于消除图片作为行内替换元素可能带来的底部空隙
• display: block 避免默认行内布局引入空白缝隙
• flex-shrink: 0 避免头图在弹性布局中被异常压缩

3. 白底只保留在正文内容区

.modal-content {
  width: 100%;
  max-height: 96vh;
  margin-top: -2rpx;
  background-color: #fff;
  border-radius: 24rpx 24rpx 0 0;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

作用：

• 仅正文区域使用白底
• 顶部透明区域不再被整体白底托住
• margin-top: -2rpx 用于消除图片区与正文区衔接时可能出现的白缝

为什么这次修复能成功

因为这次不是单纯给图片或图片容器设置 transparent，而是从结构上解决了“透明区域后面垫着什么”的问题。

可以把它理解为：

• 之前：透明图放在白纸上，透明部分看到的还是白纸
• 现在：透明图悬浮在白纸上方，透明部分看到的是后面的遮罩层

所以这属于层级承载问题，不是简单的图片样式问题。

排查透明 PNG 问题的推荐顺序

后续再遇到类似问题，可以按下面顺序排查：

第一步：确认图片资源本身

检查：

• 是否真的是 PNG
• 是否存在 alpha 通道
• 是否设计导出时已经带白底

第二步：确认 CSS 是否直接破坏透明效果

重点检查：

• opacity
• background
• mix-blend-mode
• filter
• mask
• backdrop-filter

第三步：确认透明区域后方承接的背景是什么

这是最容易被忽略的一步。

即使 PNG 是透明的，如果其父容器、祖先容器或同层底图是白色，那么透明区域看起来依然会像白底。

第四步：检查图片是否被放在错误的结构层里

如果透明图片在白色内容卡片内部，通常就需要把它从白色主体里拆出去，改成独立头部层。

适用场景总结

该方案适用于以下场景：

• 弹窗顶部透明头图
• 卡片式弹层中的异形透明图片
• Banner 顶部带透明渐隐效果
• 需要让图片透明区域透出遮罩层或页面背景的 UI

本次修复文件

• src/pages/landing/v1/components/insurance/InsuranceModal.vue

一句话总结

透明 PNG 显示不透明，很多时候不是图片有问题，而是它被放进了错误的白底容器里。真正的修复方式，是把透明图片区从白底内容层中拆出来。