vue-aplayer的api详细讲解
前言：
vue-aplayer的api介绍
来源：入口
更多 ： 英文源码
目录：
一、安装
使用 npm
使用 yarn 推荐
二、快速开始
传统方式
vue中使用：点我进入详细步骤
三、具体配置参数
fixed 可选
mini 可选
autoplay 可选
theme 可选
loop 可选
order 可选
preload 可选
volume 可选
audio 必填
#customAudioType 可选
mutex 可选
lrcType 可选
listFolded 可选
listMaxHeight 可选
storageName 可选
四、外部调用他本身的方法
version 静态
#media 实例
#currentMusic 实例
#play() 实例
#pause() 实例
#toggle() 实例
#seek() 实例
#switch() 实例
#skipBack() 实例
#skipForward() 实例
#showNotice() 实例
#showLrc() 实例
#hideLrc() 实例
#toggleLrc() 实例
#showList() 实例
#hideList() 实例
#toggleList() 实例
五、自身的方法事件
#原生 Media 事件
#播放器事件
六、歌词
LRC 格式
#LRC 文件
#LRC 字符串
#禁用歌词
七、播放列表
等等，这里只整理下常用的，更多详细的请看 入口
一、安装
使用 npm
npm install @moefe/vue-aplayer --save
使用 yarn 推荐
yarn add @moefe/vue-aplayer二、快速开始
传统方式
vue中使用：点我进入详细步骤
三、具体配置参数
fixed 可选
- 类型：
boolean? - 默认值：
false - 描述：是否开启吸底模式
mini 可选
提示
如果开启吸底模式，该选项可以控制播放器展开或收起
- 类型：
boolean? - 默认值：
false - 描述：是否开启迷你模式
autoplay 可选
注意
由于大多数移动端浏览器禁止了音频自动播放，所以该选项在移动端无效
- 类型：
boolean? - 默认值：
false - 描述：是否开启自动播放
theme 可选
提示
你可以选择引入 color-thief 让播放器根据封面图片自动获取主题颜色
- 类型：
string? - 默认值：
#b7daff - 描述：设置播放器默认主题颜色
loop 可选
注意
由于播放器会保存用户的使用习惯，所以播放器首次初始化之后该选项将失效
- 类型：
APlayer.LoopMode? - 默认值：
all - 描述：设置播放器的初始循环模式
declare namespace APlayer {
export type LoopMode = 'all' | 'one' | 'none';
}
order 可选
注意
由于播放器会保存用户的使用习惯，所以播放器首次初始化之后该选项将失效
- 类型：
APlayer.OrderMode? - 默认值：
list - 描述：设置播放器的初始顺序模式
declare namespace APlayer {
export type OrderMode = 'list' | 'random';
}
preload 可选
- 类型：
APlayer.Preload? - 默认值：
auto - 描述：设置音频的预加载模式
declare namespace APlayer {
export type Preload = 'none' | 'metadata' | 'auto';
}
volume 可选
- 类型：
number? - 默认值：
0.7 - 描述：设置播放器的音量
audio 必填
- 类型：
APlayer.Audio | Array - 默认值：
undefined - 描述：设置要播放的音频对象或播放列表
declare namespace APlayer {
export type AudioType = 'auto' | 'hls' | 'normal';
export interface Audio {
id?: number; // 音频 id
name: string | VNode; // 音频名称
artist: string | VNode; // 音频艺术家
url: string; // 音频播放地址
cover: string; // 音频封面
lrc?: string; // lrc 歌词
theme?: string; // 单曲主题色，它将覆盖全局的默认主题色
type?: AudioType; // 指定音频的类型
speed?: number; // 单曲播放速度
}
}
点击加载播放器
这里与 APlayer 不同的是新增了 id 和 speed 属性。id 默认情况下由播放器自动生成，你也可以手动传一个 id 来覆盖它。speed 属性可以指定该音频的播放速度。
注意
id 是用来区分音频的唯一标识，不允许重复，如果出现重复可能会导致播放器出现异常。
默认情况下 id 是根据播放列表的索引生成，当播放列表发生变化时 (新增/删除) 会重新生成。
当你从播放列表中删除音频时，由于播放列表发生了变化，所以会导致当前音频的 id 与删除后的播放列表不匹配。 出现这种情况时，会降级根据 url 更新当前音频的信息，如果播放列表中每一项的 url 都是唯一的，那么不会有问题。 如果有重复的 url，你必须设置音频的 id 属性，以确保每一项都是唯一的，否则播放器可能出现异常。
#customAudioType 可选
- 类型：
{ [index: string]: Function }? - 默认值：
undefined - 描述：自定义音频类型
example.vue
mutex 可选
- 类型：
boolean? - 默认值：
true - 描述：是否开启互斥模式
如果开启则会阻止多个播放器同时播放，当前播放器播放时暂停其他播放器
lrcType 可选
- 类型：
APlayer.LrcType? - 默认值：
0 - 描述：设置 lrc 歌词解析模式
declare namespace APlayer {
export enum LrcType {
file = 3, // 表示 audio.lrc 的值是 lrc 文件地址，将通过 `fetch` 获取 lrc 歌词文本
html = 2, // 不支持 html 用法
string = 1, // 表示 audio.lrc 的值是 lrc 格式的字符串，将直接通过它解析歌词
disabled = 0, // 禁用 lrc 歌词
}
}
listFolded 可选
注意
由于播放器会保存用户的使用习惯，所以播放器首次初始化之后该选项将失效
- 类型：
boolean? - 默认值：
false - 描述：是否折叠播放列表
listMaxHeight 可选
- 类型：
number? - 默认值：
250 - 描述：设置播放列表最大高度，单位为像素
storageName 可选
- 类型：
string? - 默认值：
aplayer-setting - 描述：设置存储播放器设置的
localStoragekey
四、外部调用他本身的方法
version 静态
- 类型：
string - 描述：只读属性，返回 APlayer 的版本号
- 用法：
import { APlayer } from '@moefe/vue-aplayer';
console.log(APlayer.version);
#media 实例
- 类型：
APlayer.Media - 描述：只读的原生
Media对象 - 用法：
const { media } = this.$refs.aplayer;
console.log(media.currentTime); // 获取音频当前播放时间
console.log(media.duration); // 获取音频总时间
console.log(media.paused); // 获取音频是否暂停
#currentMusic 实例
警告
如果你想切换到播放列表中的其他音频请使用 switch 方法，而不要直接设置它
- 类型：
APlayer.Audio - 描述：获取当前正在播放的音频
- 用法：
console.log(this.$refs.aplayer.currentMusic);
#play() 实例
- 类型：
Function - 返回值：
Promise - 描述：播放音频
- 用法：
this.$refs.aplayer.play();
#pause() 实例
- 类型：
Function - 返回值：
void - 描述：暂停音频
- 用法：
this.$refs.aplayer.pause();
#toggle() 实例
- 类型：
Function - 返回值：
void - 描述：切换播放和暂停
- 用法：
this.$refs.aplayer.toggle();
#seek() 实例
- 类型：
Function - 参数：
time- 类型：
number - 描述：时间（秒）
- 类型：
- 返回值：
void - 描述：跳到特定时间
- 用法：
this.$refs.aplayer.seek(100);
#switch() 实例
- 类型：
Function - 参数：
audio- 类型：
number|string - 描述：音频索引或音频的部分名称
- 类型：
- 返回值：
void - 描述：切换到播放列表中的其他音频
- 用法：
this.$refs.aplayer.switch(1); // 切换到播放列表中的第二首歌
this.$refs.aplayer.switch('东西'); // 切换到播放列表中歌曲名包含“东西”的第一首歌
#skipBack() 实例
- 类型：
Function - 返回值：
void - 描述：切换到上一首音频
- 用法：
this.$refs.aplayer.skipBack();
#skipForward() 实例
- 类型：
Function - 返回值：
void - 描述：切换到下一首音频
- 用法：
this.$refs.aplayer.skipForward();
#showNotice() 实例
- 类型：
Function - 参数：
text- 类型：
string - 描述：通知文本
- 类型：
time- 类型：
number? - 默认值：2000
- 描述：显示时间（毫秒）
- 类型：
opacity- 类型：
number? - 默认值：0.8
- 描述：通知透明度 (0 ~ 1)
- 类型：
- 返回值：
Promise - 描述：显示通知，设置时间为 0 可以取消通知自动隐藏
- 用法：
this.$refs.aplayer.showNotice('喵喵喵');
#showLrc() 实例
- 类型：
Function - 返回值：
void - 描述：显示歌词
- 用法：
this.$refs.aplayer.showLrc();
#hideLrc() 实例
- 类型：
Function - 返回值：
void - 描述：隐藏歌词
- 用法：
this.$refs.aplayer.hideLrc();
#toggleLrc() 实例
- 类型：
Function - 返回值：
void - 描述：显示/隐藏歌词
- 用法：
this.$refs.aplayer.toggleLrc();
#showList() 实例
- 类型：
Function - 返回值：
void - 描述：显示播放列表
- 用法：
this.$refs.aplayer.showList();
#hideList() 实例
- 类型：
Function - 返回值：
void - 描述：隐藏播放列表
- 用法：
this.$refs.aplayer.hideList();
#toggleList() 实例
- 类型：
Function - 返回值：
void - 描述：显示/隐藏播放列表
- 用法：
this.$refs.aplayer.toggleList();五、自身的方法事件
提示
跟组件和 prop 不同，事件名不会被用作一个 JavaScript 变量名或属性名，所以就没有理由使用 camelCase 或 PascalCase 了。 并且 v-on 事件监听器在 DOM 模板中会被自动转换为全小写 (因为 HTML 是大小写不敏感的)，所以在 DOM 模板中请始终使用全小写监听事件。
#原生 Media 事件
| 事件名称 | 描述 |
|---|---|
| onAbort | 在退出时触发 |
| onCanplay | 当文件就绪可以开始播放时触发（缓冲已足够开始时） |
| onCanplaythrough | 当媒介能够无需因缓冲而停止即可播放至结尾时触发 |
| onDurationchange | 当媒介长度改变时触发 |
| onEmptied | 当发生故障并且文件突然不可用时触发（比如连接意外断开时） |
| onEnded | 当媒介已到达结尾时触发（可发送类似“感谢观看”之类的消息） |
| onError | 当在文件加载期间发生错误时触发 |
| onLoadeddata | 当媒介数据已加载时触发 |
| onLoadedmetadata | 当元数据（比如分辨率和时长）被加载时触发 |
| onLoadstart | 在文件开始加载且未实际加载任何数据前触发 |
| onPause | 当媒介被用户或程序暂停时触发 |
| onPlay | 当媒介已就绪可以开始播放时触发 |
| onPlaying | 当媒介已开始播放时触发 |
| onProgress | 当浏览器正在获取媒介数据时触发 |
| onRatechange | 每当回放速率改变时触发（比如当用户切换到慢动作或快进模式） |
| onReadystatechange | 每当就绪状态改变时触发（就绪状态监测媒介数据的状态） |
| onSeeked | 当 seeking 属性设置为 false（指示定位已结束）时触发 |
| onSeeking | 当 seeking 属性设置为 true（指示定位是活动的）时触发 |
| onStalled | 在浏览器不论何种原因未能取回媒介数据时触发 |
| onSuspend | 在媒介数据完全加载之前不论何种原因终止取回媒介数据时触发 |
| onTimeupdate | 当播放位置改变时触发 |
| onVolumechange | 每当音量改变时（包括将音量设置为静音）时触发 |
| onWaiting | 当媒介已停止播放但打算继续播放时触发 |
example.vue
#播放器事件
| 事件名称 | 描述 |
|---|---|
| onListShow | 播放列表显示时触发 |
| onListHide | 播放列表隐藏时触发 |
| onListAdd | 播放列表新增音频时触发 |
| onListRemove | 播放列表删除音频时触发 |
| onListClear | 播放列表清空时触发 |
| onListSwitch | 切换播放的音频时触发 |
| onNoticeShow | 通知消息显示时触发 |
| onNoticeHide | 通知消息隐藏时触发 |
| onLrcShow | 歌词面板显示时触发 |
| onLrcHide | 歌词面板隐藏时触发 |
注意
由于某些选项会通过用户的操作直接修改，如果你传递了它们，会导致双向绑定的值不一致。
如果你想同步它们，可以通过监下面的事件来操作。你也可以使用 .sync 修饰符 来同步。
| 事件名称 | 描述 |
|---|---|
| update:volume | 修改音量时触发，用于同步 volume 选项 |
| update:mini | 修改迷你模式时触发，用于同步 mini 选项 |
| update:loop | 修改循环模式时触发，用于同步 loop 选项 |
| update:order | 修改顺序模式时触发，用于同步 order 选项 |
| update:listFolded | 播放列表展开/隐藏时触发，用于同步 listFolded 选项 |
example.vue
六、歌词
LRC 格式
[ti:歌词(歌曲)的标题]
[al:本歌所在的唱片集]
[ar:演出者-歌手]
[au:歌词作者-作曲家]
[by:此LRC文件的创建者]
[offset:+/- 以毫秒为单位加快或延后歌词的播放]
[re:创建此LRC文件的播放器或编辑器]
[ve:程序的版本]
[mm:ss.ms] 我们一起学猫叫
[mm:ss.ms][mm:ss:ms] 一起喵喵喵喵喵
...
查看维基百科了解更多：https://zh.wikipedia.org/wiki/LRC格式
#LRC 文件
点击加载播放器
example.vue
#LRC 字符串
点击加载播放器
example.vue
#禁用歌词
点击加载播放器
example.vue
七、播放列表
点击加载播放器
example.vue
等等，这里只整理下常用的，更多详细的请看 入口