uni-app无法直接监听锁屏播放/暂停按钮点击,需分平台处理:微信小程序通过bgm.onPlay()/onPause()监听;App端依赖原生插件桥接系统MediaSession或MPNowPlayingInfoCenter;H5不支持。

uni-app 本身无法直接监听锁屏界面上的播放/暂停按钮点击——这不是 JS 层能捕获的事件,而是系统级控制指令,必须通过原生能力桥接。微信小程序端可以,App 端(iOS/Android)则需依赖平台特性与条件编译。
微信小程序:用 onPlay/onPause 监听后台操作
微信原生的 BackgroundAudioManager 提供了完整的生命周期回调,锁屏界面的播放/暂停、上一首/下一首、进度拖动等操作,都会触发对应事件。
-
bgm.onPlay():用户在锁屏界面点“播放”、通知栏点播放、耳机线控按一下,都会触发 -
bgm.onPause():锁屏点暂停、通知栏暂停、耳机线控双击(部分机型),都会触发 -
bgm.onStop()和bgm.onEnded()也同理,但注意onStop在用户手动点“停止”时才触发,不是切后台 - 别漏掉
bgm.onSeeked()——拖动锁屏进度条后会触发,需同步更新 UI 进度
⚠️ 常见错误:只监听 @click 或页面内按钮,却没绑定这些 manager 事件,导致锁屏操作完全无响应。
App 端(iOS/Android):原生插件是唯一路径
uni-app 的 JS 层在 App 端收不到锁屏控制事件。uni.getBackgroundAudioManager() 在 App 上仅负责播放和基础状态同步,不暴露系统级控制回调。
- iOS 需用
MPNowPlayingInfoCenter+AVRoutePickerView等原生机制,JS 层必须通过uni.requireNativePlugin调用封装好的原生插件,再发事件回 JS - Android 需监听
MediaSession的onPlay()/onPause(),并用广播或回调透出到 JS,同样依赖离线打包+原生插件 - 市面上已有成熟插件如
uni-audio-control(需确认是否支持最新 Android 14 / iOS 17),但必须在manifest.json中声明权限并重新云打包 - H5 完全不支持——浏览器无锁屏音频控制概念,
uni.getBackgroundAudioManager()在 H5 返回空对象
⚠️ 切勿尝试用 document.addEventListener('visibilitychange') 或监听页面显示隐藏来模拟——它和锁屏控制无关,且 iOS 后台 JS 执行权极不稳定。
为什么不能统一用 onHide/onShow 替代?
因为这两个生命周期和锁屏控制动作完全不等价:
-
onHide只表示 App 进入后台(比如切到微信、按 Home 键),此时音频可能仍在播,用户根本没碰锁屏界面 -
onShow表示回到前台,但用户可能刚在锁屏界面点了暂停,此时你恢复播放就违背了用户意图 - 锁屏控制是异步、独立于页面生命周期的系统行为;而
onHide是 uni-app 框架层的钩子,两者时间、语义、触发源都不同
真正需要响应锁屏操作的地方,只能是原生层回调或微信的 BackgroundAudioManager 事件,没有中间态可取巧。
最易被忽略的一点:微信小程序里,onPause 触发后,bgm.paused 是 true,但 bgm.playing 不一定立刻变 false(有延迟),判断状态必须以事件为准,而不是轮询属性。


















