更新记录

1.0.4（2025-06-04）

添加requestPermission权限校验

1.0.3（2025-06-04）

添加isCreateConnected方法空指针异常

1.0.2（2025-06-04）

添加isCreateConnected方法: 检测某个蓝牙是否已连接

平台兼容性

uni-app x

uck-LeBluetooth

uck-LeBluetooth 是一个低功率蓝牙解决方案实现，让开发者专注业务

插件特色

• uts跨平台能力

使用

初始化配置

插件提供了简单的初始化配置

import { UckBluetoothConfig, UInitConfig } from "@/uni_modules/uck-LeBluetooth";
const le: UBluetoothManager = UckBluetoothConfig({
    type: "bluetooth"   // 标识
})

requestPermission 初始化: 权限校验

提示: 建议在使用蓝牙(搜索，连接)业务前，检测应用是否已经获取到对应权限

le?.requestPermission({
    bluetooth: "蓝牙权限受限提示语",
    location: "位置授权提示语（在高版本的情况下使用到位置权限）"
    callback: () => {
        console.log("权限已授权完毕");
    }
} as RequestPermissionOptions)

参数 RequestPermissionOptions

initScanRule 配置扫描规则

let setting = uni.getSystemSetting();
if(!(setting.bluetoothEnabled ?? false)){
    uni.showModal({
        title: "系统提示",
        content: "请打开蓝牙或授权蓝牙给应用",
        confirmText: "我已知晓",
        showCancel: false
    })
    return;
}
le?.initScanRule({
    scanTimeOut: 10000,
    initBallback: () => {
        console.log("配置扫描规则成功");
    }
} as UInitScanRuleOptions)

参数 UInitScanRuleOptions

scanBluetooth 开始扫描低功耗蓝牙

le?.scanBluetooth({
    onScanStarted: (success: boolean) => {
        console.log("开始扫描: ", success)
    },
    onScanning: (device: UDevice) => {
        console.log("搜索到蓝牙: ", device);
    },
    onScanFinished: (device: UDevice[]) => {
        console.log("扫描结束: ", device.length);
    }
} as ScanLeBluetoothOptions)

参数 ScanLeBluetoothOptions

cancelScanBluetooth 停止扫描低功率蓝牙

le?.cancelScanBluetooth(() => {
    console.log("停止扫描低功率蓝牙");
})

参数

createBluetoothConnection 连接蓝牙

le?.createBluetoothConnection({
    deviceId: this.address,
    onStartConnect: () => {
        console.log("连接蓝牙-开始连接");
    },
    onConnectFail: (device: UDevice, message: LeException) => {
        console.log("连接蓝牙-连接失败:", device, message);
    },
    onConnectSuccess: (device: UDevice, status: number) => {
        console.log("连接蓝牙-连接成功:", device, status);
    },
    onDisConnected: (isActiveDisConnected: boolean, device: UDevice, status: number) => {
        console.log("连接蓝牙-连接中断:", isActiveDisConnected, device, status);
    }
} as CreateUBLEConnectionOptions)

参数 CreateUBLEConnectionOptions

isCreateConnected 检测某个蓝牙是否已连接

let isConnected: boolean = le?.isCreateConnected(deviceId) ?? false;

参数

// 蓝牙地址（必须）
deviceId

// 是否已连接: true)已连接  false)未连接
isConnected

getBluetoothGattServices 获取某个已连接设备的所有Service

le?.getBluetoothGattServices({
    deviceId: deviceId,
    success: (services: string[]) => {
        console.log("获取某个已连接设备的所有Service", services.length);
        for(let i = 0; i < services.length; i++){
            console.log("Service UUID: ", services[i]);
        }
    }
} as GetBluetoothGattServicesOptions)

参数 GetBluetoothGattServicesOptions

getBluetoothGattCharacteristics 获取某个Service的所有Characteristic

le?.getBluetoothGattCharacteristics({
    deviceId: deviecId,
    serviceId: serviceId,
    success: (res: GattCharacteristics[]) => {
        console.log("所有Characteristic === :", res.length);
        for(let i = 0; i < res.length; i++){
            console.log("所有Characteristic === item: ", res[i]);
        }
    }
} as GetBluetoothGattCharacteristicsOptions)

参数 GetBluetoothGattCharacteristicsOptions

notifyBluetooth 订阅通知notify

le?.notifyBluetooth({
    deviceId: this.deviceId,
    uuidService: this.serviceId,
    uuidNotify: this.notifyId,
    onNotifySuccess: () => {
        console.log("订阅通知notify-成功:");
    },
    onNotifyFailure: (message: LeException) => {
        console.log("订阅通知notify-失败:", message);
    },
    onCharacteristicChanged: (data: number[], value: string) => {
        console.log("订阅通知notify-数据:", data.length, value);
    },
} as NotifyBluetoothOptions)

参数 NotifyBluetoothOptions

stopNotifyBluetooth 取消订阅通知notify

le?.stopNotifyBluetooth({
    deviceId: this.deviceId,
    uuidService: this.serviceId,
    uuidNotify: this.notifyId,
    notifyCallback: () => {
        console.log("取消订阅通知notify成功");
    }
} as StopnotifyBluetoothOptions)

参数 StopnotifyBluetoothOptions

indicateBluetooth 订阅通知indicate

le?.indicateBluetooth({
    deviceId: this.deviceId,
    uuidService: this.serviceId,
    uuidIndicate: this.indicateId,
    onIndicateSuccess: () => {
        console.log("订阅通知indicate成功:");
    },
    onIndicateFailure: (message: LeException) => {
        console.log("订阅通知indicate失败:", message);
    },
    onCharacteristicChanged: (data: number[], value: string) => {
        console.log("订阅通知indicate数据:", data.length, value);
    },
} as IndicateBluetoothOptions)

参数 IndicateBluetoothOptions

stopIndicateBluetooth 取消订阅通知indicate

le?.stopIndicateBluetooth({
    deviceId: this.deviceId,
    uuidService: this.serviceId,
    uuidIndicate: this.indicateId,
    notifyCallback: () => {
        console.log("取消订阅通知indicate成功");
    }
} as StopIndicateBluetoothOptions)

参数 StopIndicateBluetoothOptions

writeBluetooth 写

let writeData = "AAAA";
le?.writeBluetooth({
    deviceId: this.deviceId,
    uuidService: this.serviceId,
    uuidWrite: this.writeId,
    data: writeData,
    onWriteSuccess: (current: number, total: number, justWrite: number[], writeData: string) => {
        console.log("发送数据-成功:", current, total, justWrite.length);
    },
    onWriteFailure: (message: LeException) => {
        console.log("发送数据-失败:", message);
    }
} as WriteBluetoothOptions)

参数 WriteBluetoothOptions

readBluetooth 读

le?.readBluetooth({
    deviceId: this.deviceId,
    uuidService: this.serviceId,
    uuidRead: this.readId,
    onReadSuccess: (data: number[], value: string) => {
        console.log("读-成功:", data.length, value);
    },
    onReadFailure: (message: LeException) => {
        console.log("读-失败:", message);
    }
} as ReadBluetoothOptions)

参数 ReadBluetoothOptions

readRssiBluetooth 获取设备的信号强度Rssi

le?.readRssiBluetooth({
    deviceId: this.deviceId,
    onRssiFailure: (message: LeException) => {
        console.log("获取Rssi-失败:", message);
    },
    onRssiSuccess: (rssi: number) => {
        console.log("获取Rssi-成功:", rssi);
    }
} as ReadRssiBluetoothOptions);

参数 ReadRssiBluetoothOptions

disconnectBluetooth 断开某个设备

le?.disconnectBluetooth({
    deviceId: this.deviceId,
    callback: () => {
        console.log("断开连接");
    }
} as DisconnectBluetoothOptions)

参数 DisconnectBluetoothOptions

disconnectAllDeviceBluetooth 断开所有设备

le?.disconnectBluetooth(() => {
    console.log("断开所有设备");
})

参数

destroyBluetooth 退出使用，清理资源

le?.destroyBluetooth(() => {
    console.log("退出使用，清理资源");
})

参数

其他属性

UDevice 设备

//设备名称
name: string | null,

// 蓝牙地址
deviceId: string,

// 蓝牙设备广播数据段中的 LocalName
localName: string | null,

// 蓝牙设备的信号强度，单位dBm
RSSI: number,

// 蓝牙设备广播数据段中的 ManufacturerData 
advertisData: number[]

注意: 后续还会扩充该属性字段

LeException

// 状态码
code: number,

// 错误信息
description: string

GattCharacteristics

// 蓝牙设备特征的 UUID
uuid: string,

// 该特征是否支持 read 操作
read: boolean,

// 该特征是否支持 write 操作
write: boolean  

// 该特征是否支持 notify 操作
notify: boolean 

// 该特征是否支持 indicate 操作
indicate: boolean   

// 该特征是否支持无回复写操作
writeNoResponse: boolean    

// 该特征是否支持有回复写操作
writeDefault: boolean   

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS