uniapp-zaudio

v2.2.51

Published

2 years ago

audio manager for uniapp

Downloads

0High
0Medium
0Low

jgt012345

audio audioManager uniapp

uniapp-zaudio 背景音频播放组件

当前版本v2.2.51, 查看版本console.log(ZAudio.version)

预览

http://jingangtui.gitee.io/uniapp-z-audio/#/

若文档展示不全,请查看gitee或下载示例

特性

支持 H5, app, 微信小程序播放
支持背景音频播放
支持多页面同步状态
支持 3 种 UI 样式
支持来电中断后续播
支持同一个音频回调中注册多个业务事件(v2.1.0 后版本)

简要说明

插件分为ZAudio类和 zaudio 组件, ZAudio类处理音频播放逻辑, zaudio组件用于渲染
ZAudio基于uni.getBackgroundAudioManager和uni.createInnerAudioContext创建
示例在 app 运行时,注意开启网络权限,若不显示数据则重启 app 应用,或者检查网络权限问题
v2.0 版本依赖vuex, v2.1.0 后版本不依赖 vuex, 建议下载最新版本
如果你觉得这个项目不错, 或是想增加新功能欢迎Star Fork PR

使用步骤

插件市场下载或 npm install uniapp-zaudio;
实例化 ZAudio类并挂载

注意大小写:ZAudio是类

HbuilderX插件导入方式, import可能需要修改目录名哦

import ZAudio from '@/components/uniapp-zaudio' //HbuilderX插件导入方式, import可能需要修改目录名哦
// import ZAudio from 'uniapp-zaudio' // npm引用方式

let zaudio = new ZAudio({
  continuePlay: true, //续播
  autoPlay: true, //自动播放 部分浏览器不支持
});
Vue.prototype.$zaudio = zaudio; //挂载vue原型链上

//模拟音频初始数据,切勿业务中使用
var data = [
  {
    src:
      "https://96.f.1ting.com/local_to_cube_202004121813/96kmp3/zzzzzmp3/2016aJan/18X/18d_DeH/01.mp3",
    title: "恭喜发财",
    singer: "刘德华",
    coverImgUrl:
      "https://img.1ting.com/images/special/75/s150_f84ef5082b0420f74cd2546b986ab0fc.jpg",
  },
  {
    src:
      "https://96.f.1ting.com/local_to_cube_202004121813/96kmp3/zzzzzmp3/2015kNov/25X/25m_XiaoQ/03.mp3",
    title: "好运来",
    singer: "作者1111",
    coverImgUrl:
      "https://img.1ting.com/images/special/204/s150_77254cd4a4da1a33b8faf89c4cbf6e40.jpg",
  },
];
zaudio.setAudio(data); //添加音频
zaudio.setRender(0)//渲染第一首音频

引用组件

注意大小写:zaudio是组件

<zaudio theme="theme3"></zaudio>

import zaudio from '@/components/uniapp-zaudio/zaudio';
// import zaudio from 'uniapp-zaudio/zaudio'
export default {
  components: { zaudio: zaudio },
};

< zaudio > 组件参数配置

| 参数 | 类型 | 必填 | 描述 | 其他 | | ---------- | ------ | ----- | ---------- | ---------------------------------------------- | | theme | String | false | 主题 | theme2 or theme1 or theme3; 默认theme1 | | themeColor | String | false | 进度条颜色 | 默认 #42b983 |

用法示例:

<zaudio theme="theme1"  themeColor="#42b983" />

ZAudio对象的参数和实例方法

| 参数 | 类型 | 必填 | 描述 | 其他 | | ------------ | ------- | ----- | ---------------------------- | ---------- | | defaultCover | String | false | 默认音频封面 | | continuePlay | Boolean | false | 自动播放下一首,完成后从头播放 | 默认 true | | autoPlay | Boolean | false | 自动播放,部分浏览器不支持 | 默认 false |

| 实例方法 | 描述 | 参数 | | --------------------------- | -------------------------------------| -------------------------------------------------------------------------------------| | on(event, action, fn) | 回调函数中注册业务事件 | event(音频回调方法), action(业务名), fn(业务函数); 见音频回调事件中注册业务| | off(event, action) | 回调函数中卸载业务事件, 重要 | event(音频回调方法), action(业务名);见音频回调事件中注册业务| | setAudio(data) | 设置音频列表(audiolist赋值) | 对象数组, 例: [{src: 音频地址, title: 音频名, singer: 歌手 coverImgUrl: 封面}]| | updateAudio(data) | 添加音频列表(push数据到audiolist)| 对象数组, 例: [{src: 音频地址, title: 音频名, singer: 歌手 coverImgUrl: 封面}]| | setRender(data) | 指定音频索引或对象,渲染到 zaudio 组件, 可用于异步渲染| 索引(number或string类型) 或音频对象(object类型) | | operate(index) | 指定索引, 自动判断播放暂停,并渲染对应的音频数据,没有索引时则判断当前音频 | 索引, Number或undefined | | stop() | 停止播放音频 (强制停止) | | stepPlay(count) | 快进快退 | 单位秒, Number类型 | | syncRender() | 实时渲染当前播放状态,见实时渲染当前播放状态 | | syncStateOn(action, fn) | 注册一个用于实时获取当前播放状态的事件,用法见获取音频播放状态和属性 | action(业务名), fn(回调函数,回调参数见音频对象属性) | syncStateOff(action) | 卸载用于实时获取当前播放状态的事件,用法见获取音频播放状态和属性 | action(与注册时的业务名对应)

用法示例:

初始化ZAudio类, 并渲染音频

let zaudio = new ZAudio({
  continuePlay: true, //续播
  autoPlay: true, //自动播放 部分浏览器不支持
});
var data = [
  {
    src:
      "https://96.f.1ting.com/local_to_cube_202004121813/96kmp3/zzzzzmp3/2016aJan/18X/18d_DeH/01.mp3",
    title: "恭喜发财",
    singer: "刘德华",
    coverImgUrl:
      "https://img.1ting.com/images/special/75/s150_f84ef5082b0420f74cd2546b986ab0fc.jpg",
  },
  {
    src:
      "https://96.f.1ting.com/local_to_cube_202004121813/96kmp3/zzzzzmp3/2015kNov/25X/25m_XiaoQ/03.mp3",
    title: "好运来",
    singer: "作者1111",
    coverImgUrl:
      "https://img.1ting.com/images/special/204/s150_77254cd4a4da1a33b8faf89c4cbf6e40.jpg",
  },
];


// 设置音频数据
zaudio.setAudio(data)
//渲染第一首音频
zaudio.setRender(0)

异步加载

setTimeout(()=>{
	zaudio.setAudio(data);
	zaudio.operate(0); //手动去渲染第1首音频
},2000)

音频回调事件中注册业务

音频事件会触发不同的回调(如播放回调, 暂停回调), 而一个回调中允许注册多个互不影响的业务事件
zaudio.on(event, action, fn): 注册业务事件
zaudio.off(event, action): 卸载业务事件, 页面卸载时可以卸载不必要的业务事件, 这样可以提高页面性能
event: 回调方法名,具体表格如下
action: 自定义的业务名, 一个业务名在同一个音频回调中只能注册一次, 多次注册不会被覆盖
fn: 触发的业务函数, 部分回调会实时返回当前播放的状态, 见下表

| event(音频回调名) |action(自定义业务名)| 描述 | fn参数 | | -----------| ---- | -------------- | --------------------------------- | | waiting |类型string或symbol | 加载音频时回调 | 当前加载状态 | error |类型string或symbol| 错误播放时回调 | | playing |类型string或symbol| 播放时回调 | 实时返回当前播放的音频对象 | | canPlay |类型string或symbol| 初始播放时回调 | 当前播放的音频对象 | | pause |类型string或symbol| 暂停回调 | | ended |类型string或symbol| 结束回调 | | setAudio |类型string或symbol| 覆盖音频的回调 | 当前音频列表 | | updateAudio |类型string或symbol| 添加音频的回调 | 当前音频列表 | | stop |类型string或symbol| 强制停止播放回调, 小程序音频浮窗关闭回调 | | seek |类型string或symbol| 快进拖动回调 | 当前跳转的时间点

用法示例:

一个playing回调,触发两个业务事件

	onLoad(query) {
		//playing回调, 注册`event-a`和`event-b`两个打印事件
		this.$zaudio.on('playing', 'event-a', data => {
			console.log(data,'event-a')
		});
		this.$zaudio.on('playing', 'event-b', data => {
			console.log(data,'event-b')
		});
	},
	
	destroyed(){
			//页面卸载时卸载业务, 提高页面性能
		this.$zaudio.off('playing', 'event-a')
		this.$zaudio.off('playing', 'event-b')
	}

实时渲染当前播放状态到zaudio组件

适用情况: 当zaudio组件渲染了非当前播放的数据, 且需要实时渲染当前的播放状态时
用法示例:

onShow(){
	//实时渲染当前的播放状态
	this.$zaudio.syncRender();
},

实时获取音频播放状态和属性

由于v2.1.x之后版本不依赖vuex, 音频状态需要使用syncStateOn方法来实时监听获取
syncStateOn(action, fn): 注册一个获取音频播放状态和属性的事件
syncStateOff(action): 卸载获取音频播放状态和属性的事件, 页面卸载时卸载该事件, 这样可以提高页面性能
action: 自定义业务名, 用于区分多个不同的实时获取音频播放状态和属性事件
fn: 实时获取音频播放状态和属性的回调, 回调参数见音频对象属性

用法示例:

data(){
	return {
			audiolist: this.$zaudio.audiolist, //当前音频列表
			playIndex: this.$zaudio.playIndex, //当前播放的索引
			paused: this.$zaudio.paused, //当前是否暂停
			playinfo: this.$zaudio.playinfo //当前播放的信息

	}
}
onShow(){
	//获取音频播放状态和属性
	this.getAudioState();
},
methods:{
	getAudioState() {
		//注册page-index-get-state, 实时获取zaudio属性状态
		this.$zaudio.syncStateOn('page-index-get-state', ({ audiolist, playIndex, paused, playinfo }) => {
			this.audiolist = audiolist;
			this.playIndex = playIndex;
			this.paused = paused;
			this.playinfo = playinfo;
		});
	}
},
onHide(){
	//卸载page-index-get-state,提高页面性能
	this.$zaudio.syncStateOff('page-index-get-state')
}

音频对象属性

name | 描述 |其他 -|-|- renderIndex | 当前zaudio渲染索引| audiolist | 音频列表数组 | [{src:音频导致, title:音频名, singer: 作者, coverImgUrl: 音频封面}] renderinfo | 当前渲染信息 | playinfo | 当前播放信息| paused | 音频暂停状态| true:暂停 playIndex | 当前播放索引| renderIsPlay |渲染与播放是否一致 | loading | 加载状态

用法示例:

let zaudio = new ZAudio();
console.log(zaudio.audiolist); //获取当前的音频列表数据
console.log(zaudio.renderIndex); //获取当前zaudio组件渲染音频的索引值

注意: 上面的获取的属性不是实时的状态, 实时获取见实时获取音频播放状态和属性

背景播放配置

在 manifest.json 中配置小程序

 "mp-weixin" : {
		"requiredBackgroundModes" : [ "audio" ],
        "appid" : "",
        "setting" : {
            "urlCheck" : false
        },
        "usingComponents" : true
    }

注意 ios 端需要打包 ipa 才生效 iOS

"ios" : {
    "UIBackgroundModes" : [ "audio" ]
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme