uni.showLoading({ mask: true }) 在某些页面不生效

Question

在使用 UniApp 开发跨平台应用时，`uni.showLoading({ mask: true })` 在某些页面无法显示遮罩层是常见问题。该问题多出现在页面层级复杂、自定义导航栏或使用了 `v-show` 控制显隐的场景中。由于 `mask: true` 依赖正确的 z-index 层级和页面渲染时机，若页面存在原生子窗口（如 map、video）或组件未完全挂载，可能导致遮罩失效。此外，在 `onShow` 或异步回调中调用时，若执行时机过早，也会影响渲染效果。建议检查页面结构、避免在 `v-show` 切换时立即调用，并确保 DOM 已就绪后再触发 loading 提示。

Answer 1

一、问题现象与初步定位

在使用 UniApp 开发跨平台应用时，开发者常遇到 uni.showLoading({ mask: true }) 无法正常显示遮罩层的问题。该现象多出现在页面结构复杂或存在自定义导航栏的场景中。

• 遮罩层不出现，但 loading 文字提示可见
• 仅在部分设备（如 iOS 或特定 Android 厂商）上复现
• 在页面切换或组件显隐控制后调用失效

此问题表面上是 UI 层面的“遮罩缺失”，实则涉及渲染机制、层级管理与生命周期协调等多个底层因素。

二、技术原理剖析：mask 的实现机制

uni.showLoading 中的 mask: true 参数会创建一个全屏半透明层，用于阻止用户交互。其本质依赖于：

1. 原生渲染层的 z-index 管理
2. 页面根容器的可覆盖性
3. DOM 渲染完成后的时机控制

UniApp 在 H5、小程序和 App 端对 mask 的实现方式不同：

平台	mask 实现方式	常见冲突元素
H5	CSS fixed + z-index	fixed 定位组件
微信小程序	原生 cover-view / cover-image	map、video、camera
App（iOS/Android）	原生弹窗层（高于 webview）	web-view、subNVue

三、典型触发场景分析

以下为导致 mask 失效的高发场景及其成因：

• 自定义导航栏：通过 CSS 模拟 navbar 时，若设置了 position: fixed 且 z-index 过高，可能压住 mask 层
• v-show 控制显隐：组件未销毁，但 display 切换过程中 DOM 尚未重排，导致 mask 插入失败
• 原生子窗口组件：如 map、video 在小程序中属于“原生控件”，层级高于 WebView 内容，mask 无法覆盖
• onShow 钩子中立即调用：页面刚进入可视状态，UI 线程尚未完成布局，mask 被提前插入但未生效

四、诊断流程图

```mermaid
graph TD
    A[调用 uni.showLoading({ mask: true })] --> B{是否在 onShow 或异步回调中?}
    B -- 是 --> C[延时执行 setTimeout(..., 50)]
    B -- 否 --> D{是否存在 v-show 控制的父组件?}
    D -- 是 --> E[确保组件已完全显示后再调用]
    D -- 否 --> F{页面含 map/video 等原生组件?}
    F -- 是 --> G[尝试使用 subNVue 或原生 loading]
    F -- 否 --> H[检查全局样式 z-index 冲突]
    H --> I[调整 custom-navbar z-index < 999]
    I --> J[验证 mask 是否恢复]
```
    

五、解决方案与最佳实践

针对上述问题，提出以下分层解决策略：

1. 延迟调用保障 DOM 就绪：

   onShow() {
       this.$nextTick(() => {
           setTimeout(() => {
               uni.showLoading({ mask: true });
           }, 50);
       });
   }

2. 避免 v-show 切换瞬间调用：使用 v-if 替代以确保组件重新挂载，或监听 transition 结束事件
3. 处理原生组件遮挡：在小程序中，可使用 <cover-view> 自定义 loading，或通过 native plugins 调用原生弹窗
4. 统一 Loading 封装：创建全局 service，集成防抖、堆栈管理和平台适配逻辑
5. z-index 规范化管理：定义项目级层级常量，例如：

   // styles/variables.scss
   $z-nav: 900;
   $z-popup: 950;
   $z-loading: 999; // 必须高于其他非原生层

6. App端使用 subNVue：对于频繁出现 loading 的页面，预加载一个 native loading 层，通过 subNVues 控制显隐，规避 webview 层级限制