更新记录

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。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android 13+ 通知栏显示需 POST_NOTIFICATIONS 权限(可选,用于后台播放通知)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据;播放进度仅存储在用户设备本地(SharedPreferences/preferences)

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。