更新记录

1.6.0（2025-06-25） 下载此版本

[1.6.0] - 2024-12-25

平台兼容性

云端兼容性

uni-app(4.72)

uni-app x(4.72)

其他

sanyue-music-player

一个功能完整、稳定可靠的 uni-app 音乐播放器插件，严格按照 uni_modules 插件规范开发，支持多平台兼容和 Vue2/Vue3 双版本。

🎵 插件特性

核心功能

• 完整的音频播放控制 - 播放、暂停、停止、进度条拖拽、音量控制
• 播放列表管理 - 支持播放列表、上一首/下一首、三种播放模式
• 歌词显示支持 - 支持 LRC 格式歌词，带翻译功能
• 双模式切换 - 普通模式与迷你模式无缝切换
• 主题系统 - 内置浅色/深色主题，支持自动切换

技术特性

• 多平台兼容 - 支持 App(iOS/Android)、H5、各种小程序
• Vue 双版本支持 - 同时支持 Vue2 和 Vue3
• TypeScript 支持 - 完整的类型定义，提供智能提示
• 响应式设计 - 使用 Flex 布局和 rpx 单位，完美适配各种设备
• SCSS 样式 - 模块化样式管理，易于定制

规范符合性

• uni_modules 标准 - 严格按照 uni-app 插件规范开发
• 平台兼容性 - 通过官方兼容性测试
• 代码质量 - 遵循最佳实践，确保稳定性

📦 安装使用

方式一：HBuilderX 插件市场

1. 在 HBuilderX 中打开项目
2. 点击工具栏的 "插件市场"
3. 搜索 "sanyue-music-player"
4. 点击 "导入插件" 并选择 "导入到项目"

方式二：手动安装

1. 下载插件包并解压
2. 将 uni_modules/sanyue-music-player 文件夹复制到项目根目录的 uni_modules 文件夹中
3. 在 HBuilderX 中右键点击 uni_modules/sanyue-music-player，选择 "安装插件依赖"

🚀 快速开始

基础使用

<template>
  <view class="container">
    <sanyue-music-player
      :src="audioSrc"
      :title="songTitle"
      :artist="songArtist"
      :cover="songCover"
      @play="onPlay"
      @pause="onPause"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      audioSrc: 'https://example.com/music.mp3',
      songTitle: '示例歌曲',
      songArtist: '示例艺术家',
      songCover: 'https://example.com/cover.jpg'
    }
  },
  methods: {
    onPlay() {
      console.log('开始播放');
    },
    onPause() {
      console.log('暂停播放');
    }
  }
}
</script>

播放列表使用

<template>
  <view class="container">
    <sanyue-music-player
      :playlist="playlist"
      :current-index="currentIndex"
      :play-mode="playMode"
      @song-change="onSongChange"
      @prev="onPrev"
      @next="onNext"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      currentIndex: 0,
      playMode: 'list', // list, single, random
      playlist: [
        {
          src: 'https://example.com/song1.mp3',
          title: '歌曲1',
          artist: '艺术家1',
          cover: 'https://example.com/cover1.jpg'
        },
        {
          src: 'https://example.com/song2.mp3',
          title: '歌曲2',
          artist: '艺术家2',
          cover: 'https://example.com/cover2.jpg'
        }
      ]
    }
  },
  methods: {
    onSongChange(event) {
      console.log('歌曲切换:', event.song.title);
      this.currentIndex = event.index;
    },
    onPrev(event) {
      console.log('上一首:', event.song.title);
      this.currentIndex = event.index;
    },
    onNext(event) {
      console.log('下一首:', event.song.title);
      this.currentIndex = event.index;
    }
  }
}
</script>

迷你播放器使用

<template>
  <view class="music-app">
    <!-- 主内容区域 -->
    <scroll-view class="content" scroll-y>
      <!-- 歌曲列表等内容 -->
      <view class="song-list">
        <!-- 歌曲列表内容 -->
      </view>
    </scroll-view>

    <!-- 迷你播放器 -->
    <sanyue-music-player
      :mini-mode="true"
      :src="currentSong.src"
      :title="currentSong.title"
      :artist="currentSong.artist"
      :cover="currentSong.cover"
      :show-mini-progress="true"
      class="mini-player"
      @mode-change="onModeChange"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      currentSong: {
        src: 'https://example.com/music.mp3',
        title: '当前播放歌曲',
        artist: '艺术家',
        cover: 'https://example.com/cover.jpg'
      }
    }
  },
  methods: {
    onModeChange(mode) {
      console.log('模式切换:', mode);
    }
  }
}
</script>

<style lang="scss" scoped>
.music-app {
  height: 100vh;
  display: flex;
  flex-direction: column;
}

.content {
  flex: 1;
  height: 0; // 重要：确保 flex 子元素正确计算高度
}

.mini-player {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  z-index: 999;
}
</style>

📋 API 参考

Props 属性

Events 事件

Methods 方法

通过 ref 调用组件方法：

<template>
  <sanyue-music-player ref="player" />
</template>

<script>
export default {
  methods: {
    playMusic() {
      this.$refs.player.play();
    },
    pauseMusic() {
      this.$refs.player.pause();
    },
    seekTo(time) {
      this.$refs.player.seek(time);
    }
  }
}
</script>

🎨 样式定制

主题定制

<template>
  <sanyue-music-player
    theme="dark"
    class="custom-player"
  />
</template>

<style lang="scss" scoped>
.custom-player {
  // 自定义样式
  --primary-color: #ff6b6b;
  --background-color: #2c3e50;
  --text-color: #ecf0f1;

  ::v-deep .sanyue-player {
    background: var(--background-color);
    color: var(--text-color);

    .control-btn.play-btn {
      background: var(--primary-color);
    }
  }
}
</style>

响应式设计

插件使用 rpx 单位和 Flex 布局，自动适配不同设备：

// 小屏幕适配
@media (max-width: 750rpx) {
  .cover-section .cover-container {
    width: 300rpx;
    height: 300rpx;
  }
}

// 大屏幕适配
@media (min-width: 1200rpx) {
  .cover-section .cover-container {
    width: 500rpx;
    height: 500rpx;
  }
}

🔧 高级功能

歌词功能

<template>
  <sanyue-music-player
    :show-lyrics="true"
    :lyrics="lyrics"
    :show-translation="true"
  />
</template>

<script>
export default {
  data() {
    return {
      lyrics: [
        { time: 0, text: '第一句歌词', translation: 'First line lyrics' },
        { time: 5.5, text: '第二句歌词', translation: 'Second line lyrics' },
        { time: 12.3, text: '第三句歌词', translation: 'Third line lyrics' }
      ]
    }
  }
}
</script>

错误处理

<template>
  <sanyue-music-player
    :src="audioSrc"
    @error="onError"
    @cover-error="onCoverError"
  />
</template>

<script>
export default {
  methods: {
    onError(event) {
      console.error('播放器错误:', event.message);
      uni.showToast({
        title: '播放失败',
        icon: 'none'
      });
    },
    onCoverError() {
      console.warn('封面加载失败');
    }
  }
}
</script>

TypeScript 支持

import { SongInfo, PlayMode } from 'sanyue-music-player';

interface ComponentData {
  playlist: SongInfo[];
  currentIndex: number;
  playMode: PlayMode;
}

export default {
  data(): ComponentData {
    return {
      playlist: [
        {
          src: 'https://example.com/music.mp3',
          title: '歌曲标题',
          artist: '艺术家',
          cover: 'https://example.com/cover.jpg'
        }
      ],
      currentIndex: 0,
      playMode: 'list'
    };
  }
};

🌍 平台兼容性

🐛 常见问题

Q: 音频无法播放？

A: 请检查以下几点：

1. 音频文件地址是否正确且可访问
2. 音频格式是否被平台支持（推荐使用 mp3 格式）
3. 网络连接是否正常
4. 是否有跨域问题（H5 平台）

Q: 在小程序中无法播放？

A: 小程序平台需要注意：

1. 音频文件域名需要在小程序后台配置为合法域名
2. 部分小程序平台对音频格式有限制
3. 确保音频文件支持 HTTPS 访问

Q: 样式显示异常？

A: 请检查：

1. 是否正确引入了组件
2. 是否有样式冲突
3. 确保使用了正确的 rpx 单位

Q: Vue3 项目中如何使用？

A: Vue3 项目直接使用主组件：

<script setup>
import { ref } from 'vue';

const playerRef = ref(null);

const playMusic = () => {
  playerRef.value?.play();
};
</script>

<template>
  <sanyue-music-player ref="playerRef" />
</template>

Q: Vue2 项目中如何使用？

A: Vue2 项目使用 Vue2 兼容版本：

<template>
  <sanyue-music-player-vue2 ref="player" />
</template>

<script>
export default {
  methods: {
    playMusic() {
      this.$refs.player.play();
    }
  }
}
</script>

📄 更新日志

v1.6.0 (2024-12-25)

• 🎉 严格按照 uni_modules 插件规范重构
• 🔧 修复上一首/下一首功能异常问题
• 🎨 全面采用 Flex 布局和 SCSS 语法
• 📱 统一使用 rpx 单位，完美适配各种设备
• 🛠️ 优化代码结构，提升稳定性
• 📚 完善 TypeScript 类型定义
• 🐛 修复已知问题，提升用户体验

v1.5.0 (2024-12-24)

• 🔧 修复播放控制功能异常
• 🎨 优化界面布局和样式
• 📱 改进迷你播放器设计
• 🛠️ 代码优化和性能提升

📜 开源协议

本插件采用 MIT 开源协议，您可以自由使用、修改和分发。

sanyue-music-player - 让音乐播放更简单、更优雅！