当前位置: 首页 > 工具软件 > Player > 使用案例 >

vue-aplayer的api详细讲解

漆雕欣德
2023-12-01

前言:

      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

二、快速开始

传统方式

<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>

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<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>

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

 

 

 类似资料: