根本原因是锁屏控制栏由系统级服务驱动,uni-app无直接api控制,需原生桥接;android须用notification+progress实现且满足id固定等条件,ios则完全不可控。

App端锁屏控制栏进度无法更新,根本原因是什么
锁屏控制栏(如 Android 锁屏界面的媒体播放控件、下载进度浮层)不是 uni-app 能直接控制的 UI 区域,它由系统级服务(MediaSession、Notification 或厂商定制控件)驱动。uni-app 本身没有 API 可写入锁屏进度,必须通过原生能力桥接。常见错误是误以为 plus.notification.createNotification 或 uni.showLoading 能影响锁屏——它们只作用于前台通知或页面内弹层,对锁屏区域完全无效。
Android 锁屏进度只能靠 Notification + MediaStyle 实现
Android 系统允许在锁屏显示自定义进度,但仅限两类场景:媒体播放(用 MediaSession)、长期任务(用带 progress 的 Notification 并启用 ongoing: true)。下载类进度必须走后者,且需满足:
- 通知必须使用
NotificationCompat.Builder构建,并调用.setStyle(new NotificationCompat.DecoratedCustomViewStyle())或.setStyle(new NotificationCompat.MediaStyle())(部分厂商仅认 MediaStyle) -
setProgress(max, progress, false)中的max必须是非零整数(如 100),不能传 0 或小数 - 通知 ID 必须固定(不能每次下载都换新 ID),否则锁屏上会闪退或不更新
- 必须在主线程调用更新逻辑,H5+ 的
plus.android.importClass需配合plus.android.runOnUiThread
iOS 锁屏进度根本不可控,别白费力气
iOS 系统禁止第三方 App 在锁屏界面显示任意进度条。你唯一能做的,是注册 UNNotificationCategory 并发送带 mutable-content: 1 的后台通知,但锁屏上只会显示静态文本和图标,progress 字段会被忽略。试图用 AVPlayer 模拟媒体播放来触发锁屏控件,也会因无实际音频流被系统拦截。真机测试时若看到锁屏有进度,那一定是系统根据下载文件类型自动识别为“媒体”并启用默认样式——不可预测、不可编程、不建议依赖。
真正可行的折中方案:用前台 Notification 绑定锁屏可见性
虽然不能直接写锁屏,但可让前台通知始终处于“前台活跃”状态,从而提升其在锁屏的曝光概率:
- 创建通知时设
priority: 2(最高优先级)和visibility: 1(Notification.VISIBILITY_PUBLIC) - Android 8.0+ 必须指定
channelId,且该 channel 的importance设为IMPORTANCE_HIGH - 每次进度更新前,先调用
notificationManager.cancel(id)再重建,避免旧通知残留导致锁屏显示异常 - 进度值更新频率压到 500ms 以上,防止系统判定为“骚扰通知”而降权隐藏
锁屏进度不是前端能“同步”的状态,而是系统根据通知活跃度、渠道重要性和用户行为动态决定的展示策略——把通知做稳、做准、做持续,比强行塞进度数字更有效。











