更新记录

1.0.2（2024-11-20）

(注：不同hx版本最好重新打包基座，以避免出现版本差异的错误)

• 【新增】closeNotification 关闭消息订阅api；
• 【新增】requestPermission 请求权限api；
• 【修复】ios startScan 扫描蓝牙设备，设置不重复上报设备信息，第二次执行startScan扫描会过滤掉上一次扫描到的蓝牙设备，导致扫描不到全部蓝牙设备；
• 【更新】文档代码示例错误更正，分别列出uni和unix示例代码；

1.0.1（2024-11-11）

(注：不同hx版本最好重新打包基座，以避免出现版本差异的错误)

• 【新增】ios兼容；

• 【更新】android-兼容targetSdkVersion 34（广播接收器新增行为标志参数）；

• 【更新】兼容hx4.25版本+ 为了优化js回调性能，回调触发一次就会注销，导致无法持续触发回调的问题（本插件使用了hx4.27版本新增的“@UTSJS.keepAlive”装饰器解决了这个问题，所以本插件只支持 < hx4.25版本和 >= hx4.27版本）【详情请查看】;

• 【新增】android-支持多个低功耗蓝牙同时连接设备；

• 【更新】android-优化低功耗蓝牙连接成功发现服务失败的问题；

平台兼容性

xwe-bluetooth（低功耗蓝牙插件）

HBuilder X 支持版本

vue版本兼容

平台兼容

权限说明文档

• 【android】

内置注册权限：插件内配置了AndroidManifest.xml，内置权限如下：

注意：下面权限已经在插件内配置，项目中不需要重复配置了（权限配置兼容了android12+）

<uses-feature
    android:name="android.hardware.bluetooth_le"
    android:required="true" />

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<uses-permission
    android:name="android.permission.BLUETOOTH"
    android:maxSdkVersion="30" />
<uses-permission
    android:name="android.permission.BLUETOOTH_ADMIN"
    android:maxSdkVersion="30" />

<uses-permission
    android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation"
    tools:targetApi="S" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

动态申请权限：下面的权限是需要动态申请的：

//android12及其以上 需要动态申请以下权限（附近设备权限）【可合并申请】
android.permission.BLUETOOTH_SCAN
android.permission.BLUETOOTH_ADVERTISE
android.permission.BLUETOOTH_CONNECT

//android12以下 需要动态申请以下权限（定位权限）【可合并申请】
android.permission.ACCESS_COARSE_LOCATION
android.permission.ACCESS_FINE_LOCATION

除了以上权限，还需要下面功能开启

蓝牙开关开启、定位服务开关开启（定位服务android12及以上不需要，经过个人亲测在鸿蒙双系统的手机上必须要开启定位服务才能扫描到设备）

• 【ios】

内置注册权限：插件内配置了Info.plist，内置权限如下：

注意：下面权限已经在插件内配置，项目中不需要重复配置了

<dict>
    <key>NSBluetoothPeripheralUsageDescription</key>
    <string>开启蓝牙权限</string>
    <key>NSBluetoothAlwaysUsageDescription</key>
    <string>开启蓝牙权限</string>
</dict>

除了以上权限，还需要下面功能开启

蓝牙开关开启

接口使用文档

• 引入插件和实例化

import {XWEBlue} from '@/uni_modules/xwe-bluetooth';

let xweBlue = new XWEBlue();

• 引入插件所需类型

说明：ts/unix项目需要用到类型方可引用，不需要的可以不引用

import {
    MegOption,
    ScanOption,
    ConnectOption,
    RequestMtuOption,
    NotificationOption,
    WriteCharacteristicOption,
    GetDeviceServicesOption,
    GetDeviceCharacteristicsOption,
    XWEBlueRequestPermissionOption
} from '@/uni_modules/xwe-bluetooth'; 

• 初始化插件

xweBlue.initBle(callback)

说明：插件必须先初始化，否则无法调用蓝牙主要api，建议全局初始化一次就够了，最好不要多次调用初始化。

平台差异

callback返回参数说明

callbackOption结构说明

data结构说明（蓝牙设备断开连接的状态码：-21）【android数据结构】

说明：data返回的status状态数据，是为了在更多复杂场景中，拿到原始状态进行判断，才专门返回的数据，普通需求按照code返回的状态进行操作即可。

data结构说明（蓝牙设备断开连接的状态码：-21）【ios数据结构】

说明：data返回的domain、code、userInfo等数据，是为了在更多复杂场景中，拿到一些原始数据进行判断，才专门返回的数据，普通需求按照code返回的状态进行操作即可。

调用代码示例

【uniapp示例】
xweBlue.initBle((callbackOption) => {

    //初始化成功
    if(callbackOption.code == 1){
        console.log('初始化成功',callbackOption);
    }

    //【仅限ios】初始化蓝牙模块触发蓝牙权限-允许
    if(callbackOption.code == 15){
        console.log('授权了蓝牙权限',callbackOption);
    }

    //【仅限ios】初始化蓝牙模块触发蓝牙权限-拒绝
    if(callbackOption.code == -15){
        console.log('拒绝了蓝牙权限',callbackOption);
    }

    //连接断开-状态监听【android】
    if(callbackOption.code == -21){
        console.log('连接或断开连接状态',callbackOption.data.status);
        console.log('新的连接状态',callbackOption.data.newState);
        console.log('断开连接的设备deviceId',callbackOption.data.deviceId);
    }

    //连接断开-状态监听【ios】
    if(callbackOption.code == -21){
        console.log('断开连接错误域',callbackOption.data.domain);
        console.log('断开连接错误code',callbackOption.data.code);
        console.log('断开连接错误信息',callbackOption.data.userInfo);
        console.log('断开连接的设备deviceId',callbackOption.data.deviceId);
    }
});

【uniappX示例】
xweBlue.initBle((callbackOption) => {

    //初始化成功
    if(callbackOption.code == 1){
        console.log('初始化成功',callbackOption);
    }

    //【仅限ios】初始化蓝牙模块触发蓝牙权限-允许
    if(callbackOption.code == 15){
        console.log('授权了蓝牙权限',callbackOption);
    }

    //【仅限ios】初始化蓝牙模块触发蓝牙权限-拒绝
    if(callbackOption.code == -15){
        console.log('拒绝了蓝牙权限',callbackOption);
    }

    //连接断开-状态监听【android】
    if(callbackOption.code == -21){
        console.log('连接或断开连接状态',callbackOption.data?.['status']);
        console.log('新的连接状态',callbackOption.data?.['newState']);
        console.log('断开连接的设备deviceId',callbackOption.data?.['deviceId']);
    }

    //连接断开-状态监听【ios】
    if(callbackOption.code == -21){
        console.log('断开连接错误域',callbackOption.data?.['domain']);
        console.log('断开连接错误code',callbackOption.data?.['code']);
        console.log('断开连接错误信息',callbackOption.data?.['userInfo']);
        console.log('断开连接的设备deviceId',callbackOption.data?.['deviceId']);
    }
});

• 权限检测

xweBlue.permisCheck(callback)

说明：检测蓝牙权限是否满足条件，如果满足条件则返回10，不满足条件则返回对应的code码，详情查看【code状态码说明】

平台差异

callback返回参数说明

callbackOption结构说明

调用代码示例

【uniapp/uniappX示例】
xweBlue.permisCheck((callbackOption) => {
    if(callbackOption.code == 10){
        console.log('权限满足',callbackOption);
    }else{
        console.log('权限不满足',callbackOption);
    }
});

• 请求权限

xweBlue.requestPermission(callback)

平台差异

option结构说明

permission参数结构说明

callback返回参数说明

callbackOption结构说明

调用代码示例

//(android 12以下请求定位权限)
let permission = [
    'android.permission.ACCESS_FINE_LOCATION',
    'android.permission.ACCESS_COARSE_LOCATION'
];

//(android 12及其以上请求附近设备权限)
let permission = [
    'android.permission.BLUETOOTH_SCAN',
    'android.permission.BLUETOOTH_CONNECT',
    'android.permission.BLUETOOTH_ADVERTISE'
];

//(ios请求蓝牙权限)
let permission = [
    'bluetooth'
];

【uniapp示例】
xweBlue.requestPermission({
    permission:permission,
    callback:(callbackOption) => {

        console.log('requestPermission-请求权限',callbackOption);

        //允许权限
        if(callbackOption.code == 200){
            console.log('requestPermission-允许权限',callbackOption);
        }

        //拒绝权限
        if(callbackOption.code == 201){
            console.log('requestPermission-拒绝权限',callbackOption);
        }

        //永久拒绝权限【只限android会触发】
        if(callbackOption.code == 202){
            console.log('requestPermission-永久拒绝权限',callbackOption.data);
        }
    }
});

【uniappX示例】
xweBlue.requestPermission({
    permission:permission,
    callback:(callbackOption) => {

        console.log('requestPermission-请求权限',callbackOption);

        //允许权限
        if(callbackOption.code == 200){
            console.log('requestPermission-允许权限',callbackOption);
        }

        //拒绝权限
        if(callbackOption.code == 201){
            console.log('requestPermission-拒绝权限',callbackOption);
        }

        //永久拒绝权限【只限android会触发】
        if(callbackOption.code == 202){
            console.log('requestPermission-永久拒绝权限',callbackOption.data);
        }
    }
} as XWEBlueRequestPermissionOption);

• 开始扫描蓝牙设备

xweBlue.startScan(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

deviceType结构说明【ios不支持】

deviceType code结构说明【ios不支持】

调用代码示例

【uniapp示例】
xweBlue.startScan({
    allowDuplicatesKey:true,
    callback:(callbackOption) => {

        console.log('startScan-开始扫描蓝牙设备',callbackOption);

        //扫描开始
        if(callbackOption.code == 30){
            console.log('startScan-扫描开始',callbackOption);
        }

        //扫描失败
        if(callbackOption.code == -30){
            console.log('startScan-扫描失败',callbackOption);
        }

        //扫描成功
        if(callbackOption.code == 31){
            console.log('startScan-扫描到的设备数据',callbackOption.data);
        }

        //扫描结束
        if(callbackOption.code == -31){
            console.log('startScan-扫描结束',callbackOption);
        }
    }
});

【uniappX示例】
xweBlue.startScan({
    allowDuplicatesKey:true,
    callback:(callbackOption) => {

        console.log('startScan-开始扫描蓝牙设备',callbackOption);

        //扫描开始
        if(callbackOption.code == 30){
            console.log('startScan-扫描开始',callbackOption);
        }

        //扫描失败
        if(callbackOption.code == -30){
            console.log('startScan-扫描失败',callbackOption);
        }

        //扫描成功
        if(callbackOption.code == 31){
            console.log('startScan-扫描到的设备数据',callbackOption.data);
        }

        //扫描结束
        if(callbackOption.code == -31){
            console.log('startScan-扫描结束',callbackOption);
        }
    }
} as ScanOption);

• 停止扫描蓝牙设备

xweBlue.stopScan(callback)

注意：调用停止扫描成功，同时会触发开始扫描设备xweBlue.startScan的回调。

平台差异

callback返回参数说明

callbackOption结构说明

调用代码示例

【uniapp/uniappX示例】
xweBlue.stopScan((callbackOption) => {

    console.log('stopScan-停止扫描',callbackOption);

    //扫描结束
    if(callbackOption.code == -31){
        console.log('stopScan-扫描结束',callbackOption);
    }
});

• 连接蓝牙设备

xweBlue.connect(option)

注意：蓝牙设备断开连接，会触发插件初始化xweBlue.initBle的回调。

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明（连接相关的状态码：21、-20、-21）

说明：data返回的状态数据，是为了在更多复杂场景中，拿到原始状态进行判断，才专门返回的数据，普通需求按照code返回的状态进行操作即可。

data结构说明（发现服务的状态码：40）

调用代码示例

【uniapp示例】
xweBlue.connect({
    deviceId:'', 
    powerLevel:'CONNECTION_PRIORITY_BALANCED',
    reconnect:false,
    callback:(callbackOption) => {

        console.log('connect-连接蓝牙设备',callbackOption);

        //连接中
        if(callbackOption.code == 20){
            console.log('connect-连接中',callbackOption);
        }

        //连接失败
        if(callbackOption.code == -20){
            console.log('connect-连接失败',callbackOption);
        }

        //连接成功
        if(callbackOption.code == 21){
            console.log('connect-连接成功',callbackOption.data);
        }

        //发现服务特征
        if(callbackOption.code == 40){
            console.log('connect-发现服务特征',callbackOption.data);
        }

        //未发现服务特征
        if(callbackOption.code == -40){
            console.log('connect-未发现服务特征',callbackOption.data);
        }

    }
});

【uniappX示例】
xweBlue.connect({
    deviceId:'', 
    powerLevel:'CONNECTION_PRIORITY_BALANCED',
    reconnect:false,
    callback:(callbackOption) => {

        console.log('connect-连接蓝牙设备',callbackOption);

        //连接中
        if(callbackOption.code == 20){
            console.log('connect-连接中',callbackOption);
        }

        //连接失败
        if(callbackOption.code == -20){
            console.log('connect-连接失败',callbackOption);
        }

        //连接成功
        if(callbackOption.code == 21){
            console.log('connect-连接成功',callbackOption.data);
        }

        //发现服务特征
        if(callbackOption.code == 40){
            console.log('connect-发现服务特征',callbackOption.data);
        }

        //未发现服务特征
        if(callbackOption.code == -40){
            console.log('connect-未发现服务特征',callbackOption.data);
        }
    }
} as ConnectOption);

• 请求设置MTU最大传输单元

xweBlue.requestMtu(option)

注意：需要调用xweBlue.connect连接成功后，才能调用此接口。

【ios不支持，因为ios没有特定设置mtu的方式，ios是根据设备支持的大小自行协商，ios插件内置了这个方法，调用也会返回结果，但是只是一个伪调用。】

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明（设置成功状态码：60）

说明：data返回数据是系统api返回的一些原始数据，可能一些业务场景需要。

调用代码示例

【uniapp示例】
xweBlue.requestMtu({
    deviceId:'',
    mtu:200,
    callback:(callbackOption) => {

        console.log('requestMtu-请求设置mtu',callbackOption);

        //请求设置mtu成功
        if(callbackOption.code == 60){
            console.log('requestMtu-请求设置mtu成功',callbackOption.data);
        }

        //请求设置mtu失败
        if(callbackOption.code == -60){
            console.log('requestMtu-请求设置mtu失败',callbackOption);
        }

    }
})

【uniappX示例】
xweBlue.requestMtu({
    deviceId:'',
    mtu:200,
    callback:(callbackOption) => {

        console.log('requestMtu-请求设置mtu',callbackOption);

        //请求设置mtu成功
        if(callbackOption.code == 60){
            console.log('requestMtu-请求设置mtu成功',callbackOption.data);
        }

        //请求设置mtu失败
        if(callbackOption.code == -60){
            console.log('requestMtu-请求设置mtu失败',callbackOption);
        }

    }
} as RequestMtuOption);

• 断开蓝牙设备连接

xweBlue.disconnect(deviceId)

注意：蓝牙设备断开连接，会触发插件初始化xweBlue.initBle的回调。

平台差异

deviceId参数说明

• 释放蓝牙设备连接资源

xweBlue.close(deviceId)

平台差异

deviceId参数说明

• 获取蓝牙设备连接状态

xweBlue.isConnectState(deviceId)

平台差异

deviceId参数说明

return的数据

• 开启消息订阅

xweBlue.notification(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

调用代码示例

【uniapp示例】
xweBlue.notification({
    deviceId:'', 
    serviceId:'',
    characteristicId:'',
    callback:(callbackOption) => {

        console.log('notification-开启消息订阅',callbackOption);

        //开启消息订阅成功
        if(callbackOption.code == 50){
            console.log('notification-开启消息订阅成功',callbackOption);
        }

        //开启消息订阅失败
        if(callbackOption.code == -50){
            console.log('notification-开启消息订阅失败',callbackOption);
        }

        //收到消息通知
        if(callbackOption.code == 51){
            console.log('notification-收到消息通知',callbackOption.data);
        }

    }
});

【uniappX示例】
xweBlue.notification({
    deviceId:'', 
    serviceId:'',
    characteristicId:'',
    callback:(callbackOption) => {

        console.log('notification-开启消息订阅',callbackOption);

        //开启消息订阅成功
        if(callbackOption.code == 50){
            console.log('notification-开启消息订阅成功',callbackOption);
        }

        //开启消息订阅失败
        if(callbackOption.code == -50){
            console.log('notification-开启消息订阅失败',callbackOption);
        }

        //收到消息通知
        if(callbackOption.code == 51){
            console.log('notification-收到消息通知',callbackOption.data);
        }

    }
} as NotificationOption);

• 关闭消息订阅

xweBlue.closeNotification(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

调用代码示例

【uniapp示例】
xweBlue.closeNotification({
    deviceId:'', 
    serviceId:'',
    characteristicId:'',
    callback:(callbackOption) => {
        console.log('关闭消息订阅',callbackOption);
    }
});

【uniappX示例】
xweBlue.closeNotification({
    deviceId:'', 
    serviceId:'',
    characteristicId:'',
    callback:(callbackOption) => {
        console.log('关闭消息订阅',callbackOption);
    }
} as NotificationOption);

• 给设备写入数据

xweBlue.writeCharacteristic(option)

平台差异

option结构说明

writeType属性值说明

callback返回参数说明

callbackOption结构说明

data结构说明（写入失败的状态码：-55）【android数据结构】

说明：data返回的status状态数据，是为了在更多复杂场景中，拿到原始状态进行判断，才专门返回的数据，普通需求按照code返回的状态进行操作即可。

data结构说明（写入失败的状态码：-55）【ios数据结构】

说明：data返回的domain、code、userInfo等数据，是为了在更多复杂场景中，拿到一些原始数据进行判断，才专门返回的数据，普通需求按照code返回的状态进行操作即可。

调用代码示例

【uniapp示例】
xweBlue.writeCharacteristic({
    deviceId:'',
    serviceId:'',
    characteristicId:'',
    value:[0x0E,0x11],
    callback:(callbackOption) => {

         console.log('writeCharacteristic-设备写入数据',callbackOption);

        //写入数据成功
        if(callbackOption.code == 55){
            console.log('writeCharacteristic-写入数据成功',callbackOption);
        }

        //写入数据失败
        if(callbackOption.code == -55){
            console.log('writeCharacteristic-写入数据失败',callbackOption);
        }

    }
});

【uniappX示例】
xweBlue.writeCharacteristic({
    deviceId:'',
    serviceId:'',
    characteristicId:'',
    value:[0x0E,0x11],
    callback:(callbackOption) => {

        console.log('writeCharacteristic-设备写入数据',callbackOption);

        //写入数据成功
        if(callbackOption.code == 55){
            console.log('writeCharacteristic-写入数据成功',callbackOption);
        }

        //写入数据失败
        if(callbackOption.code == -55){
            console.log('writeCharacteristic-写入数据失败',callbackOption);
        }

    }
} as WriteCharacteristicOption);

• 获取设备所有服务

  xweBlue.getDeviceServices(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

sevices结构说明

调用代码示例

【uniapp示例】
xweBlue.getDeviceServices({
    deviceId:'',
    callback:(callbackOption) => {
         console.log('getDeviceServices-获取设备所有服务',callbackOption);

        //获取服务成功
        if(callbackOption.code == 40){
            console.log('getDeviceServices-获取服务成功',callbackOption.data.sevices);
        }
    }
});

【uniappX示例】
xweBlue.getDeviceServices({
    deviceId:'',
    callback:(callbackOption) => {

        console.log('getDeviceServices-获取设备所有服务',callbackOption);

        //获取服务成功
        if(callbackOption.code == 40){
            console.log('getDeviceServices-获取服务成功',callbackOption.data?.['sevices']);
        }

    }
} as GetDeviceServicesOption);

• 获取设备所选服务特征值

  xweBlue.getDeviceCharacteristics(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

characteristics结构说明

properties结构说明

调用代码示例

【uniapp示例】
xweBlue.getDeviceCharacteristics({
    deviceId:'',
    callback:(callbackOption) => {

        console.log('getDeviceServices-获取设备所有服务特征值',callbackOption);

        //获取服务特征值成功
        if(callbackOption.code == 40){
            console.log('getDeviceServices-获取服务特征值成功',callbackOption.data.characteristics);
        }
    }
});

【uniappX示例】
xweBlue.getDeviceCharacteristics({
    deviceId:'',
    callback:(callbackOption) => {

        console.log('getDeviceServices-获取设备所有服务特征值',callbackOption);

        //获取服务特征值成功
        if(callbackOption.code == 40){
            console.log('getDeviceServices-获取服务特征值成功',callbackOption.data?.['characteristics']);
        }

    }
} as GetDeviceServicesOption);

• 获取已连接的蓝牙设备

xweBlue.getConnectDevices(callback)

平台差异

callback返回参数说明

callbackOption结构说明

data结构说明

connectList结构说明

调用代码示例

【uniapp示例】
xweBlue.getConnectDevices((callbackOption) => {
    console.log('获取已连接的蓝牙设备',callbackOption.data.connectList);
});

【uniappX示例】
xweBlue.getConnectDevices((callbackOption) => {
    console.log('获取已连接的蓝牙设备',callbackOption.data?.['connectList']);
});

• 创建-监听状态事件(蓝牙状态、定位服务状态)

xweBlue.onReceiverStateChange(callback)

说明：主要监听蓝牙功能所需的一些系统功能状态，蓝牙开关、定位服务开关，ios只监听蓝牙开关状态。

平台差异

callback返回参数说明

callbackOption结构说明

调用代码示例

xweBlue.onReceiverStateChange((callbackOption) => {
    console.log('创建-监听状态事件(蓝牙状态、定位服务状态)',callbackOption);
});

• 注销-监听状态事件(蓝牙状态、定位服务状态)

xweBlue.unReceiverStateChange(callback)

说明：callback可以传为null，详情查看代码示例。

平台差异

callback返回参数说明

callbackOption结构说明

调用代码示例

xweBlue.unReceiverStateChange((callbackOption) => {
    console.log('注销-监听状态事件(蓝牙状态、定位服务状态)',callbackOption);
});

或

xweBlue.unReceiverStateChange(null);

• 开启蓝牙

  xweBlue.enable(callback)

说明：callback可以传为null，详情查看代码示例。

平台差异

callback返回参数说明

说明：ios不会触发此回调，android只会在android 12请求“附近设备权限”，权限被拒会触发此回调。想要监听蓝牙开关状态，请使用“onReceiverStateChange”进行监听。

callbackOption结构说明

调用代码示例

xweBlue.enable((callbackOption) => {
    if(callbackOption.code == -14){
        console.log('附近设备权限被拒',callbackOption);
    }
});

或

xweBlue.enable(null);

• 关闭蓝牙

  xweBlue.disable(callback)

说明：callback可以传为null，详情查看代码示例。

平台差异

callback返回参数说明

说明：ios不会触发此回调，android只会在android 12请求“附近设备权限”，权限被拒会触发此回调。想要监听蓝牙开关状态，请使用“onReceiverStateChange”进行监听。

callbackOption结构说明

调用代码示例

xweBlue.disable((callbackOption) => {
    if(callbackOption.code == -14){
        console.log('附近设备权限被拒',callbackOption);
    }
});

或

xweBlue.disable(null);

code状态码说明