更新记录

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 type {
    MegOption
} 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) => {
    console.log('初始化成功',callbackOption);

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

    //连接断开-状态监听【ios】
    if(callbackOption.code == -21 && callbackOption.data){
        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) => {
    console.log('初始化成功',callbackOption);

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

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

• 权限检测

xweBlue.permisCheck()

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

平台差异

callback返回参数说明

callbackOption结构说明

调用代码示例

xweBlue.permisCheck({
    callback:(callbackOption) => {
        if(callbackOption.code == 10){
            console.log('权限满足',callbackOption);
        }else{
            console.log('权限不满足',callbackOption);
        }
    }
});

• 开始扫描蓝牙设备

xweBlue.startScan(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

deviceType结构说明【ios不支持】

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

调用代码示例

xweBlue.startScan({
    allowDuplicatesKey:true,
    callback:(callbackOption) => {
        let dataObj = callbackOption.data || {};
        if(Object.keys(dataObj).length > 0){
            console.log('扫描到的设备数据',dataObj);
        }
    }
});

• 停止扫描蓝牙设备

xweBlue.stopScan(callback)

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

平台差异

callback返回参数说明

callbackOption结构说明

• 连接蓝牙设备

xweBlue.connect(option)

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

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

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

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

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

调用代码示例

xweBlue.connect({
    deviceId:'', 
    powerLevel:'CONNECTION_PRIORITY_BALANCED',
    reconnect:false,
    callback:(callbackOption) => {
        let dataObj = callbackOption.data || {};
        console.log('设备连接状态',callbackOption,dataObj);
    }
});

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

xweBlue.requestMtu(option)

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

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

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

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

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

调用代码示例

xweBlue.requestMtu({
    deviceId:'',
    mtu:200,
    callback:(callbackOption) => {
        let dataObj = callbackOption.data || {};
        console.log('mtu设置状态',callbackOption,dataObj);
    }
})

• 断开蓝牙设备连接

xweBlue.disconnect(deviceId)

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

平台差异

deviceId参数说明

• 释放蓝牙设备连接资源

xweBlue.close(deviceId)

平台差异

deviceId参数说明

• 获取蓝牙设备连接状态

xweBlue.isConnectState(deviceId)

平台差异

deviceId参数说明

return的数据

• 开启消息订阅

xweBlue.notification(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

调用代码示例

xweBlue.notification({
    deviceId:'', 
    serviceId:'',
    characteristicId:'',
    callback:(callbackOption) => {
        let dataObj = callbackOption.data || {};
        console.log('消息通知',callbackOption,dataObj);
    }
});

• 给设备写入数据

xweBlue.writeCharacteristic(option)

平台差异

option结构说明

writeType属性值说明

callback返回参数说明

callbackOption结构说明

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

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

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

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

调用代码示例

xweBlue.writeCharacteristic({
    deviceId:'',
    serviceId:'',
    characteristicId:'',
    value:[0x0E,0x11],
    callback:(callbackOption) => {
        let dataObj = callbackOption.data || {};
        console.log('写入状态',callbackOption,dataObj);
    }
});

• 获取设备所有服务

  xweBlue.getDeviceServices(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

sevices结构说明

调用代码示例

xweBlue.getDeviceServices({
    deviceId:'',
    callback:(callbackOption) => {
        let dataObj = callbackOption.data || {};
        console.log('获取到的设备服务',callbackOption,dataObj);
    }
});

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

  xweBlue.getDeviceCharacteristics(option)

平台差异

option结构说明

callback返回参数说明

callbackOption结构说明

data结构说明

characteristics结构说明

properties结构说明

调用代码示例

xweBlue.getDeviceCharacteristics({
    deviceId:'',
    callback:(callbackOption) => {
        let dataObj = callbackOption.data || {};
        console.log('获取到的设备服务特征值',callbackOption,dataObj);
    }
});

• 获取已连接的蓝牙设备

xweBlue.getConnectDevices(callback)

平台差异

callback返回参数说明

callbackOption结构说明

data结构说明

connectList结构说明

调用代码示例

xweBlue.getConnectDevices((callbackOption) => {
    let dataObj = callbackOption.data || {};
    console.log('获取已连接的蓝牙设备',callbackOption,dataObj.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状态码说明