uni-app横竖屏配置需按平台区分:manifest.json的screenOrientation仅App生效,pages.json的pageOrientation仅小程序和App部分生效,H5需用uni.onWindowResize监听并配合CSS媒体查询。

manifest.json 和 pages.json 配置不生效?先看平台限制
uni-app 的横竖屏控制不是“写完就通”,不同端走的是完全不同的机制,配置错地方或跨端误用是第一大坑。
-
manifest.json中的screenOrientation只对App端生效,H5 和小程序压根不读这个字段 -
pages.json里的pageOrientation是页面级开关,但仅在小程序(如微信)和 App 端部分生效;H5 完全无视它 - 微信小程序必须 同时 在
pages.json(页面 style)和manifest.json(mp-weixin.settings.screenOrientation)里声明方向,缺一不可 - App 端若只配了
manifest.json却没在pages.json指定某页为landscape,那该页仍可能被系统强制竖屏(尤其 iOS)
plus.screen.lockOrientation 在 H5 或小程序里报错?检查条件编译
这个 API 是 App端 原生能力,其他平台调用会直接抛 undefined is not a function 或静默失败。
- 必须用
#ifdef APP-PLUS包裹,否则 H5 构建时会报错,小程序运行时报plus is not defined - 锁定后不
unlockOrientation(),退出页面时方向会被卡住——下次进其他页也可能横着显示 - 不要在
onLoad立即锁,加setTimeout(..., 300)更稳:iOS 启动动画未结束时锁方向易失效 - 别用
landscape这种简写,必须用标准值:landscape-primary(home 键在右)或landscape-secondary(home 键在左)
监听屏幕旋转总收不到回调?优先用 uni.onWindowResize
uni.onWindowResize 是目前最通用、跨端可用的方向变化监听方式,比监听 orientationchange 或 resize 更可靠。
- 它返回的是
windowWidth和windowHeight,判断逻辑简单:windowWidth > windowHeight≈ 横屏(注意:不是 100% 等价于设备 orientation,但对 UI 布局足够) - H5 端可额外监听
window.addEventListener('resize'),但需手动off,否则内存泄漏;uni.onWindowResize的回调必须在onUnload里用uni.offWindowResize清理 - 不要依赖
screen.orientation.type—— H5 兼容性差,iOS Safari 不支持,微信小程序也不暴露该对象 - 监听到变化后,避免直接操作 DOM;推荐用
setData或响应式变量触发@media (orientation: landscape)样式切换
横屏时布局错乱、文字缩成一团?慎用 rpx + 检查 CSS 媒体查询范围
rpx 在横屏下按宽度等比缩放,但高度没变,容易导致“宽高比例崩坏”;而媒体查询若没写全,也会漏掉关键断点。
- 视频页、图表页等强横屏场景,建议放弃
rpx,改用vw/vh或%+flex布局 -
@media (orientation: landscape)只检测设备方向,不保证窗口尺寸;真要适配宽高比,得补上@media (min-aspect-ratio: 16/9)这类规则 - H5 模拟横屏(用
transform: rotate(90deg))时,务必加overflow: hidden到 body,否则出现双滚动条或内容溢出 - App 端横屏后,
statusBar高度逻辑可能错位,需在锁方向后手动调用plus.navigator.getStatusBarHeight()重算










