更新记录

1.0.0（2025-12-10）

• 插件初始版本

平台兼容性

uni-app(4.66)

uni-app x(4.66)

关于版本

【源码授权版】和【普通授权版】功能上是完全一样的。
【源码授权版】适用于项目对外部插件源代码有要求或者需要基于插件源码进行二次开发和定制的场景。

关于插件

本插件为uniapp提供耳机线控事件监听。支持有线耳机、蓝牙耳机。支持按钮事件、动作（播放、暂停、下一曲、上一曲等）事件、耳机连接断开事件。
如果你的APP对耳机线控事件感兴趣，例如：点击耳机播放按钮启动APP内智能AI语音助手等等，那么本插件非常适合。

如何使用

引入

import { UtsEarphoneEventHelper } from '@/uni_modules/ts-earphone-tool';

基本使用

启动事件监听

const earphoneEventHelper = new UtsEarphoneEventHelper()

function startEventListener() {
    earphoneEventHelper.startEventListener({
        title: "线控APP播放中", // 音乐标题，会在系统播放中心显示，适用于iOS、鸿蒙系统，安卓无效
        artist: "小妖粉粉",     // 音乐作者，会在系统播放中心显示，适用于iOS、鸿蒙系统，安卓无效

        connectEvent: (event) => {
            console.log(`连接事件：${JSON.stringify(event)}`)
        },
        actionEvent: (event) => {
            console.log(`动作事件：${JSON.stringify(event)}`)
        },
        keyEvent: (event) => {
            console.log(`按键事件：${JSON.stringify(event)}`)
            // 可以按需要进行过滤
            // 注意：iOS不支持按键事件，只支持动作事件
            if (event.platform == 'android') {
                if (event.keyAction == 'Down') {
                    logLabelItem("按键事件: ", JSON.stringify(event))
                }
            }
        },
        audioFocusEvent: (event) => {
            if (event.name == "Acquire") {
                console.log("APP获取到音频焦点")
            } else if (event.name == "Lose") {
                console.log("APP失去音频焦点，按键事件无法捕获")
            }
        },
        resultCallback: (errMsg) => {
            if (errMsg.code == 0) {
                console.log("启动事件监听成功")
            } else {
                console.log("启动事件监听失败")
            }
        }
    })
}

输出结果样例：

连接事件：{"type":"BluetoothHeadset","event":"Connect","name":"QE03"}
按键事件：{"platform":"android","keyName":"KEYCODE_MEDIA_PLAY","keyAction":"Down","keyCode":126}
动作事件：{"name":"Play"}
按键事件：{"platform":"android","keyName":"KEYCODE_MEDIA_PAUSE","keyAction":"Down","keyCode":127}
动作事件：{"name":"Pause"}
连接事件：{"type":"BluetoothHeadset","event":"Disconnect","name":"QE03"}

停止事件监听
当APP不再需要线控事件的时候，请停止监听服务

function stopEventListener() {
    earphoneEventHelper.stopEventListener({
        resultCallback: (errMsg) => {
            if (errMsg.code == 0) {
                console.log("停止事件监听成功")
            } else {
                console.log("停止事件监听失败")
            }
        }
    })
}

获取音频焦点
应用启动监听后，如果APP没有获取音频焦点是没法捕获线控事件的。
同样，APP获取的音频焦点，可能会被其他应用（例如音乐APP）抢断从而失去音频焦点。
这时候就需要主动获取音频焦点。

function acquireAudioFocus() {
    earphoneEventHelper.acquireAudioFocus({
        resultCallback: (errMsg) => {
            if (errMsg.code == 0) {
                console.log("获取音频焦点成功")
            } else {
                console.log("获取音频焦点失败")
            }
        }
    })
}

释放音频焦点
当APP不再需要线控事件的时候，可以主动释放音频焦点。

function releaseAudioFocus() {
    earphoneEventHelper.releaseAudioFocus({
        resultCallback: (errMsg) => {
            if (errMsg.code == 0) {
                console.log("释放音频焦点成功")
            } else {
                console.log("释放音频焦点失败")
            }
        }
    })
}

权限要求

安卓Android权限

需要增加以下权限

<!-- 蓝牙按键监听必要的权限 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<!-- Android 12+ 蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- 音频焦点权限 -->
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

苹果iOS权限

需要增加以下权限

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>
<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限来支持音频播放</string>