更新记录

1.0.0（2026-05-22）

初始化版本发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

XF-bleUTS

XF-bleUTS 是面向 uni-app x 的 BLE 4.0 UTS 插件，并在 Android、iOS、Harmony 三端提供同名 API。插件只处理 BLE Central 侧常见流程：初始化、扫描、获取设备、连接、发现服务/特征/描述符、读写、notify 监听、缓存 simple notify 数据和清理本地缓存。

快速调用流程

1. 运行前确认静态权限已配置，并在页面中完成动态权限申请。
2. 调用 initManager，确认返回 state: 'poweredOn'。
3. 调用 scan 开始扫描，再轮询或手动调用 getPeripheral 获取设备列表。
4. 选中 peripheralUUID 后调用 connect。
5. 调用 discoverService，再调用 discoverCharacteristics，需要描述符时再调用 discoverDescriptorsForCharacteristic。
6. 根据特征属性调用 readValueForCharacteristic、writeValueForCharacteristic、setNotify 或 setSimpleNotify。
7. 不再使用时调用 stopNotify、disconnect、stopScan，必要时调用 clean 清空扫描缓存。

import { initManager, scan, getPeripheral } from '@/uni_modules/XF-bleUTS'

initManager({
  success: (res) => {
    if (res.state == 'poweredOn') {
      scan({ success: () => console.log('scan started') })
    }
  },
  fail: (err) => console.log(JSON.stringify(err))
})

getPeripheral({
  success: (res) => console.log(JSON.stringify(res.peripherals))
})

权限配置

Android

插件内置 utssdk/app-android/AndroidManifest.xml，声明：

• android.permission.BLUETOOTH
• android.permission.BLUETOOTH_ADMIN
• android.permission.BLUETOOTH_SCAN
• android.permission.BLUETOOTH_CONNECT
• android.permission.ACCESS_FINE_LOCATION
• android.permission.ACCESS_COARSE_LOCATION

Android 12 及以上运行时申请 BLUETOOTH_SCAN、BLUETOOTH_CONNECT；Android 12 以下申请定位权限。

iOS

项目需要声明蓝牙隐私说明：

• NSBluetoothAlwaysUsageDescription
• NSBluetoothPeripheralUsageDescription

如果需要后台蓝牙能力，还需要配置 bluetooth-central、bluetooth-peripheral 后台模式。

Harmony

项目需要在 harmony-configs/entry/src/main/module.json5 声明：

• ohos.permission.ACCESS_BLUETOOTH

通用类型

回调

所有异步接口沿用 uni-app x 常见的 success、fail、complete 回调字段。成功结果直接返回对象；失败结果为 XFBleFail。

export interface XFBleFail extends IUniError {
  errCode: XFBleErrorCode
  nativeCode: number
}

errCode 是插件统一错误码，nativeCode 是平台原生错误码或参考错误编号。

数据对象

XFBlePeripheral：

XFBleCharacteristic：

XFBleDescriptor：

读写特征和描述符时，value 统一传十六进制字符串，例如 0102030a。

三端接口对比

接口说明

initManager

初始化 BLE 管理器。

参数：

返回：{ state }，state 可为 poweredOn、poweredOff、resetting、unauthorized、unknown、unsupported。

scan

开始扫描 BLE 设备。扫描结果不会直接在 scan 回调中返回，需要调用 getPeripheral 获取当前缓存列表。

参数：

返回：{ status: true }。

三端差异：Android 21+ 使用 BluetoothLeScanner，旧版使用 startLeScan；iOS 使用 scanForPeripherals；Harmony 使用 startBLEScan，不传过滤条件时向系统传 null。

getPeripheral

获取当前扫描缓存中的设备。

参数：只有回调字段。

返回：{ peripherals: XFBlePeripheral[] }。

getPeripheralRssi

读取指定已连接设备的 RSSI。

参数：

返回：{ status: true, rssi: number }。

建议连接成功后调用。

isScanning

查询是否正在扫描。

返回：{ status: boolean }。

stopScan

停止扫描。无参数，无回调。

connect

连接指定设备。

参数：

返回：{ status: true }。

连接前通常需要先 scan 并通过 getPeripheral 取得设备 UUID。

disconnect

断开指定设备连接。

参数：peripheralUUID。

返回：{ status: boolean, peripheralUUID: string }。

isConnected

判断指定设备是否处于连接状态。

参数：peripheralUUID。

返回：{ status: boolean, peripheralUUID: string }。

getPeripheralState

获取指定设备连接状态。该接口是插件保留的扩展接口。

参数：peripheralUUID。

返回：{ state, peripheralUUID }，state 可为 disconnected、connecting、connected、disconnecting、unknow。

retrievePeripheral

根据 UUID 数组找回设备信息。

参数：

返回：{ peripherals: XFBlePeripheral[] }。

三端差异：iOS 调用系统 retrievePeripherals；Android 和 Harmony 主要从插件当前已知设备缓存中查找。

retrieveConnectedPeripheral

根据服务 UUID 查找当前已连接设备。

参数：

返回：{ peripherals: XFBlePeripheral[] }。

discoverService

发现指定设备的服务。

参数：

返回：{ status: true, services: string[] }。

discoverCharacteristics

发现指定服务下的所有特征。

参数：peripheralUUID、serviceUUID。

返回：{ status: true, characteristics: XFBleCharacteristic[] }。

discoverDescriptorsForCharacteristic

发现指定特征下的所有描述符。

参数：peripheralUUID、serviceUUID、characteristicUUID。

返回：{ status: true, descriptors: XFBleDescriptor[] }。

setNotify

开启指定特征 notify。收到数据时会重复触发 success/complete 回调。

参数：peripheralUUID、serviceUUID、characteristicUUID。

返回：{ status: true, characteristic: XFBleCharacteristic }。

stopNotify

停止 notify。

参数可选：

不传参数时，三端都会按各自实现清理 notify 相关记录；传入完整三元组时停止对应特征的 notify。

readValueForCharacteristic

读取指定特征值。

参数：peripheralUUID、serviceUUID、characteristicUUID。

返回：{ status: true, characteristic: XFBleCharacteristic }。

readValueForDescriptor

读取指定描述符值。

参数：peripheralUUID、serviceUUID、characteristicUUID、descriptorUUID。

返回：{ status: true, descriptor: XFBleDescriptor }。

writeValueForCharacteristic

写入指定特征值。

参数：

返回：{ status: true, characteristic: XFBleCharacteristic }。

三端差异：Android 支持 signed；iOS 的 auto 会在支持 writeWithoutResponse 时自动使用无响应写；Harmony 当前只区分 withoutResponse 和其它写法，其它值按有响应写处理。

writeValueForDescriptor

写入指定描述符值。

参数：peripheralUUID、serviceUUID、characteristicUUID、descriptorUUID、value。

返回：{ status: true, descriptor: XFBleDescriptor }。

connectPeripherals

批量连接设备。

参数：

每个设备会按平台连接结果触发回调。

setSimpleNotify

开启指定特征 notify，但通知数据不会直接通过该接口持续返回，而是缓存到插件内部。

参数：peripheralUUID、serviceUUID、characteristicUUID。

返回：{ status: true }。

getAllSimpleNotifyData

读取 setSimpleNotify 缓存的数据。

返回类型：Map<string, XFBleSimpleNotifyData>，key 为 peripheralUUID。

type XFBleSimpleNotifyData = {
  serviceUUID: string
  characterUUID: string
  data: string[]
}

clearAllSimpleNotifyData

清空 simple notify 缓存。

返回：{ status: true }。

clean

清空插件缓存的扫描设备信息。建议在未连接或业务确认不再使用缓存设备时调用；清空后依赖缓存的接口可能需要重新扫描或重新发现。

返回：{ status: true }。

调试建议

• 扫描为空：确认系统蓝牙已开启、动态权限已允许、附近设备正在 BLE 广播；Android 12 以下还要确认定位权限和系统定位开关。
• 能扫描但连接失败：先确认设备未被其它手机占用，再检查 peripheralUUID 是否来自当前平台本次扫描结果。
• 服务或特征为空：确认已连接成功，并按设备厂商文档使用正确的服务 UUID、特征 UUID。
• 写入失败：确认 value 是偶数字符数的十六进制字符串，并确认特征支持 write 或 writeWithoutResponse。
• notify 无数据：确认特征支持 notify 或 indicate，并确认设备端确实在发送通知。