更新记录

1.0.0（2025-12-03）

初始版本，测试机使用Android 14和HarmonyOS 4.2.0

平台兼容性

uni-app(4.0)

uni-app x(4.0)

其他

蓝牙BLE插件，支持Android端PHY 2M模式和连接优先级设置，用于大量数据的快速传输

引入并初始化插件并初始化

import { BleFast } from '@/uni_modules/xw-ble';
// 初始化实例
const instance = BleFast()
// 
instance.openBluetoothAdapter({
    connectOverTime: 30000, // 全局设置连接超时时间为30秒
    success: (res) => {
        console.log("bluetooth adapter ok")
        // 可以监听蓝牙状态并进行其他操作了...
    },
    fail: (e) => {
        console.error("bluetooth adapter fail", e)
    }
})

蓝牙授权验证并设置全局参数

openBluetoothAdapter({
    connectOverTime ?: 'int, 设置连接超时时间（毫秒），默认10秒',
    operateTimeout ?: 'int, 设置write、read、notify的超时时间（毫秒），默认5秒',
    success ?: '成功回调，返回成功初始化信息',
    fail ?: '失败回调，返回错误信息'
})

监听蓝牙适配器状态

onBluetoothAdapterStateChange(function(res) {
    /* {
        available： 'boolean, 蓝牙适配器是否可用',
        discovering: 'boolean, 蓝牙适配器是否处于搜索状态'
    } */
})

监听设备发现状态

onBluetoothDeviceFound(function(res) {
    /* devices: [{
        deviceId: 'string, 设备Mac标识',
        name: 'string, 设备名称',
        RSSI: 'int, 信号',
        timestampNanos: 'long, 连接时间'
    }] */
})

监听设备连接状态

onBLEConnectionStateChange(function(res) {
    /* {
        deviceId: 'string, 设备Mac标识',
        connected: 'boolean, 是否连接'
    } */
})

监听特征值变化

onBLECharacteristicValueChange(function(res) {
    {
        deviceId: 'string, 设备Mac标识',
        serviceId: 'string, 服务ID',
        characteristicId: 'string, 特征ID',
        value: 'byte[], 特征值字节码'
    }
})

扫描蓝牙设备

scan({
    interval ?: 'long, 扫描时长，毫秒，默认10秒，小于等于0表示不限制扫描时间',
    services ?: 'string[], 过滤服务ID',
    success ?: '成功回调',
    fail ?: '失败回调'
})

取消扫描

cancelScan()

获取设备服务列表

getBLEDeviceServices({
    deviceId: '设备Mac标识',
    success ?: function(rst) {
        // 成功回调
        {
            services: [{
                uuid: 'string, 服务ID',
                isPrimary: 'boolean, 是否主服务'
            }]
        }
    },
    fail ?: '失败回调'
})

获取设备服务列表

getBLEDeviceCharacteristics({
    deviceId: 'string, 设备Mac标识',
    serviceId ?: 'string, 需要过滤的服务ID',
    success ?: function(res) {
        // 成功回调
        {
            deviceId: '设备Mac标识',
            characteristics: [{
                serviceId: 'string, 服务标识',
                uuid: 'string, 特征标识',
                read: 'boolean, 特征是否支持Read操作',
                write: 'boolean, 特征是否支持Write操作',
                notify: 'boolean, 特征是否支持Notify操作',
                indicate: 'boolean, 特征是否支持Indicate操作'
            }]
        }
    },
    fail ?: '失败回调'
})

连接设备

createBLEConnection({
    deviceId : 'string, 设备Mac标识',
    success ?: '成功回调',
    fail ?: '失败回调'
})

连接设置，部分设备在连续设置时需要延迟并分开设置才能成功，createBLEConnection方法中也能设置这些参数

connectSetting({
    deviceId : 'string, 设备Mac标识',
    mtu ?: 'int, 设置最大传输单元，(22,512) 区间内，默认23个Byte',
    phy2m ?: 'boolean, 设置PHY 2M模式，一般无需设置会自适应',
    priority ?: 'int, 设置连接优先级，建议在大量数据快速传输完成后设置为默认值，0-默认值；1-连接快的值，当需要跟设备进行大的数据传输时设置该值，2-低功耗值',
    success ?: '成功回调',
    fail ?: '失败回调'
})

读取特征值

readBLECharacteristicValue({
    deviceId: 'string, 设备Mac标识',
    serviceId: 'string, 服务标识',
    characteristicId: 'string, 特征标识',
    success : '成功回调，返回字节数组',
    fail ?: '失败回调'
})

写入特征值

writeBLECharacteristicValue({
    deviceId: 'string, 设备Mac标识',
    serviceId: 'string, 服务标识',
    characteristicId: 'string, 特征标识',
    value : 'array[int], 写入的字节数组',
    success ?: '成功回调',
    fail ?: '失败回调'
})

订阅特征值，先启用onBLECharacteristicValueChange才能监听到设备特征值变化事件

notifyBLECharacteristicValueChange({
    deviceId: 'string, 设备Mac标识',
    serviceId: 'string, 服务标识',
    characteristicId: 'string, 特征标识',
    state ?: 'boolean, 为false时关闭notify功能，默认为true',
    success ?: '成功回调',
    fail ?: '失败回调'
})

订阅特征值，先启用onBLECharacteristicValueChange才能监听到设备特征值变化事件

indicateBLECharacteristicValueChange({
    deviceId: 'string, 设备Mac标识',
    serviceId: 'string, 服务标识',
    characteristicId: 'string, 特征标识',
    state ?: 'boolean, 为false时关闭indicate功能，默认为true',
    success ?: '成功回调',
    fail ?: '失败回调'
})

关闭连接

closeBLEConnection(deviceId: string)

关闭蓝牙适配器，释放资源

closeBluetoothAdapter({
    success ?: '成功回调',
    fail ?: '失败回调'
})