uni-app全屏需分平台处理:App端须在manifest.json配置沉浸式状态栏并结合plus.navigator.setFullscreen(true),H5端仅能模拟全屏,小程序端无法隐藏状态栏。

uni-app 全屏显示时状态栏消失但底部安全区仍存在
全屏不是简单隐藏状态栏就能解决的,uni.setScreenBrightness 或 plus.navigator.setFullscreen 都不直接控制状态栏。真正起作用的是 manifest.json 中的 orientation 和 display 配置,以及条件编译下原生层的干预。
常见错误是只改了 H5 端的 document.documentElement.requestFullscreen(),结果 App 端完全没反应——因为 H5 全屏和原生全屏机制完全不同。
- App 端必须在
manifest.json的 “Android 设置” 或 “iOS 设置” 中勾选 “沉浸式状态栏”,并设置"statusBarStyle": "transparent" - 若需动态切换(如视频播放时全屏),需使用条件编译:
#ifdef APP-PLUS内调用plus.navigator.setFullscreen(true),再配合plus.webview.currentWebview().setStyle({top: '0px', height: '100%'}) - 注意:iOS 15+ 上
setFullscreen可能失效,需额外调用plus.navigator.setStatusBarStyle('light')并确保Info.plist中已配置UIViewControllerBasedStatusBarAppearance = YES
uni-app 隐藏状态栏后页面内容被“顶上去”或留白
隐藏状态栏 ≠ 页面自动撑满屏幕。系统状态栏高度(通常 20–44px)被移除后, 或根容器仍按原有 viewport 计算,导致顶部内容错位或底部露出空白。
这不是 CSS 能单独解决的问题,必须结合平台特性做适配:
- App 端:启用沉浸式后,
uni.getSystemInfoSync().statusBarHeight仍返回非零值,此时应忽略该值,用height: 100vh+position: fixed布局,并确保外层webview已设top: '0px' - H5 端:无法真正隐藏状态栏,只能视觉模拟——用
document.documentElement.style.paddingTop = 'env(safe-area-inset-top)'+viewport-fit=covermeta 控制;但 iOS Safari 下env(safe-area-inset-top)在非全屏模式下为 0,需监听resize判断是否进入 PWA 全屏 - 微信小程序端:状态栏不可隐藏,
wx.setNavigationBarColor({frontColor: '#ffffff', backgroundColor: '#000000', animation: {duration: 0}})是唯一可控入口,且仅影响导航栏,不影响状态栏本身
uni-app 条件编译中误用 plus.navigator.setFullscreen 导致白屏
plus.navigator.setFullscreen(true) 必须在 plusready 事件之后调用,否则 plus 对象未就绪,会静默失败甚至中断 webview 渲染流程。
典型错误写法:onLoad() { plus.navigator.setFullscreen(true) } —— 此时 plus 极大概率未初始化。
- 正确做法:在
created或onLoad中加一层判断:if (typeof plus !== 'undefined') { plus.navigator.setFullscreen(true) },更稳妥的是监听document.addEventListener('plusready', ...) - 退出全屏时务必恢复 webview 样式:
plus.webview.currentWebview().setStyle({top: 'statusbar', height: 'auto'}),否则返回上一页可能布局错乱 - 安卓部分机型(如华为 EMUI)调用
setFullscreen(true)后,软键盘弹出会触发状态栏闪现,需监听softinputDidShow事件手动重置setStyle
manifest.json 中 statusbar 配置对不同平台的实际影响
很多开发者以为在 manifest.json 里把 “状态栏样式” 设为 “透明” 就万事大吉,其实各平台响应逻辑差异极大:
- Android:仅当
"statusBarStyle": "transparent"且"immersed": true同时存在时,才真正启用沉浸式;缺一不可,且需在 “Android 设置” 卡片内配置,H5 或小程序设置项无效 - iOS:该配置只影响首次启动,后续运行时修改需原生插件介入;另外,
"statusBarStyle": "dark"在深色模式下可能不生效,建议统一用"light"并通过 CSS 控制文字颜色 - 打包后若发现配置未生效,检查
unpackage/res/nativeplugins/下是否有冲突插件(如某些广告 SDK 会强制重写状态栏样式),优先禁用后验证
最易被忽略的一点:H5 端无论 manifest 怎么配都无效,它根本不读这个文件;所谓“H5 全屏”只是浏览器地址栏折叠效果,依赖用户主动添加到主屏幕,且仅限支持 PWA 的浏览器。











