芒果音乐播放器接入文档

芒果音乐播放器是一款稳定、便捷、高性能的 HTML5 音乐播放器插件，面向生产环境分发。源码不对外开放时，只需要发布打包后的 npm 包和 CDN 文件，业务项目通过播放器标签自动挂载，或通过 JavaScript、Vue、React 实例化接入。

💡 提示

推荐使用在线调试工具快速生成配置代码，然后复制到你的项目中使用。

安装

npm 安装

bash # 安装芒果音乐播放器
npm install mango-music-player

CDN 引入

直接通过 script 标签引入，无需安装任何依赖：

html <script src="https://music.mgznb.cn/assets/js/music-player.min.js"></script>

快速使用

方式一：标签自动挂载

最简单的使用方式，只需引入 JS 文件，然后在页面中添加自定义标签即可：

html <script src="https://music.mgznb.cn/assets/js/music-player.min.js"></script>

<mango-music-player
  theme="mango-original-theme"
  mode="cloud"
  api-url="https://music.api.xfyun.club/api/v1/music/top?platform=netease&topId=3778678"
  is-auto-popup="true"
  memory="true"
></mango-music-player>

方式二：IIFE JS 实例化

通过 JavaScript 手动创建播放器实例：

javascript <script src="https://music.mgznb.cn/assets/js/music-player.min.js"></script>

<script>
  // 创建播放器实例
  const player = new MusicPlayer({
    theme: 'mango-original-theme',
    mode: 'cloud',
    apiUrl: 'https://music.api.xfyun.club/api/v1/music/top?platform=netease&topId=3778678',
    isAutoPopup: true,
    memory: true
  });

  // 挂载到页面
  player.mount(document.body);
</script>

方式三：ESM / npm 引入

使用 ES Module 方式引入：

javascript import { MusicPlayer } from 'mango-music-player';

const player = new MusicPlayer({
  theme: 'mango-original-theme',
  mode: 'cloud',
  apiUrl: 'https://music.api.xfyun.club/api/v1/music/top?platform=netease&topId=3778678'
});

player.mount(document.body);

CDN 地址

播放器提供 CDN 加速服务，可直接引用：

文件 地址 说明
主文件 (IIFE) https://music.mgznb.cn/assets/js/music-player.min.js 生产环境推荐使用
ESM 版本 https://music.mgznb.cn/assets/js/music-player.esm.js ES Module 格式
樱花特效 https://music.mgznb.cn/plugin/sakura/sakura.min.js 樱花飘落特效插件

基础配置

播放器支持丰富的配置项，可以通过 HTML 属性或 JS 对象传入：

属性名 类型 默认值 说明
language string zh 语言，可选 zh / en
theme string mango-original-theme 主题名称
mode string cloud 播放模式，cloud / local
api-url string - 云端模式下的 API 地址
environment string production 环境，production / development
autoplay boolean false 是否自动播放
volume number 0.8 音量，0-1
play-mode string order 播放模式，order / single / random

主题配置

内置多套精美主题，可自由切换：

主题名 说明
mango-original-theme 原始主题（芒果橙黄）
mango-orange-theme 橙色主题
mango-pink-theme 粉色主题
mango-dark-green-theme 深绿主题
mango-wine-theme 酒红主题
mango-sky-theme 天空主题
mango-dark-theme 暗色主题

自定义主题

也可以通过 CSS 变量自定义主题样式：

css mango-music-player {
  --player-primary-color: #ff6b6b;
  --player-bg-color: #ffffff;
  --player-text-color: #333333;
}

布局配置

属性名 类型 默认值 说明
player-width string 324px 播放器宽度
bottom string 2.5em 底部距离
song-list-height string - 歌单高度
visible-song-list-count number 4 可见歌单数量
font-name string - 自定义字体名称
is-auto-popup boolean false 是否自动弹出
is-auto-playlist boolean false 是否自动展开歌单

播放配置

属性名 类型 默认值 说明
memory boolean false 是否记忆播放
memory-key string - 记忆存储的 key
colorful-lyric boolean false 是否彩色歌词
audio-visualizer boolean false 是否音频可视化
system-monitor boolean false 是否系统监控
lazy-load-timer number - 延迟加载时间（毫秒）

云端模式

云端模式下，播放器会从指定的 API 地址获取歌单数据：

html <mango-music-player
  mode="cloud"
  api-url="https://music.api.xfyun.club/api/v1/music/top?platform=netease&topId=3778678"
></mango-music-player>

支持的 API 格式

本地模式

本地模式下，可以直接传入歌曲数组：

javascript const player = new MusicPlayer({
  mode: 'local',
  playlist: [
    {
      name: '歌曲名',
      artist: '歌手',
      url: 'https://example.com/song.mp3',
      cover: 'https://example.com/cover.jpg',
      lyric: '[00:00.00] 歌词...'
    }
  ]
});

实例 API

播放器实例提供丰富的 API 方法：

方法 参数 说明
play() - 播放
pause() - 暂停
toggle() - 切换播放/暂停
stop() - 停止
prev() - 上一首
next() - 下一首
select(index) index: number 跳转到指定歌曲
seek(seconds) seconds: number 跳转到指定秒数
setVolume(volume) volume: number (0-1) 设置音量
setPlayMode(mode) mode: string 设置播放模式
setConfig(config) config: object 更新配置
setPlaylist(playlist) playlist: array 替换歌单
destroy() - 销毁播放器

生命周期

播放器提供完整的生命周期钩子：

javascript const player = new MusicPlayer({
  // 播放器创建前
  onBeforeCreate: () => {},
  // 播放器创建后
  onCreated: () => {},
  // 播放器挂载前
  onBeforeMount: () => {},
  // 播放器挂载后
  onMounted: () => {},
  // 播放器销毁前
  onBeforeDestroy: () => {},
  // 播放器销毁后
  onDestroyed: () => {}
});

樱花特效插件

樱花飘落特效插件，引入即可生效：

html <!-- 樱花特效插件 -->
<script src="https://music.mgznb.cn/plugin/sakura/sakura.min.js"></script>
🌸 提示

樱花特效是独立的插件，只需在页面中引入 script 标签即可自动生效，不需要额外配置。

兼容模式

兼容模式插件，用于旧版浏览器兼容：

html <!-- 兼容模式插件（放在播放器主JS之前） -->
<script src="https://music.mgznb.cn/plugin/ie-out/index.js"></script>

<!-- 播放器主JS -->
<script src="https://music.mgznb.cn/assets/js/music-player.min.js"></script>