更新记录

0.1.0（2026-06-02）下载此版本

新增独立低功耗蓝牙 UTS 插件 i-ble。
新增统一 API：适配器打开/关闭、扫描、停止扫描、连接、断开、服务发现、通知订阅、读取、写入、RSSI、MTU、设备状态和事件监听。
新增扫描结果过滤、自动识别可写/可通知/可读特征值、多设备连接状态缓存和分包写入队列。
新增 Android、iOS、鸿蒙、微信小程序平台目录和基础权限配置。
新增中文插件说明、API、状态码、平台差异和使用流程文档。

平台兼容性

uni-app x(5.11)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
-	-	√	√	√	√

I BLE 低功耗蓝牙

I BLE 是一个面向 UniAppX 的低功耗蓝牙 UTS 插件，用于统一 BLE 设备扫描、连接、服务发现、通知订阅、数据读取、数据写入、RSSI、MTU、分包发送和多设备连接管理。

插件信息

插件名称：i-ble
插件类型：UTS 插件 / 通用 SDK
当前版本：0.1.0
主要平台：Android、iOS、鸿蒙、微信小程序
微信小程序端：第一版只完整适配 mp-weixin

安装

将 i-ble 目录放入项目的 src/uni_modules/i-ble。在页面或业务模块中直接导入：

import {
  openAdapter,
  startScan,
  connect,
  discoverServices,
  subscribe,
  write,
  onDeviceFound,
  onValueChange,
  onWriteComplete
} from '@/uni_modules/i-ble'

权限配置

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 12 及以上需要关注蓝牙扫描/连接运行时权限；低版本 Android 扫描 BLE 设备通常需要定位权限。

iOS

插件内置 utssdk/app-ios/Info.plist，包含：

NSBluetoothAlwaysUsageDescription
NSBluetoothPeripheralUsageDescription

iOS 不支持主动设置 MTU，实际写入包长由系统协商能力决定。

鸿蒙

插件已提供 utssdk/app-harmony 平台目录。鸿蒙真机运行时仍需按项目实际权限模型配置蓝牙相关权限。

微信小程序

第一版只承诺微信小程序，使用前需确保小程序基础库支持 BLE，并在用户授权后调用。

使用流程

调用 openAdapter 初始化蓝牙适配器。
注册 onAdapterStateChange 监听系统蓝牙开关状态。
注册 onDeviceFound 监听扫描结果。
调用 startScan 扫描设备，可通过服务 UUID、名称、设备 ID、RSSI 过滤。
找到设备后调用 stopScan 停止扫描。
调用 connect 连接设备，可设置超时和自动重连。
调用 discoverServices 发现服务与特征值，插件会自动识别可写、可通知、可读 UUID。
调用 subscribe 订阅通知，并通过 onValueChange 接收设备回传数据。
调用 write 写入十六进制字符串、数字数组或 ArrayBuffer。
通过 onWriteComplete 监听分包写入完成结果。
可按需调用 read、readRSSI、setMTU。
页面卸载或业务结束时调用 disconnect、closeAdapter，并移除事件监听。

API

openAdapter(options?)

初始化蓝牙适配器。其他 BLE API 必须在初始化后调用。

openAdapter({
  success: (res) => {},
  fail: (err) => {}
})

closeAdapter(options?)

关闭蓝牙适配器，并重置扫描状态。

startScan(options?)

开始扫描 BLE 设备。

参数	类型	默认值	说明
services	Array\<string>	[]	按广播服务 UUID 过滤。
allowDuplicates	Boolean	false	是否允许同一设备重复上报。
interval	Number	0	设备上报间隔，单位 ms。
nameContains	String	''	设备名称包含过滤。
namePrefix	String	''	设备名称前缀过滤。
deviceId	String	''	指定设备 ID。
minRSSI	Number	-	最低信号强度过滤。

stopScan(options?)

停止扫描。建议找到目标设备后立即停止，以降低功耗。

connect(options)

连接设备。

参数	类型	默认值	说明
deviceId	String	-	必填，设备 ID。
timeout	Number	10000	连接超时时间，单位 ms。
autoReconnect	Boolean	false	断开后是否自动重连。
maxRetries	Number	3	自动重连最大次数。
retryInterval	Number	1500	自动重连间隔，单位 ms。
discoverAfterConnect	Boolean	true	连接成功后是否自动发现服务。

disconnect(options)

断开指定设备，传入 deviceId。

getConnectedDevices(options?)

获取当前插件内维护的已连接设备状态。

discoverServices(options)

发现设备服务和特征值，并自动识别：

可写特征值：write / writeNoResponse
可通知特征值：notify / indicate
可读特征值：read

subscribe(options)

订阅通知。若未传 serviceId 和 characteristicId，优先使用自动识别的可通知特征值。

unsubscribe(options)

取消通知订阅。

read(options)

主动读取特征值。若未传 UUID，优先使用自动识别的可读特征值。

write(options)

写入数据。支持：

十六进制字符串：'A0 01 FF'
数字数组：[0xA0, 0x01, 0xFF]
ArrayBuffer

参数	类型	默认值	说明
deviceId	String	-	必填，设备 ID。
serviceId	String	自动识别	服务 UUID。
characteristicId	String	自动识别	特征值 UUID。
value	String / Array / ArrayBuffer	-	必填，写入数据。
writeType	String	auto	`auto`、`write`、`writeNoResponse`。
chunkSize	Number	0	分包大小，0 表示自动使用 `mtu - 3`，未获取 MTU 时为 20。
chunkInterval	Number	20	分包发送间隔，单位 ms。

readRSSI(options)

读取设备 RSSI。

setMTU(options)

设置 MTU。Android 通常支持；iOS 不支持主动设置，失败时返回 20009。

getDeviceState(options)

同步返回插件内维护的设备状态。

事件

方法	说明
onAdapterStateChange / offAdapterStateChange	监听系统蓝牙开关和扫描状态。
onDeviceFound / offDeviceFound	监听扫描到的设备。
onConnectionStateChange / offConnectionStateChange	监听连接状态变化。
onValueChange / offValueChange	监听通知或读取回传数据。
onWriteComplete / offWriteComplete	监听写入完成。
onError / offError	监听插件错误。

onValueChange 的数据同时包含：

buffer：ArrayBuffer
hex：十六进制字符串
bytes：数字数组

状态码

状态码	说明
0	正常。
10000	未初始化蓝牙适配器。
10001	当前蓝牙适配器不可用。
10002	没有找到指定设备。
10003	连接失败。
10004	没有找到指定服务。
10005	没有找到指定特征值。
10006	当前连接已断开。
10007	当前特征值不支持此操作。
10008	系统错误。
10009	系统不支持 BLE。
10010	已连接。
10011	配对设备需要配对码。
10012	操作超时。
10013	参数无效。
20001	平台暂不支持。
20002	权限不足。
20003	扫描过滤无结果。
20004	自动识别特征值失败。
20005	写入队列繁忙。
20006	写入数据为空。
20007	十六进制格式错误。
20008	自动重连失败。
20009	当前平台不支持主动设置 MTU。

平台差异

Android：支持扫描、连接、通知、读写、RSSI、MTU；分包大小建议不超过 mtu - 3。
iOS：支持扫描、连接、通知、读写、RSSI；不支持主动设置 MTU。
鸿蒙：提供平台入口和统一 API，实际真机能力以鸿蒙系统蓝牙权限与运行环境为准。
微信小程序：使用微信小程序 BLE API，写入需注意包长和基础库能力。

注意事项

BLE 扫描耗电较高，连接到目标设备后应及时停止扫描。
并行写入容易失败，插件按设备维护串行写入队列。
未发现服务和特征值前，无法自动识别 UUID。
自动识别只选择第一个符合条件的特征值；复杂设备建议业务侧显式传入 UUID。
iOS 对过长单包写入可能不回调，建议始终开启分包发送。
使用过程中如果有疑问，可评论留言。