更新记录

1.0.0（2026-06-27） 下载此版本

初次提交

平台兼容性

uni-app(5.13)

uni-app x(5.13)

laoqianjunzi-audio

laoqianjunzi-audio 是一个面向 uni-app x 的标准 UTS 音频插件，聚焦后台播放、播放队列、远程控制、能力探测与运行诊断。

插件实现参考了以下公开资料，并在此基础上按当前模块的接口设计与多端适配需求完成了独立封装：

• https://doc.dcloud.net.cn/uni-app-x/api/get-background-audio-manager.html
• https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-getBackgroundAudioManager/utssdk

功能概览

• 统一封装 Android、iOS、HarmonyOS、Web 四端音频播放能力
• 支持单曲设置、歌单设置、追加曲目、移除曲目、按索引切换
• 支持播放、暂停、继续、停止、跳转进度、倍速、音量、循环模式控制
• 支持状态变更、进度、缓冲、播放结束、远程命令、中断等事件监听
• 支持能力探测、调试轨迹、异常报告读取与清理
• 自带插件内示例页，便于直接运行和联调

适用场景

• 音乐播放
• 有声书 / 播客连续播放
• 需要后台保活播放与系统控制中心联动的业务
• 需要统一管理播放队列和播放状态的多页面项目

平台支持

目录说明

• uni_modules/laoqianjunzi-audio/utssdk/：插件接口与各平台实现
• uni_modules/laoqianjunzi-audio/pages/index.uvue：插件示例页
• uni_modules/laoqianjunzi-audio/changelog.md：版本变更记录

安装方式

将插件放入项目的 uni_modules 目录后，直接通过模块路径引入即可。

import {
  initPlayer,
  setPlaylist,
  play,
  on,
  type AudioDeckTrack
} from '@/uni_modules/laoqianjunzi-audio'

快速开始

1. 初始化播放器

initPlayer({
  debug: true,
  preloadNext: true,
  preloadNextTime: 20,
  nextTrackTimeout: 12000,
  success: (res : any) => {
    console.log('initPlayer success', res)
  },
  fail: (err : any) => {
    console.error('initPlayer fail', err)
  }
})

2. 准备歌单并开始播放

const tracks : Array<AudioDeckTrack> = [
  {
    id: 'kalimba-1',
    url: 'https://www.learningcontainer.com/wp-content/uploads/2020/02/Kalimba.mp3',
    title: 'Kalimba',
    singer: 'Learning Container',
    album: 'Demo Album',
    durationHint: 348
  },
  {
    id: 'samplelib-45',
    url: 'https://download.samplelib.com/mp3/sample-45s.mp3',
    title: 'Samplelib Preview 45s',
    singer: 'Samplelib',
    album: 'Demo Album',
    durationHint: 45
  }
]

setPlaylist({
  tracks,
  startIndex: 0,
  tracksPayloadJson: JSON.stringify({ tracks }),
  success: (_res : any) => {
    play(null)
  }
})

3. 监听关键事件

on('stateChange', (event) => {
  console.log('stateChange', event.payload)
})

on('progress', (event) => {
  console.log('progress', event.payload)
})

on('error', (event) => {
  console.error('error', event.payload)
})

API 列表

初始化与装载

播放控制

播放参数

查询能力

事件与诊断

主要类型

AudioDeckTrack

AudioDeckState

AudioDeckState 用于描述当前运行状态，重点字段包括：

• initialized：是否已初始化
• status：当前状态，如 idle、ready、playing、paused
• currentTrack：当前曲目
• currentTime / duration / buffered：进度与缓冲信息
• playbackRate / volume / loopMode：当前播放参数
• queueIndex / queueLength：当前队列位置与长度
• backgroundActive：是否处于后台播放活跃状态

AudioDeckCapabilities

AudioDeckCapabilities 用于描述当前平台能力，包括：

• supported：当前平台是否支持插件能力
• sessionLevel：底层会话级别
• backgroundAudio：是否支持后台音频
• mediaSession：是否支持系统媒体会话
• remoteCommand：是否支持远程控制命令
• queue：是否支持队列能力
• playbackRate / volume：是否支持对应调节能力
• platform / adapter：当前平台和适配器标识
• requiresCustomBase：是否需要自定义基座

事件说明

运行示例

插件内置了完整示例页：

• 页面文件：uni_modules/laoqianjunzi-audio/pages/index.uvue
• 当前项目入口：pages.json

示例页覆盖以下演示内容：

• 初始化播放器
• 设置单曲与歌单
• 播放 / 暂停 / 继续 / 停止
• 倍速、音量、循环模式调节
• 上一首 / 下一首 / 指定索引切换
• 状态、能力、调试轨迹、异常报告读取
• 事件日志实时输出

使用建议

• 推荐优先使用 https 音频地址，避免平台安全策略或浏览器拦截
• Web 平台的自动播放与后台控制能力受浏览器策略影响，应以真实设备测试结果为准
• 如果曲目较多，建议同时传入 tracks 和 tracksPayloadJson，便于桥接层稳定读取队列数据
• 退出页面前应通过 off 解除监听，避免重复订阅
• 直播流或不适合缓存的音频资源，建议按业务需要显式设置 cache: false

调试建议

• 业务联调时先调用 initPlayer({ debug: true })
• 通过 getDebugTrace() 查看插件内部轨迹
• 通过 getCrashReports() 汇总异常记录
• 每次测试前可调用 clearDebugTrace() 与 clearCrashReports() 清空历史信息

版本记录

请查看 uni_modules/laoqianjunzi-audio/changelog.md。