更新记录

v1.0.0（2026-10-26） 下载此版本

首发版本：全局播放单例、迷你条+全屏播放页、弹性歌词动画、进度拖拽、播放列表、播放模式切换、点赞事件。

平台兼容性

uni-app(3.8.7)

uni-music-player 插件使用指南

版本：1.1.0 · 许可：MIT
全端音乐播放插件：JS 单例播放内核 + 统一组件（迷你播放条 + 全屏播放页合一），仿 Apple Music 歌词弹性动画，uni_modules 引入即用。

一、插件特性

• 全端播放：App 端使用后台音频管理器（锁屏 / 通知栏可控、支持后台播放），H5 / 小程序使用 InnerAudioContext；音频单例常驻，切页面不打断
• Apple Music 弹性歌词：当前行之后 1~9 行依次回弹，级联波动动画；当前行平滑放大高亮
• 完整播放能力：播放列表、列表循环 / 单曲循环 / 随机播放、进度拖拽、点击歌词跳转、上一首 / 下一首（3 秒规则）
• 歌词解析内置：标准 LRC（[mm:ss.xx]）解析，支持一行多标签、数组格式直传
• 样式隔离：组件样式均为 scoped，类名（ump- 前缀）不会泄漏到宿主页面
• 加载态反馈：换歌 / 地址解析期间显示加载指示，自动防止重复触发
• H5 键盘控制：PC 浏览器中空格播放 / 暂停，左右键快进 / 快退 5 秒，Esc 收起播放页

二、平台兼容性

2.1 总览

2.2 各端播放内核差异

三、快速开始（3 步接入）

第 1 步：引入播放器单例

import musicPlayer from '@/uni_modules/uni-music-player'

单例全局唯一，跨页面播放不中断。

第 2 步：设置播放列表并播放

musicPlayer.setPlaylist([
  {
    id: '1',                                    // 建议：列表内唯一
    title: '星光轨道',
    artist: '合成演示',
    cover: '/static/demo-music/cover1.png',     // 封面图
    src: '/static/demo-music/song1.wav',        // 音频直链；也支持 async (song) => url
    lrc: '[00:00.00]晚风穿过霓虹的街\n[00:03.00]星光落在你眼睑'  // LRC 文本
  }
], { index: 0, autoplay: true })

第 3 步：放置统一组件

<uni-music-player :visible="showPlayer" @open="showPlayer = true" @close="showPlayer = false" />

即可获得：迷你条常驻底部（无歌自动隐藏）→ 点击展开全屏播放页 → 弹性歌词 / 进度拖拽 / 播放列表 / 模式切换。

组件位于 uni_modules 且以 uni- 开头，HBuilderX 默认开启 easycom 自动注册；若项目关闭了 autoscan，手动 import 即可。

四、JS API

事件

只读状态

musicPlayer.song / playlist / index / lyrics / playing / loading / mode / currentTime / duration
（loading 为 true 表示正在加载音频或换歌）

五、组件属性与事件

uni-music-player（统一组件）

六、平台注意事项

1. App 后台播放：使用 getBackgroundAudioManager，锁屏与通知栏可控，支持耳机线控；真机后台播放需系统未锁定应用进程。
2. H5 自动播放策略：浏览器要求用户手势后才能播放，setPlaylist / play() 请在点击回调中调用，否则会有 autoplay 警告且无声。
3. 小程序后台播放：默认使用 InnerAudioContext，退到后台会中断（平台限制）。微信端如需真背景播放，请自行替换为 wx.getBackgroundAudioManager 并在 manifest.json 的 mp-weixin 中配置 requiredBackgroundModes: ["audio"]。
4. 小程序本地歌词：小程序端无法 request 读取包内 .lrc 文件，请将 LRC 文本内嵌到歌曲数据中（或从接口获取）。

七、常见问题

Q：组件样式会影响我的页面吗？
不会。组件 <style> 均为 scoped，所有类名（ump- 前缀）只在组件内部生效。

Q：点击播放没有声音 / 控制台报 autoplay 警告？
H5 浏览器要求用户手势触发播放，请在点击事件回调中调用 setPlaylist 或 play。

Q：如何替换默认图标 / 封面兜底图？
替换插件目录 static/icons/ 下的同名 PNG（建议保持尺寸与透明风格一致）。

Q：播放列表只有一首歌时，播放结束会怎样？
列表循环 / 单曲循环模式下重新播放当前歌曲；随机模式在单曲时退化为重播。

Q：正式商用有什么注意的？
内置图标资源沿用自开源音乐项目，正式商用前建议替换 static/icons/ 下图标以避免版权风险。

八、完整接入示例

参见项目内 pages/index/index.vue，核心逻辑：

import musicPlayer from '@/uni_modules/uni-music-player'
import demoSongs from '@/common/demo-music/songs.js'

// 设置播放列表（autoplay:false 只加载不播放，迷你条立即显示）
musicPlayer.setPlaylist(demoSongs, { index: 0, autoplay: false })

// 订阅事件驱动自己的 UI（on() 返回取消函数，页面卸载时统一调用）
const offs = [
  musicPlayer.on('change', (e) => { /* 更新当前下标 */ }),
  musicPlayer.on('playstate', (e) => { /* 同步播放状态 */ }),
  musicPlayer.on('error', (e) => { /* 播放失败提示 */ })
]

// 点击歌曲：在用户手势回调中播放（满足 H5 限制）
function playSong(i) {
  musicPlayer.play(i)
}