uniapp如何隐藏小米手机底部白条？

Question

在使用 UniApp 开发跨平台应用时，部分小米手机（尤其是全面屏机型）底部会出现白色导航栏（即“白条”），影响界面美观和沉浸式体验。该问题主要出现在 Android 系统的虚拟导航栏区域，因系统未正确透明化导致。开发者常通过设置页面全屏或调整 webview 的窗口布局参数来尝试解决，但在小米 MIUI 系统中适配效果不稳定。如何在 UniApp 中兼容性良好地隐藏小米手机底部白条，实现真正的沉浸式全屏显示，成为实际开发中的常见痛点。

Answer 1

UniApp 沉浸式全屏开发：解决小米手机底部“白条”问题的深度实践

1. 问题背景与现象描述

在使用 UniApp 开发跨平台应用时，部分小米手机（尤其是全面屏机型）在运行 Android 应用时，底部会出现一条明显的白色导航栏，俗称“白条”。该问题主要出现在启用了虚拟导航键的 MIUI 系统中。

尽管开发者已设置页面为全屏模式，但由于系统未正确将 WebView 的窗口布局延伸至导航栏区域，导致该区域默认填充白色背景，破坏了沉浸式体验。

此问题在非小米设备上表现良好，但在 MIUI 12 及以上版本中尤为突出，成为实际项目交付中的常见兼容性痛点。

2. 技术原理分析

Android 系统通过 WindowInsets 和 fitsSystemWindows 控制系统 UI（状态栏、导航栏）与内容区域的交互。UniApp 底层基于原生 WebView 构建，其窗口行为受 HBuilderX 编译配置和原生 Activity 布局影响。

MIUI 系统对虚拟导航栏的处理机制与原生 Android 存在差异，特别是在“全面屏手势”关闭时，系统强制保留导航栏占位，且默认不透明。

常见的错误做法是仅在前端通过 CSS 设置 padding-bottom 或 env(safe-area-inset-bottom) 进行适配，但无法真正消除白条。

3. 解决方案层级演进

1. CSS 层面尝试： 使用安全区环境变量进行适配
2. 页面配置优化： 修改 pages.json 中的 navigationStyle
3. 编译平台配置： 调整 manifest.json 中的 Android 窗口属性
4. 原生插件干预： 通过自定义原生插件调用 Android API 强制透明导航栏
5. 动态检测与兼容： 结合设备型号与系统版本做差异化处理

4. 具体实现步骤

步骤	操作内容	适用场景
1	在 pages.json 中设置 "navigationStyle": "custom"	隐藏默认标题栏，释放控制权
2	修改 manifest.json，启用沉浸式配置	全局生效，需配合原生编译
3	添加 CSS： body { padding-bottom: constant(safe-area-inset-bottom); }	基础兼容，防止内容被遮挡
4	使用原生插件调用 getWindow().getDecorView().setSystemUiVisibility()	深度控制 MIUI 导航栏透明度
5	判断设备是否为小米 + MIUI 版本，动态启用修复逻辑	避免对其他品牌造成副作用

5. 核心代码示例

// manifest.json 配置片段
{
  "app-plus": {
    "softinputMode": "adjustResize",
    "navigationBarTitleText": "",
    "immersed": true,
    "titleNView": false,
    "bounce": "none"
  }
}

// 原生插件 Java 代码（Android）
public void setImmersiveNavigation() {
    Activity activity = this.getActivity();
    Window window = activity.getWindow();
    window.getDecorView().setSystemUiVisibility(
        View.SYSTEM_UI_FLAG_LAYOUT_STABLE
        | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
        | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
        | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
        | View.SYSTEM_UI_FLAG_FULLSCREEN
        | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
    );
    window.setNavigationBarColor(Color.TRANSPARENT);
}

6. 流程图：解决方案执行路径

graph TD
            A[启动应用] --> B{是否为小米设备?}
            B -- 是 --> C{MIUI 版本 >= 12?}
            B -- 否 --> D[应用通用沉浸式配置]
            C -- 是 --> E[调用原生插件设置透明导航栏]
            C -- 否 --> F[使用 safe-area 兼容布局]
            E --> G[监听页面生命周期重置状态]
            F --> G
            D --> G
            G --> H[完成沉浸式渲染]

7. 注意事项与最佳实践

• 避免在所有设备上无差别启用透明导航栏，可能引发华为、OPPO 等品牌的兼容问题。
• 使用 uni.getSystemInfoSync() 获取 brand 和 system 字段进行精准判断。
• 测试时需覆盖多种手势模式（开启/关闭全面屏手势），因 MIUI 行为会动态变化。
• 建议封装为可复用的 npm 包或 uni_modules 模块，便于多项目集成。
• 注意 HBuilderX 版本更新可能带来新的系统适配机制，需持续关注官方文档。
• 在 release 构建中验证插件是否被打包，避免调试正常而线上失效。
• 考虑用户可访问性，提供“返回”按钮替代物理导航键功能。
• 监控 Sentry 或类似工具上报的崩溃日志，排查原生层异常。
• 对于金融类或高安全性应用，需评估系统 UI 隐藏带来的合规风险。
• 结合 @supports (margin-bottom: env(safe-area-inset-bottom)) 做渐进增强。