更新记录
1.0.2(2026-11-19)
首次发布:完成 Android / HarmonyOS 双端实现与真机验证。
1.0.1(2026-11-19)
首次发布:完成 Android / HarmonyOS 双端实现与真机验证。
1.0.0(2026-11-19)
首次发布:完成 Android / HarmonyOS 双端实现与真机验证。
查看更多平台兼容性
uni-app x(4.25)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| × | × | √ | × | √ | × |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
uni-bg-audio 后台音频播放插件
开箱即用的后台音频播放插件,提供播放列表队列、音频焦点自动管理、断点续播、状态监听、能力诊断。纯系统 API(Android MediaPlayer / 鸿蒙 AVPlayer),零三方 SDK 依赖。
为什么选它(对比 uni-app x 内置 getBackgroundAudioManager)
| 能力 | 内置 getBackgroundAudioManager | uni-bg-audio |
|---|---|---|
| 单曲播放 | ✅ | ✅ |
| 播放列表队列 / 上下曲 | ❌ | ✅ |
| 循环模式(列表/单曲) | ❌ | ✅ |
| 音频焦点自动管理 | 部分 | ✅(焦点丢失自动暂停 + 事件通知) |
| 断点续播(进度持久化) | ❌ | ✅ |
| 状态事件监听 | ✅ | ✅(9 类事件码) |
| 能力诊断 diagnose | ❌ | ✅ |
| 倍速播放 | ✅ | ✅ |
平台支持
| 平台 | 支持 | 引擎 |
|---|---|---|
| App-Android | ✅ | MediaPlayer(系统原生) |
| App-鸿蒙 HarmonyOS | ✅ | AVPlayer(@kit.MediaKit) |
| App-iOS | ⏸ 后期规划 | — |
| Web / 小程序 | ❌ | — |
快速开始(3 行接入)
import { play, onStateChange, getState } from '@/uni_modules/uni-bg-audio'
// 1. 监听状态
onStateChange((e) => console.log('音频事件:', e.message, e.position + '/' + e.duration))
// 2. 播放(支持本地路径 / 网络 URL)
play({
list: [
{ src: '/sdcard/music/a.mp3', title: '第一首' },
{ src: 'https://example.com/b.mp3', title: '第二首' }
],
index: 0,
loopMode: 1, // 0不循环 1列表循环 2单曲循环
background: true, // 显示后台通知
success: (res) => console.log('开始播放', res)
})
API 清单
| API | 说明 |
|---|---|
play(options) |
播放(track 单曲 或 list 列表,index 起始,loopMode,background) |
pause(options?) |
暂停 |
resume(options?) |
恢复播放 |
stop(options?) |
停止并清除通知 |
seek(options) |
跳转到指定秒数 |
setVolume(options) |
音量 0~1 |
setRate(options) |
倍速 0.5~2.0 |
next(options?) / prev(options?) |
下一首 / 上一首 |
getState() |
同步获取当前状态(status/playing/position/duration/index/listSize/volume/rate/loopMode) |
saveProgress(options) |
保存断点(key) |
restoreProgress(options) |
恢复断点(key) |
onStateChange(cb) / offStateChange() |
监听 / 取消状态变化 |
diagnose(options) |
能力诊断 |
状态事件码(onStateChange)
| event | 说明 |
|---|---|
| 1 | 开始播放 |
| 2 | 暂停 |
| 3 | 停止 |
| 4 | 播放结束 |
| 5 | 播放错误 |
| 6 | 缓冲中 |
| 7 | 音频焦点丢失(来电等打断,已自动暂停) |
| 8 | 音频焦点恢复 |
| 9 | 切换曲目 |
状态码(getState.status)
0 空闲 · 1 播放中 · 2 暂停 · 3 停止 · 4 结束 · 5 错误 · 6 缓冲中
权限与隐私
- Android 13+ 通知栏显示需在 manifest 声明
POST_NOTIFICATIONS并动态申请(仅 background=true 时需要;不申请也能播放,只是无通知) - 插件不采集任何数据;断点进度仅存本地应用私有目录
- 纯系统 API,标准基座即可运行(无需自定义基座)
鸿蒙端能力边界
- AVPlayer 切后台可继续播放一段时间;长期稳定后台播放需接入 AVSession 媒体会话(可选增强,后续版本)
diagnose().supportsBackground在鸿蒙端返回false即为诚实提示
常见问题(FAQ)
Q:为什么点播放没声音?
A:先用 diagnose() 确认 canPlay。检查 src 是否为可访问的本地路径或网络 URL;网络音频需联网。
Q:切到后台还在播放吗? A:Android 端 background=true 会显示常驻通知并尽量保活;鸿蒙端 AVPlayer 切后台可播放一段时间。
Q:来电后会自动暂停吗? A:Android 端已接入音频焦点监听,来电/其他 App 播放时会收到 event=7 并自动暂停;焦点恢复发 event=8。
效果预览
真机(MuMu 模拟器)截图,图片托管在插件市场 CDN。

更新记录
见 changelog.md。

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 69
赞赏 0
下载 12775967
赞赏 1960
赞赏
京公网安备:11010802035340号