更新记录

1.0.0（2026-10-22）

immersive-screen

Android 沉浸式全屏 UTS 插件，适用于 uni-app（Vue2 / Vue3）项目在 App-Android 端隐藏顶部状态栏与底部系统导航栏，实现真正的全屏显示。

插件针对 Android 15 / Android 16 强制 edge-to-edge 的场景做了适配，同时处理了隐藏系统栏后底部残留白色占位区域的问题。

功能特性

同时隐藏状态栏和系统导航栏，实现全屏沉浸式显示
兼容 Android 15 / Android 16 强制 edge-to-edge
API 30 及以上使用 WindowInsetsController 隐藏系统栏
API 23 ~ 29 使用 SYSTEM_UI_FLAG_IMMERSIVE_STICKY 等传统沉浸式标记
隐藏系统栏后自动清理基座叠加的导航栏等高原生占位层，避免底部白条
系统栏隐藏后边缘滑动可临时唤出，符合系统手势习惯
插件内部自动延时重试，降低页面切换、焦点变化后系统栏复现的概率

平台兼容

平台	支持情况
App Android	支持，Android 6.0（API 23）及以上
App iOS	支持调用，但不执行任何操作
HarmonyOS	不支持
Web / H5	不支持
小程序	不支持

说明：iOS 没有开放隐藏系统导航栏的对应能力，hideSystemNavigation() 在 iOS 端为空实现，调用不会产生副作用。

安装方式

在插件市场导入本插件，或把 immersive-screen 目录放入项目的 uni_modules 下。
本插件包含 UTS 原生代码，必须使用自定义基座或云打包运行，标准基座无法加载。
修改插件原生代码后，需要重新打自定义基座，并同步递增 manifest.json 中的 versionCode 与 versionName。

使用示例

在 App.vue 中，于启动和回到前台时调用即可：

// #ifdef APP-PLUS
import { hideSystemNavigation } from '@/uni_modules/immersive-screen'
// #endif

export default {
  onLaunch() {
    // #ifdef APP-PLUS
    if (plus.os.name === 'Android') {
      hideSystemNavigation()
    }
    // #endif
  },
  onShow() {
    // #ifdef APP-PLUS
    if (plus.os.name === 'Android') {
      hideSystemNavigation()
    }
    // #endif
  }
}

API 说明

hideSystemNavigation()

隐藏状态栏和系统导航栏。

参数：无
返回值：无
执行线程：内部自动切换到主线程执行

hideSystemNavigation()

manifest 建议配置

建议在 manifest.json 中开启沉浸式状态栏，并取消底部安全区预留：

{
  "app-plus": {
    "statusbar": {
      "immersed": true
    },
    "safearea": {
      "background": "#000000",
      "backgroundDark": "#000000",
      "bottom": {
        "offset": "none"
      }
    }
  }
}

实现说明

Android 11（API 30）及以上：
- Window.setDecorFitsSystemWindows(false) 开启 edge-to-edge
- 状态栏、导航栏颜色设为透明
- 关闭导航栏对比度强制（API 29+）
- 使用 WindowInsetsController.hide() 隐藏状态栏和导航栏
- 设置 BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE，支持边缘滑动临时唤出
Android 6 ~ 10（API 23 ~ 29）：
- 使用 SYSTEM_UI_FLAG_IMMERSIVE_STICKY、HIDE_NAVIGATION、LAYOUT_FULLSCREEN 等传统标记
清理底部白条：
- 将 Activity 窗口背景设为黑色兜底，避免系统栏区域露出默认白色主题
- 查找并隐藏基座叠加在 DecorView 底部、与系统栏等高的占位容器，让页面内容正常显示
- 调用 requestLayout() 让页面按新的窗口尺寸重新布局
延时重试：
- 首次调用后分别在 120ms、600ms、1500ms、3000ms 再次应用，处理启动、页面切换等时机导致的系统栏复现

注意事项

插件本身不做页面适配，页面内容如需避开状态栏，请自行使用 safe-area-inset-* 或 uni.getWindowInfo() 返回值处理。
系统栏被隐藏后，从屏幕边缘滑动会临时显示系统栏，这是 Android 的系统行为，不是插件失效。
本插件会调整 Activity 窗口背景与底部占位层，如果项目依赖系统栏默认背景色，请在页面中自行绘制背景。
修改插件原生代码（UTS / Kotlin）后必须重新打自定义基座，否则改动不会生效。

常见问题

为什么标准基座运行没有效果？

插件包含 UTS 原生代码，必须使用自定义基座或云打包，标准基座不包含插件原生实现。

系统栏已隐藏，底部仍有一条白色区域？

这通常是基座在导航栏区域叠加的原生占位层没有随系统栏隐藏而移除。本插件已针对该情况清理占位层；请确认使用的基座已包含当前版本插件代码。

页面切换后系统栏又出现了？

在 App.vue 的 onShow 中再次调用 hideSystemNavigation() 即可，插件内部也带有延时重试。

编译报错“找不到名称 Type”？

请升级到当前版本插件。插件已避免在 Kotlin 混编文件中使用 WindowInsetsCompat.Type、WindowInsets.Type 等嵌套类引用，改为数值形式的 inset 类型掩码。

iOS 端能隐藏系统导航栏吗？

不能。iOS 未开放该能力，插件在 iOS 端为空实现。

版本

1.0.0

首次发布
支持 Android 6.0 及以上隐藏状态栏与系统导航栏
适配 Android 15 / Android 16 edge-to-edge
处理隐藏系统栏后的底部白色占位区域

平台兼容性

uni-app(5.26)

Vue2	Vue2插件版本	Vue3	Vue3插件版本	Chrome	Safari	app-vue	app-vue插件版本	app-nvue	app-nvue插件版本	Android	Android插件版本	iOS	鸿蒙
√	1.0.0	√	1.0.0	×	×	√	1.0.0	√	1.0.0	4.4	1.0.0	×	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
×	×	×	×	×	×	×	×	×	×	×	×

uni-app x(5.33)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
-	-	-	-	-	-

其他

多语言	暗黑模式	宽屏模式	蒸汽模式
√	√	√	√