更新记录

1.0.0（2026-07-23）

功能更新，兼容APP和H5

平台兼容性

uni-app(4.71)

其他

uni-audio-float — 全局音频播放悬浮按钮插件

一个轻量级的 uni-app 插件，在 App 和 H5 中提供可跨页面拖动的全局音频悬浮控制按钮，支持播放、暂停、关闭等操作，无缝衔接页面跳转。

📦 功能特点

• 全局悬浮：通过 position: fixed 固定在屏幕右下角，页面切换不中断，始终可见。
• 跨页面控制：基于单例 AudioManager，在任何页面均可控制同一音频实例，无需重复创建。
• 状态同步：组件自动监听管理器状态变化，实时更新 UI（播放/暂停图标、隐藏/显示）。
• 暗黑模式：自动检测系统主题（App 通过 plus.navigator.getUIStyle()，H5 通过 prefers-color-scheme），切换视觉风格。
• 宽屏适配：悬浮按钮尺寸上限 56px，在 iPad 等大屏设备上保持协调。
• 纯净实现：使用 uni-app 原生 API（uni.createInnerAudioContext），无第三方依赖；图标全部 CSS 绘制，无需额外图片资源。
• 事件预留：所有交互均包含 console.log 调试信息，方便扩展点击事件。

🖥️ 平台兼容性

📁 目录结构

uni_modules/muzi-audio-float/
├── package.json                     # 插件配置
├── components/
│   └── muzi-audio-float.vue         # 悬浮按钮 UI 组件
├── utils/
│   └── audioManager.js              # 全局音频管理器（单例）
└── readme.md                        # 文档

🚀 快速开始

1. 引入悬浮按钮组件

在项目根目录的 App.vue 中注册并放置组件，使其覆盖所有页面：

<template>
  <view>
    <router-view />
    <!-- 全局音频悬浮按钮 -->
    <muzi-audio-float />
  </view>
</template>

<script>
export default {
  name: 'App'
};
</script>

2. 在任意页面触发播放

<template>
  <view class="page">
    <button @click="playLocalAudio">播放本地音频</button>
    <button @click="pauseAudio">暂停</button>
    <button @click="stopAudio">停止并隐藏按钮</button>
  </view>
</template>

<script>
// 引入音频管理器单例
import audioManager from '@/uni_modules/muzi-audio-float/utils/audioManager.js';

export default {
  methods: {
    // 播放示例：使用本地 static 目录下的音频
    playLocalAudio() {
      audioManager.play({
        src: '/static/ylsh.mp3',   // 替换为实际音频路径
        title: '示例音乐',
        cover: ''                   // 预留封面字段
      });
    },
    pauseAudio() {
      audioManager.pause();
    },
    stopAudio() {
      audioManager.stop();
    }
  }
};
</script>

3. 效果预览

• 点击播放后，屏幕右下角浮现红色圆形悬浮按钮，内含播放/暂停图标。
• 手指或鼠标悬停时，显示音频标题气泡。
• 右上角有关闭按钮，点击后停止播放并隐藏悬浮按钮。
• 页面跳转时按钮始终存在，音乐持续播放。

⚙️ API 文档（AudioManager）

所有方法均通过导入的单例调用：
import audioManager from '@/uni_modules/muzi-audio-float/utils/audioManager.js';

play(options)

开始播放新音频。若已有音频在播，会先停止再播放。

参数

• options.src (String) : 音频文件地址（网络/本地）
• options.title (String) : 音频标题，显示在悬浮按钮提示中
• options.cover (String) : 封面图（预留，暂未使用）

示例

audioManager.play({
  src: 'https://example.com/music.mp3',
  title: '歌曲名',
  cover: ''
});

pause()

暂停当前音频。

resume()

继续播放（从暂停位置恢复）。

stop()

停止播放并销毁音频实例，同时隐藏悬浮按钮（hasAudio 置为 false）。

togglePlayPause()

切换播放/暂停状态（悬浮按钮点击时调用）。

addListener(callback)

注册状态监听器，回调参数为完整状态对象。

状态对象字段：

• src : 音频源
• title : 标题
• cover : 封面
• isPlaying : 是否正在播放
• isPaused : 是否已暂停
• duration : 总时长（秒）
• currentTime : 当前播放进度（秒）
• hasAudio : 是否有音频加载（决定按钮显隐）

removeListener(callback)

移除对应的监听器。

❗ 注意事项

1. 音频路径问题

   • 本地资源：使用 /static/xxx.mp3 路径，编译后直接映射到根目录，App 与 H5 通用。
   • 网络资源：H5 端需确保音频服务器配置 CORS 或使用同源地址，否则会因跨域无法播放。
   • 真机调试：Android/iOS 本地音频文件必须放置在 static 目录下。

2. 全局唯一性
   音频管理器为单例，请勿自行 new AudioManager()，始终从模块导入同一个实例。

3. 按钮位置
   悬浮按钮默认距右侧 24rpx，距底部 120rpx。若被原生导航栏或 TabBar 遮挡，可调整 .audio-float-container 的 bottom 值。

4. 销毁行为
   调用 stop() 会销毁音频上下文并隐藏按钮；若仅需暂停保留按钮，请使用 pause()。

5. 暗黑模式
   H5 自动跟随系统主题变化；App 端通过 plus.navigator.getUIStyle() 检测，部分旧版安卓可能需额外处理。

6. 事件扩展
   组件内的 handleFloatClick、handleClose 等方法已预留 console.log，开发者可按需重写添加自定义逻辑（如跳转播放详情页等）。

📝 License

MIT © muzi

示例音频：/static/ylsh.mp3（需自行放入项目 static 目录）
问题反馈：评论留言，看到之后会及时答复