uni-app 无法直接获取锁屏控制栏状态,因该概念非标准系统接口,且 statusBarHeight 仅反映前台应用状态栏高度,与锁屏无关;可监听 onHide/onShow 感知前后台切换,但需平台特判+原生能力实现真锁屏逻辑。

uni-app 没有 API 能直接获取“锁屏控制栏”状态(如是否锁屏、锁屏界面是否显示控制中心/通知等)。所谓“锁屏控制栏”不是标准系统概念,实际可能指锁屏界面的顶部状态栏、iOS 控制中心入口、Android 快捷设置面板,或误将 statusBarHeight 当作锁屏专属信息——这些都不可靠,也无跨端统一接口。
为什么 uni.getSystemInfoSync().statusBarHeight ≠ 锁屏状态信息
statusBarHeight 只反映当前前台应用窗口顶部状态栏(时间、信号、电池)的高度,无论设备是否锁屏,只要应用在前台运行,该值就固定不变。锁屏时应用已暂停或退至后台,onShow 都不会触发,更无法读取任何“锁屏界面”的 UI 信息。
- iOS 锁屏界面由系统独占渲染,App 无权限访问其布局或控件状态
- Android 各厂商锁屏样式差异极大(华为 EMUI、小米 MIUI、OPPO ColorOS),且无标准 API 暴露“控制栏是否展开”这类交互态
- 微信小程序、支付宝小程序等宿主环境完全屏蔽锁屏层信息,连
visibilitychange事件在锁屏时也不稳定触发
能间接感知的仅限“应用前后台切换”
如果你真正关心的是用户离开 App(比如按下电源键锁屏、切到其他 App),可用生命周期钩子监听,但注意:这不等于“锁屏”,只是前台状态变化。
-
onHide:App 进入后台时触发(含锁屏、Home 键、多任务切换) -
onShow:App 回到前台时触发(含解锁后回到本 App) - ⚠️ 不要依赖
document.hidden或visibilitychange—— H5 环境下锁屏时该事件不触发,小程序里被限制,App 端需 plus 监听plus.navigator.getState()
真需要锁屏相关逻辑?只能平台特判 + 降级处理
例如:视频播放页希望锁屏后继续播、或暂停;音乐类 App 需锁屏控制条支持。这类需求必须绕过 uni-app 封装,直调原生能力:
- App 端:用
uni.getBackgroundAudioManager()或plus.audio.createPlayer()启用后台音频,配合plus.ios.setApplicationIconBadgeNumber()(iOS)或plus.android.createNotification()(Android)模拟锁屏控制 - 小程序端:微信支持
backgroundAudioManager,锁屏后仍可播,但无法自定义锁屏控制条;需配置requiredBackgroundModes(iOS)和android:usesCleartextTraffic(Android)等 manifest 权限 - H5 端:无解。浏览器禁止锁屏下持续音视频播放,
navigator.mediaSession仅在部分 Chrome/Edge 支持,且锁屏后立即中断
锁屏本身是操作系统级隔离行为,uni-app 作为跨端框架,既无权限也无必要暴露这类底层状态。所有试图“检测锁屏”的方案,本质都是监听前台失焦,再结合业务场景做合理 fallback —— 比如视频暂停、定位停止上报、心跳断连重试。别在 JS 层硬写 isLockedScreen: true 这种伪状态。


















