最彻底关闭沉浸式的方法是将 manifest.json 中 app-plus → statusbar → immersed 设为 false,该配置仅对 App 生效,修改后须真机运行或重新打包 APK/IPA。

直接在 manifest.json 关闭沉浸式
最简单、最彻底的关闭方式,就是让 App 端根本不走沉浸式逻辑——改 manifest.json 里的 app-plus → statusbar → immersed 配置为 false。
它比任何 JS 调用或 pages.json 配置都底层:不触发系统沉浸式窗口 flag,自然就不会有状态栏穿透、内容顶上去、padding 错乱等问题。
- 路径:
manifest.json→ 切换到“代码视图” → 找到"app-plus"节点 - 添加或修改为:
"app-plus": { "statusbar": { "immersed": false } } - 注意:该配置仅对 App(iOS/Android)生效,H5 和小程序不受影响
- 改完必须重新**真机运行或打包 APK/IPA**,HBuilderX 模拟器不识别此设置
pages.json 里设 navigationStyle: "default" 不等于关闭沉浸式
很多人以为把 navigationStyle 改成 "default" 就能“恢复默认状态栏”,其实不是。
uni-app 的 navigationStyle: "default" 仍会启用原生导航栏容器,并默认继承 immersed: true 行为(尤其 Android),页面内容依然可能和状态栏重叠,或者顶部多出不可见占位。
-
navigationStyle: "default"只控制是否渲染原生导航栏 UI,不控制状态栏是否沉浸 - 若你没动
manifest.json,即使设了"default",plus.navigator.setFullscreen(true)仍可能被框架自动调用(比如某些插件或模板内置逻辑) - 真正想“非沉浸”,优先靠
manifest.json关开关,而不是靠页面样式来回切
为什么不用 plus.navigator.setFullscreen(false)?
这个 API 名字有误导性:setFullscreen(false) 并不会“退出沉浸式”,它只是取消全屏状态——但前提是之前调过 setFullscreen(true),且系统支持回退。
现实中,多数机型(尤其 Android 厂商定制系统)一旦进入沉浸式窗口模式,false 调用常静默失败或无效;更麻烦的是,它无法覆盖 manifest.json 里 immersed: true 的初始窗口行为。
- 不要依赖
setFullscreen(false)来“关沉浸式”,它不是开关,而是临时状态切换 - 如果你已在某页面误调了
setFullscreen(true),建议在onHide中显式调setFullscreen(false)+unlockOrientation(),避免影响后续页面 - 但根源解法仍是:一开始就在
manifest.json设immersed: false
关闭后状态栏颜色和背景怎么控制?
关闭沉浸式后,状态栏回归系统默认样式(通常是黑字白底或白字黑底),但你仍可单独控制文字颜色和背景色,只是不能再“融合”进页面了。
- 文字颜色:在
pages.json对应页面的style下设"navigationBarTextStyle": "black"或"white"(仅 App 端生效) - 背景色:App 端需用
plus.navigator.setStatusBarBackground("#ff0000"),且必须包裹#ifdef APP-PLUS - 注意:部分低端 Android 机型不支持动态改状态栏背景,
immersed: false后基本只能靠系统默认色
manifest.json 却忘了重新打包。模拟器和热更新都不加载这个配置,只有安装新 APK/IPA 才生效。


















