更新记录

1.0.0（2026-04-11）

首次发布，代替安卓端uni.getBackgroundAudioManager() 方法的原生通知栏音乐播放器，保活

平台兼容性

uni-app(3.7.3)

其他

lingrui-audio-player 使用说明

安卓端背景音频播放器 UTS 插件，用于替代 uni.getBackgroundAudioManager() 在安卓端没有系统播放器的问题。

背景

uni 官方的 uni.getBackgroundAudioManager() 在 iOS 端有完整的锁屏播放器，但在安卓端没有。本插件专为安卓端提供与官方 API 一致的接口，并实现系统级媒体通知栏播放器，支持封面、标题、进度条、上一曲/下一曲/暂停等控制。

安装步骤

1. 配置权限

在 manifest.json 的安卓权限中添加以下配置：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

2. 打包安卓自定义基座

插件使用 UTS 原生能力，必须打包安卓自定义基座后才能生效，标准基座不支持。

使用说明

引入插件

//#ifdef APP
import { AndroidBackgroundAudioManager } from "@/uni_modules/lingrui-audio-player";
//#endif

初始化

本插件的设计初衷是直接替换 uni.getBackgroundAudioManager()，如果你已经在使用官方方法，只需在安卓端切引入本插件后，把uni.getBackgroundAudioManager() 替换为 new AndroidBackgroundAudioManager()，其余代码无需修改。

const platform = uni.getSystemInfoSync().platform;

export default {
    data() {
        return {
            audioCtx: false
        }
    },
    onLoad() {
        this.initAudio()
    },
    methods: {
        // 背景音频初始化
        initAudio() {
            if (this.audioCtx) return;
            // #ifndef WEB
                //#ifdef APP
                    if (platform == 'android') {
                        try {
                            const mgr = new AndroidBackgroundAudioManager()
                            // 兜底判断：对象和关键方法是否存在
                            if (mgr && typeof mgr.play === 'function' && typeof mgr.pause === 'function') {
                                this.audioCtx = mgr
                            } else {
                                console.warn('UTS AndroidBackgroundAudioManager 方法缺失，使用兜底 uni.getBackgroundAudioManager()')
                                this.audioCtx = uni.getBackgroundAudioManager()
                            }
                        } catch (e) {
                            console.warn('UTS AndroidBackgroundAudioManager 初始化失败，使用兜底', e)
                            this.audioCtx = uni.getBackgroundAudioManager()
                        }
                    } else {
                        this.audioCtx = uni.getBackgroundAudioManager()
                    }
                //#endif
                //#ifndef APP
                this.audioCtx = uni.getBackgroundAudioManager();
                //#endif
            // #endif
            // #ifdef WEB
            this.audioCtx = uni.createInnerAudioContext();
            // #endif

            // 注册监听
            this.watchAudio()
        },

        // 监听音频事件
        watchAudio() {
            this.audioCtx.onPlay(() => {
                console.log('音频播放了')
            });
            this.audioCtx.onPause(() => {
                console.log('音频暂停了')
            });
            this.audioCtx.onWaiting(() => {
                console.log('音频等待中')
            });
            this.audioCtx.onCanplay((res) => {
                console.log('音频可以播放了')
            });
            this.audioCtx.onTimeUpdate((res) => {
                console.log('播放进度：', this.audioCtx.currentTime)
            });
            this.audioCtx.onEnded(() => {
                console.log('音频播放完了')
            });
            this.audioCtx.onError((res) => {
                console.log('音频出错了', res)
            });
            // #ifndef WEB
            this.audioCtx.onStop(() => {
                console.log('音频关闭')
            });
            this.audioCtx.onPrev(() => {
                console.log('点击上一曲')
            });
            this.audioCtx.onNext(() => {
                console.log('点击下一曲')
            });
            // #endif
        },

        // 播放
        startPlay() {
            this.audioCtx.title = '测试音频标题'
            this.audioCtx.singer = '作者'
            this.audioCtx.coverImgUrl = '封面图片地址'
            this.audioCtx.src = '音频文件地址'
            this.audioCtx.play()
        },

        // 暂停
        pause() {
            this.audioCtx.pause()
        },

        // 停止
        stop() {
            this.audioCtx.stop()
        },

        // 跳转到指定位置（单位：秒）
        seek(seconds) {
            this.audioCtx.seek(seconds)
        }

    }
}

API 文档

属性

方法

事件监听

注意事项

• 本插件仅支持安卓端 APP，iOS 和小程序请继续使用 uni.getBackgroundAudioManager()
• 必须使用自定义基座打包，标准基座无效
• 封面和播放地址需要可公网访问的URL 或者 本地图片
• 本地音频 plus.io.convertLocalFileSystemURL('/static/app/名称.mp3');
• 本地图片 'file://' + plus.io.convertLocalFileSystemURL('/static/app/图片.png');
• 播放 m3u8 串流格式需要设备安卓版本支持

建议

由于 uni.getBackgroundAudioManager() 全局唯一，强烈建议将音频管理器封装为全局唯一单例（如 Vuex store 或全局 mixin），避免多处实例化导致状态混乱。