vue-aplayer的api详细讲解

漆雕欣德

2023-12-01

前言：

vue-aplayer的api介绍

来源：入口

一、安装

使用 npm

npm install @moefe/vue-aplayer --save

使用 yarn 推荐

yarn add @moefe/vue-aplayer

二、快速开始

传统方式

<html>
  <body>
    <!-- prettier-ignore -->
    <div id="app">
      <a-player :audio="audio" :lrc-type="3"></a-player>
    </div>
  </body>
  <!-- 你必须在引入 vue-aplayer 之前引入 vue -->
  <script src="https://cdn.jsdelivr.net/npm/vue"></script>
  <script src="https://cdn.jsdelivr.net/npm/@moefe/vue-aplayer"></script>
  <script>
    Vue.use(VueAPlayer, {
      defaultCover: 'https://github.com/u3u.png',
      productionTip: true,
    });

    new Vue({
      el: '#app',
      data: {
        audio: {
          name: '东西（Cover：林俊呈）',
          artist: '纳豆',
          url: 'https://cdn.moefe.org/music/mp3/thing.mp3',
          cover: 'https://p1.music.126.net/5zs7IvmLv7KahY3BFzUmrg==/109951163635241613.jpg?param=300y300', // prettier-ignore
          lrc: 'https://cdn.moefe.org/music/lrc/thing.lrc',
        },
      },
    });
  </script>
</html>

三、具体配置参数

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<APlayer.Audio>
默认值：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

<template>
  <aplayer :audio="audio" :customAudioType="customAudioType" :lrcType="3" />
</template>

<script>
import Vue from 'vue';
import APlayer from '@moefe/vue-aplayer';

Vue.use(APlayer);

export default {
  data() {
    return {
      audio: {
        name: 'Let It Go.m3u8',
        artist: 'Idina Menzel',
        url: 'https://cdn.moefe.org/music/hls/frozen.m3u8',
        cover: 'https://p1.music.126.net/n72JJkPg2-ENxhB-DsZ2AA==/109951163115400390.jpg?param=300y300', // prettier-ignore
        lrc: 'https://cdn.moefe.org/music/lrc/frozen.lrc',
        type: 'customHls',
      },
      customAudioType: {
        customHls(audioElement, audio, player) {
          if (Hls.isSupported()) {
            const hls = new Hls();
            hls.loadSource(audio.url);
            hls.attachMedia(audioElement);
          } else if (
            audioElement.canPlayType('application/x-mpegURL') ||
            audioElement.canPlayType('application/vnd.apple.mpegURL')
          ) {
            audioElement.src = audio.url;
          } else {
            player.showNotice('Error: HLS is not supported.');
          }
        },
      },
    };
  },
};
</script>

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
描述：设置存储播放器设置的 localStorage key

四、外部调用他本身的方法

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<void>
描述：播放音频
用法：

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<void>
描述：显示通知，设置时间为 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

<template>
  <aplayer
    :audio="audio"
    @abort="handleEvent"
    @canplay="handleEvent"
    @canplaythrough="handleEvent"
    @durationchange="handleEvent"
    @emptied="handleEvent"
    @ended="handleEvent"
    @error="handleEvent"
    @loadeddata="handleEvent"
    @loadedmetadata="handleEvent"
    @loadstart="handleEvent"
    @pause="handleEvent"
    @play="handleEvent"
    @playing="handleEvent"
    @progress="handleEvent"
    @ratechange="handleEvent"
    @readystatechange="handleEvent"
    @seeked="handleEvent"
    @seeking="handleEvent"
    @stalled="handleEvent"
    @suspend="handleEvent"
    @timeupdate="handleEvent"
    @volumechange="handleEvent"
    @waiting="handleEvent"
  />
</template>

<script>
import Vue from 'vue';
import APlayer from '@moefe/vue-aplayer';

Vue.use(APlayer);

export default {
  data() {
    return {
      audio: {
        name: '东西（Cover：林俊呈）',
        artist: '纳豆',
        url: 'https://cdn.moefe.org/music/mp3/thing.mp3',
        cover: 'https://p1.music.126.net/5zs7IvmLv7KahY3BFzUmrg==/109951163635241613.jpg?param=300y300', // prettier-ignore
        lrc: 'https://cdn.moefe.org/music/lrc/thing.lrc',
      },
    };
  },
  methods: {
    handleEvent(e) {
      console.log(e);
    },
  },
};
</script>

#播放器事件

事件名称	描述
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

<template>
  <aplayer
    :audio="audio"
    :volume.sync="volume"
    :mini.sync="mini"
    :loop.sync="loop"
    :order.sync="order"
    :listFolded.sync="listFolded"
    @listShow="handleEvent"
    @listHide="handleEvent"
    @listAdd="handleEvent"
    @listRemove="handleEvent"
    @listClear="handleEvent"
    @listSwitch="handleEvent"
    @noticeShow="handleEvent"
    @noticeHide="handleEvent"
    @lrcShow="handleEvent"
    @lrcHide="handleEvent"
  />
</template>

<script>
import Vue from 'vue';
import APlayer from '@moefe/vue-aplayer';

Vue.use(APlayer);

export default {
  data() {
    return {
      audio: {
        name: '东西（Cover：林俊呈）',
        artist: '纳豆',
        url: 'https://cdn.moefe.org/music/mp3/thing.mp3',
        cover: 'https://p1.music.126.net/5zs7IvmLv7KahY3BFzUmrg==/109951163635241613.jpg?param=300y300', // prettier-ignore
        lrc: 'https://cdn.moefe.org/music/lrc/thing.lrc',
      },
      volume: 0.7,
      mini: false,
      loop: 'all',
      order: 'list',
      listFolded: false,
    };
  },
  methods: {
    handleEvent() {
      console.log('Meow~');
    },
  },
};
</script>

六、歌词

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

<template>
  <!--
    指定 lrcType 为 3，表示 audio.lrc 的值是 lrc 文件地址，
    将通过 `fetch` 获取 lrc 歌词文本。
  -->
  <aplayer audio=":audio" :lrcType="3" />
</template>

<script>
import Vue from 'vue';
import APlayer from '@moefe/vue-aplayer';

Vue.use(APlayer);

export default {
  data() {
    return {
      audio: {
        name: '啵唧',
        artist: 'Hanser',
        url: 'https://cdn.moefe.org/music/mp3/kiss.mp3',
        cover: 'https://p1.music.126.net/K0-IPcIQ9QFvA0jXTBqoWQ==/109951163636756693.jpg?param=300y300', // prettier-ignore
        lrc: 'https://cdn.moefe.org/music/lrc/kiss.lrc',
      },
    };
  },
};
</script>

#LRC 字符串

点击加载播放器

 example.vue

<template>
  <!-- 指定 lrcType 为 1，表示 audio.lrc 的值是 lrc 字符串 -->
  <aplayer :audio="audio" :lrcType="1" />
</template>

<script>
import Vue from 'vue';
import APlayer from '@moefe/vue-aplayer';

Vue.use(APlayer);

export default {
  data() {
    return {
      audio: {
        name: '啵唧',
        artist: 'Hanser',
        url: 'https://cdn.moefe.org/music/mp3/kiss.mp3',
        cover: 'https://p1.music.126.net/K0-IPcIQ9QFvA0jXTBqoWQ==/109951163636756693.jpg?param=300y300', // prettier-ignore
        lrc: '[00:00.00] 我们一起学猫叫\n[99:99.99] 一起喵喵喵喵喵',
      },
    };
  },
};
</script>

#禁用歌词

点击加载播放器

 example.vue

<template>
  <!-- 指定 lrcType 为 0，表示禁用歌词 -->
  <aplayer :audio="audio" :lrcType="0" />
</template>

<script>
import Vue from 'vue';
import APlayer from '@moefe/vue-aplayer';

Vue.use(APlayer);

export default {
  data() {
    return {
      audio: {
        name: '啵唧',
        artist: 'Hanser',
        url: 'https://cdn.moefe.org/music/mp3/kiss.mp3',
        cover: 'https://p1.music.126.net/K0-IPcIQ9QFvA0jXTBqoWQ==/109951163636756693.jpg?param=300y300' // prettier-ignore
      },
    };
  },
};
</script>

七、播放列表

点击加载播放器

 example.vue

<template>
  <aplayer :audio="audio" :lrcType="3" />
</template>

<script>
import Vue from 'vue';
import APlayer from '@moefe/vue-aplayer';

Vue.use(APlayer);

export default {
  data() {
    return {
      audio: [
        {
          name: '东西（Cover：林俊呈）',
          artist: '纳豆',
          url: 'https://cdn.moefe.org/music/mp3/thing.mp3',
          cover: 'https://p1.music.126.net/5zs7IvmLv7KahY3BFzUmrg==/109951163635241613.jpg?param=300y300', // prettier-ignore
          lrc: 'https://cdn.moefe.org/music/lrc/thing.lrc',
        },
        {
          name: '响喜乱舞（Cover：MARiA）',
          artist: '泠鸢yousa',
          url: 'https://cdn.moefe.org/music/mp3/kyoukiranbu.mp3',
          cover: 'https://p1.music.126.net/AUGVPQ_rVrngDH9ocQrn3Q==/109951163613037822.jpg?param=300y300', // prettier-ignore
          lrc: 'https://cdn.moefe.org/music/lrc/kyoukiranbu.lrc',
        },
        {
          name: '啵唧',
          artist: 'Hanser',
          url: 'https://cdn.moefe.org/music/mp3/kiss.mp3',
          cover: 'https://p1.music.126.net/K0-IPcIQ9QFvA0jXTBqoWQ==/109951163636756693.jpg?param=300y300', // prettier-ignore
          lrc: 'https://cdn.moefe.org/music/lrc/kiss.lrc',
        },
      ],
    };
  },
};
</script>

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 字符串

#禁用歌词

七、播放列表

等等，这里只整理下常用的，更多详细的请看 入口

相关阅读

相关文章

相关问答

相关文档

更多：英文源码

等等，这里只整理下常用的，更多详细的请看入口