uni-app全屏需分端实现:app端需navigationstyle:"custom"、关闭titlenview、onshow调plus.navigator.setfullscreen;h5端仅能requestfullscreen视觉模拟;小程序端无法隐藏状态栏。

uni-app 实现“全屏显示”没有统一解法,必须按端拆解:App 端能真隐藏状态栏+系统导航栏,H5 端只能视觉模拟,小程序端连状态栏都不可隐藏——混用同一套逻辑必然失败。
App 端真全屏必须三步闭环
只改 pages.json 或只调 API 都不行,缺一不可:
-
navigationStyle: "custom"是前提,不设这个,plus.navigator.setFullscreen(true)只能藏状态栏,顶部仍留白 - 配套关闭
"app-plus": { "titleNView": false },否则某些 Android 机型(如小米、OPPO)会渲染空白 title 区域 -
onShow中调用plus.navigator.setFullscreen(true),且必须包裹#ifdef APP-PLUS,否则 H5 小程序报plus is not defined - 若需连底部虚拟导航栏也隐藏,加
plus.navigator.hideSystemNavigation(),但注意:小米 HyperOS、OPPO ColorOS 14+ 已禁用该 API,属系统限制
H5 端 requestFullscreen 只能模拟视觉全屏
它不会锁方向、不隐藏地址栏,只是让页面 DOM 占满视口:
- 必须由用户点击事件触发,
document.body.requestFullscreen()比document.documentElement.requestFullscreen()兼容性更好(iOS Safari 不支持后者) - 退出时务必调
document.exitFullscreen(),并监听fullscreenchange事件同步状态 - 全屏后加 CSS:
html, body { height: 100vh; overflow: hidden; },否则可能残留滚动条 - manifest.json 的
h5节点下必须设"orientation": "all",否则横屏全屏无效
视频组件全屏不能靠 CSS 拉伸
style="width: 100vw; height: 100vh;" 是伪全屏,内容被裁切、控制条错位、背景透出:
- App 端必须用
uni.createVideoContext('myVideo', this).requestFullScreen({ direction: 90 }),direction: 90强制横屏(iOS 下0常失效) -
<video></video>必须有严格匹配的id,大小写敏感,否则上下文创建失败 - 全屏时
cover-view自动失效(设计使然),需用subNVue覆盖控件,且zIndex ≥ 9999 - 监听
@fullscreenchange事件获取e.detail.fullScreen,别信document.fullscreenElement—— 多端返回不可靠
全屏后内容错位或露白不是 CSS 问题
状态栏高度被移除后,布局未适配导致:
- App 端优先用 CSS 变量:
padding-top: var(--status-bar-height);,比 JS 获取uni.getSystemInfoSync().statusBarHeight更稳 - 若用了
<uni-nav-bar></uni-nav-bar>,设background-color="transparent",下拉刷新时临时关掉透明,防状态栏变黑 - H5 端无法真正隐藏状态栏,只能用
viewport-fit=cover+env(safe-area-inset-top)模拟,但 iOS Safari 非 PWA 模式下该值为 0 - 真机调试必须用正式打包的 IPA/APK,HBuilderX 模拟器不触发原生窗口 flags,测不出真实效果
最易被忽略的是:App 端所有操作依赖 plusready 环境就绪,mounted 或 created 里调 setFullscreen 必然静默失败;而 H5 和小程序根本不存在“真全屏”概念,强行复用 App 逻辑只会白屏或报错。











