更新记录

1.0.21（2026-01-30）

• 添加了 setBluetoothEnable 接口用于编程式开关系统蓝牙（无感开关或者用户交互）
• 实现了鸿蒙next平台无需搜索直接连接设备的特性（开发参考 createBLEConnection 标注信息）
• 修复了鸿蒙next平台 startBluetoothDevicesDiscovery 接口传入 services 参数非128bit时会报错的问题
• 修复了鸿蒙next平台蓝牙关闭时 onBluetoothAdapterStateChange 接口多次回调的问题

1.0.20（2026-01-23）

• 修复了 startBluetoothDevicesDiscovery 接口的 services 参数传入非128bit的uuid字符串时报错的问题。
• Android端添加直接通过地址连接设备而无需搜索的特性支持（非跨端兼容，勿滥用）

1.0.19（2025-12-22）

• 修复Android端连接到“已连接”的设备时，会报错10002/no device的问题。
• 修复iOS端连接到“已连接”的设备时，会报错10002/no device的问题。
• 修复鸿蒙NEXT端连接到“已连接”的设备时，会报错10002/no device的问题。

平台兼容性

uni-app(4.81)

uni-app x(4.81)

开源对接例程，持续更新

GITEE开源仓库，UniappX与本蓝牙插件的对接例程

• 由于DCloud插件市场的示例项目功能无法管理版本和更新日志，因此使用gitee进行版本管理
• 工程内的 utils 文件夹包含了一些对BLE开发很有帮助的封装库
  • utils.uts 【常用BLE开发工具】 内含比如ab2hex的替代品bytes2hex，可将蓝牙数据转换为hex字符串
  • ble.uts 【跨平台调用插件】 极大简化 UniappX 工程跨端引用本插件
  • 更多用法请阅览源代码 ......

插件与接口的特点

UniAPP工程种类兼容性多，系统平台兼容性强

IOS、Android、鸿蒙NEXT，三端都支持，基于UniAPP JS引擎版本的工程甚至可以通过本插件自带的 BLE.js 无缝对齐，部署为小程序工程

接口对齐度与接口兼容性高

• 95%的WX与UniApp的BLE主机模式的接口兼容性，尽全力对齐表现，减少代码迁移的时间损耗和兼容性问题排查的时间损耗
• 支持Promise风格配合async与await进行api调用，与WX的实现思路基本一致 【参考WX的实现文档】

选型开发维护全程无忧

• 完善的文档，细致的注意事项，可帮助开发者减少开发难度，提高开发效率，快速上线APP
• 稳定维护，本插件已有对接的APP在提供服务，从立项到维护不怕插件断更导致APP功能异常甚至缺失而无法解决只能另寻他法

创新接口解决关键痛点

• 跟随最新的WX的BLE接口的实现，且创新式添加API，UniApp没有的本插件有，WX没有的本插件也有
• 全新设计批量传输接口，解决传输速率和传输包之间的间隔长的痛点
  • 完美解决传输OTA大包时外设固件UART超时中断过短(1.5s以下)，而WX与UNIAPP的官方API分包发送间隔过长导致大概率失败的问题
  • 有效提高传输速率，减少js层分包发送带来性能损耗

接口的已知问题

本插件某些接口只支持注册一个回调而Uniapp和WX支持注册多个

• 原因：某些接口提供的注册方法虽然可以注册多个，但是解注册方法只能是全部进行解注册，解注册和注册的过程极其容易留下暗坑，比如内存泄露，回调混乱，生命周期不符合需求
• 解决方案：开发者自行维护这些API的注册以及解注册，在需要的时候注册，在不需要的时候解注册。真正传给本插件库的只有一个注册的回调函数，通过此回调函数进行分发处理
• 可参考 不同的BLE第三方库导致的回调混乱
• 可参考 本插件的例程实现的回调维护机制
• 受影响的API：onBluetoothDeviceFound、onBluetoothAdapterStateChange、onBLECharacteristicValueChange。注意，一般仅在多设备下链接下有影响。

云打包报错

• 原因：HBuilderX 版本过低或者过高
• 解决方案：请使用合适的 HBuilderX 版本
• 目前本插件的开发和调试是 [HBuilderX 4.15正式版本] 和 [HBuilderX 4.17 Alpha版本] 和 [HBuilderX 4.23 正式版本] 和 [HBuilderX 4.66 正式版本]

闪退问题一览

• UniappJS引擎，使用此插件时，参数不正确传入导致闪退

  • 原因：UniappJS会自动序列化js变量到原生层，如果类型不匹配就会抛出异常导致闪退
  • 解决方案：接口文档声明必须要传的参数，绝不可漏，否则有闪退的可能性，并且确保类型与文档的描述一致
  • tips：理论上UniappX引擎的工程编译时会检查类型完整性，但是为了避免闪退，请确保参数正确传入

• IOS端扫描到的设备信息暂时无法提供 serviceData 字段

  • 原因：闪退issues 1
  • 解决方案：HBuilderX升级到4.23及以上可解决此问题，目前插件已加入此修复逻辑，在 HBuilderX版本 >= 4.23 时自动开放此字段

• IOS端首次编译运行或者点击重新运行进行调试，使用蓝牙后一段时间内崩溃

  • 原因：闪退issues 2
  • 临时方案：编译运行后，手动杀死app，从桌面图标重新进入可正常运行不闪退
  • tips：此问题仅在本插件开发时被插件开发者频繁遇到，已确认不影响使用本插件的APP

• IOS端UniAppJS引擎的APP调用接口许久以后内存爆炸导致闪退

  • 原因：闪退issues 3
  • 临时方案：使用 BLE.js 封装库在js引擎的app下调用接口，切勿直接调用UTS接口
    • 临时解决方案仅能解决带 options 入参的接口的内存泄漏，各种 onXXX 回调注册接口执行多了还是会泄漏
  • onXXX 接口调用超过几千上万次才‘可能’导致发生崩溃，如果你的逻辑里面没有非常频繁的以ms级别调用此类接口则无需担心，在用户使用APP的周期内都是比较稳定的
  • tips：仅有js引擎且是在IOS下的工程受到影响，包括 UniAppx IOS js逻辑层、UniApp JS IOS

异步接口并行高频次调用可能存在一些兼容性问题

• setBLEMTU 接口需要等待原生层回调通知结果，期间如果开发者并行调用多次此接口，则可能存在只回调一次 success 而后 onBLEMTUChange 多次回调的可能性。

• 在鸿蒙next上，设置MTU，设置使能通知，读特征，写特征，这几个接口，需要在执行完成后才能执行下一次，否则会报错 errMsg: "readBLECharacteristicValue:fail BussinessError 2900099: Operation failed"

是否考虑优化：考虑，但不优先考虑，请开发者规范调用异步接口，在success与fail与complete中进行下一步操作

当前插件不支持的但待实现的功能

1. SPP之类的经典蓝牙相关的操作接口，包括搜索，连接，创建通信通道
2. Peripheral模式，也就是手机作为一个外设（BLE从机）广播的模式
3. BEACON模式，用于短距离定位，常用于外设之间相互通报位置，属于定位权限

tips: 待实现优先级按照列表排名

某些接口注册回调会重复的问题

• IOS由于swift的闭包函数无法被比较的特性，在直接调用插件实现的UTS层实现的原生接口函数无法识别是否是已经注册过的函数，某些可以注册多个监听回调的接口多次调用会导致重复注册

• Android端由于UTS插件的编译器的BUG，导致UniAPP JS引擎的js回调每次传递到UTS层都会创建一个新的lambda去实现UTS层定义的callback

• 关注重复注册的问题：重复注册 issues

• 受影响的API：

  • onBLEConnectionStateChange
  • onBLEMTUChange

同样，因为无法识别唯一性，上述的接口也无法调用其对应的 offXXX 接口，传入同一个回调函数的变量，去移除指定的回调函数的注册，而只能传入为空的变量，去移除所有的注册记录

插件开发者已经通过一些窍门去解决重复注册的问题，查看下方的兼容性框图，了解你的工程上是否会遇到此问题 🔥

因为iOS端的uniapp x swift逻辑层暂未上线，因此你可以忽略此工程的问题，只需要关注以下事项：

• 如果你是 UniApp JS 引擎的工程，按照下方教程安装插件后导入 BLE.js 直接使用，没有此问题
• 如果你是 UniApp X 引擎的工程
  • 在Android端使用 import * as UTSBLE from '@/uni_modules/xl-uts-bluetooth'; 导入后，直接按照教程调用接口
  • 在IOS端使用 import * as UTSBLE from '@/uni_modules/xl-uts-bluetooth/jssdk/BLE.js'; 导入后，直接按照教程调用接口
  • 在鸿蒙NEXT端使用 import * as UTSBLE from '@/uni_modules/xl-uts-bluetooth'; 导入后，直接按照教程调用接口
  • 注意：如果需要兼容多端，应当使用条件编译，详细用法请参考插件的示例工程

接口的兼容性处理

1. 蓝牙需要获取相关的权限（不获取就没法搜索或者连接到设备）：

   • Android:

     • 在android6.0及以上，android12以下（不包括12），需要在运行时申请 (定位权限)
       • android.permission.ACCESS_FINE_LOCATION
       • android.permission.ACCESS_COARSE_LOCATION
       • android.permission.ACCESS_BACKGROUND_LOCATION

         权限用途：用于搜索BLE设备，不授权则无法搜索到任何蓝牙设备

     • 在android12及以上会出现的权限，需要在运行时申请 （附近的设备权限）
       • android.permission.BLUETOOTH_SCAN
       • android.permission.BLUETOOTH_ADVERTISE
       • android.permission.BLUETOOTH_CONNECT

         权限用途：用于搜索，连接，管理蓝牙设备，不授权则无法操作任何蓝牙设备

   • 鸿蒙NEXT：

     • 需要用到 ohos.permission.ACCESS_BLUETOOTH 权限

       权限用途：用于搜索和连接蓝牙设备，禁止后会导致无法搜索和连接蓝牙。

     • 可能需要用到 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 权限

       • 此权限用于无搜索直接连接设备，注意，此权限是系统受限权限，需要开发者自行申请。
       • 系统受限权限申请 华为文档
       • 蓝牙MAC地址持久化受限文档说明 华为文档
       • DCLOUD权限配置文档 开发和权限配置

   • iOS:

     • 需要用到 NSBluetoothAlwaysUsageDescription 权限
     • 需要用到 NSBluetoothPeripheralUsageDescription 权限

       权限用途：您的应用需要始终访问蓝牙设备，以便与其他蓝牙设备进行持续的通信和数据传输。

   为了尽可能正常使用本插件，以及减少代码复杂性，尽可能贴近wx和uniapp的官方api的用法。本插件在使用 openBluetoothAdapter 接口时会自动申请需要的权限， 这可能会导致app上架失败（有些市场要求上架的app在申请权限之前要app自定义一个弹窗声明权限用途，请求用户赋予） 如果您的APP不考虑上架市场，则可以直接使用所有的API进行开发，但是如果您需要上架国内的应用市场，请务必按照市场的要求检查系统版本号并且弹窗声明权限信息 在弹窗声明和申请相关的权限时，可参考上述的“权限用途”描述

2. 禁止用 errMsg 判断接口的执行结果

   在进行插件开发时，开发者搜索了大量的用例，发现网络上的开发者们的用法真是千奇百怪，有些用户甚至使用errMsg判断是否调用接口成功， 比如下方链接指向的用法：第82行代码，理论上来讲这是不规范的， 正确用法应当是判断errCode，如果你是从老的wx小程序代码中迁移BLE调用逻辑到本插件，请务必检查代码中是否包此类使用errMsg进行判断的逻辑，有的话请更改为使用errCode，

   • 注：在实际的迭代过程中，wx或者uniapp或者本插件的errMsg的格式都有可能会变，且本插件无法百分百知晓在出现错误时，各大厂商对于errMsg的格式的实现。

3. batchWriteBLECharacteristicValue 接口在传输的过程中，严禁再次并行调用 writeBLECharacteristicValue 和 batchWriteBLECharacteristicValue

   此接口一旦开启传输，会占用指定的服务下的指定特征用于自动在原生层分包发送数据块，一般此接口用于发送完整的固件、或者较大的数据封包， 这些数据在传输的过程中，往往都需要保证连续性和完整性，因此也不应该在发送的过程中穿插其他的数据，而是在接口的success执行后，再去调用任何的写接口

   注：如果看到以下的错误代码以及错误信息，则说明你的代码逻辑没处理好串行写的逻辑，此时你应当检查是否错误的并行调用写接口，或者是在不同的事件（比如setTimer、setInterval）中误调接口，或是async调用时没有await

     {
         "errSubject": "xl-uts-bluetooth",
         "errCode": 10008,
         "errMsg": "writeBLECharacteristicValue:fail characteristic handler is busy"
     }

4. writeBLECharacteristicValue 接口并行调用且传入 writeType 还不相同的情况下，会导致顺序错乱 这是已知问题，且短时间内无法修复，可能也不会考虑修复。在正常的蓝牙开发过程中，蓝牙的写操作是一个异步的操作，且是一个可能会由于各种原因失败的异步操作， 在你设计程序之初，就应当考虑将异步操作进行串行化，同步化（async + await），根据上次的write的执行结果决定本次需要重试还是继续发送还是结束发送和通知客户。而不是对一个设计之初就是异步的api进行并行调用，并行调用的情况下，由于writeType在各个平台 的实现略有不同，因此各个平台展现出来的特性也是也是不一样的，所以失败+数据错乱的概率会大大增加。

   • 注：在对一个指定的服务特征并行执行了多次写操作之后，在还未全部结束的情况下尝试执行 batchWriteBLECharacteristicValue 接口会直接报错busy，请勿混用写接口。

5. 所有的操作传入的参数，没有特殊说明的情况下按照以下规范进行：

   • 字符串类型请传入大写字符串，比如deviceId, serviceId, characteristicId

6. MTU相关的接口在双端的差异性

   • 下方论据以蓝牙模块 XY-MBA32A 为例子

   • Android: 经测试，在不同的机型，Android版本，系统版本，三个大区别上，BLE的表现特征是不一致的，碎片化比较严重

     • 设备：红米Note8Pro，系统版本为miui12.5.6.0稳定版，Android版本为11

       • 特性：createBLEConnection 创建BLE链接后，不会触发 onBLEMTUChange ， 且如果 setBLEMTU 不为517，会返回错误 setBLEMTU:fail android ble status 4

     • 设备：红米k60pro上，系统版本为hyperos1.0.8.0.UMKCNXM，Android版本为14

       • 特性：createBLEConnection 创建BLE链接后会紧接着触发 onBLEMTUChange 通知MTU更改（外设的固件请求更改的），因此 getBLEMTU 获取的MTU就是更改后的MTU

     • 设备：三星S23ULTRA上，系统版本为OneUI6.1，Android版本为14

       • 特性：createBLEConnection 创建BLE链接后并没有任何的MTU更改的回调，因此 getBLEMTU 只能获取到默认的23大小
       • 如果希望 getBLEMTU 可以获取到更大的MTU，则需要在外设支持的情况下调用 setBLEMTU 进行MTU的设置，经测试，对 XY-MBA32A 模块调用 setBLEMTU(任意值) 会触发 onBLEMTUChange 更改为517

     • getBLEMTU 接口获取到的MTU需要减去3，看这个文档了解详情：MTU在Android端的注意事项

     • 结论：

       • 连接设备前：先注册 onBLEMTUChange， 因为可能连接成功后直接就协商好MTU了，如果你没提前监听的话，可能会导致措施MTU更改的消息通知
       • 连接设备后：尝试一次 setBLEMTU，无论能不能设置为指定的MTU值，至少在外设支持更改的情况下，Android底层是会尝试设置到双方都支持的最大值的， 设置成功后就能触发 onBLEMTUChange
   • IOS: 系统底层有协商MTU的逻辑的，只是开发者没办法接触到，也就是说，如果开发者需要更改MTU，需要由外设端发起更改，也就是说可以把锅丢给硬件固件部门的同事了
     • getBLEMTU 的底层是调用了 maximumWriteValueLength ，在IOS的官方API中，是把 write 和 writeNoResponse 两种传输类型区分对待的，两者能传输的长度是不一样的，注意，此长度不需要减去3，也就是此长度已经减去包含 Op-Code 和 Attribute Handle 的长度
     • setBLEMTU 由于系统原因，原生不支持此API，自然也就不支持 onBLEMTUChange
   • 特别注意：插件开发者在使用 XY-MBA32A 透传模块和 JDY-31-LE 透传模块进行测试时，发现这两款产品都有MTU相关的逻辑问题
     • 在 XY-MBA32A 模块上，发现尽管MTU可以设置为更大的值(517)，但是调用API时如果发送比较大的数组，会回调成功，但是模块的TX没有数据出现，经测试只能发送255以内的包大小
     • 在 JDY-31-LE 模块上，对其串口RX写大于等于MTU大小的数据包时，BLE总是回调20个字节一次的包大小，也就是说其串口端并没有根据新的MTU进行分包发送
     • MTU在一些非规范实现的BLE透传模块上，有很大的问题，并不可信，因此切记先测试模块的MTU是否支持设置，以及设置完成后，传输 MTU - 3 大小的字节的包是否能正常收到

7. 在进行读写特征值的操作之前至少调用一次 getBLEDeviceServices 接口

   • 否则有可能导致某些系统平台上，在调用读写特征值、获取特征列表的接口时，一直报错 10004 no service 没有找到指定服务
   • 推荐在设备连接成功后，调用一次此接口确保服务探索完毕
   • 如果存在其他接口调用操作，请确保 设置MTU 和 获取服务 和 设置通知使能 这几个接口不是并行调用，而是按照顺序依次调用的。

8. MAC地址兼容性须知

   • 在鸿蒙NEXT上，MAC地址是虚拟的，虽然搜索到的设备列表里面的地址看起来不像是IOS那种UUID形式的，但是其实这个也不是真正的MAC地址，而是被系统重映射隐藏之后的了。

     • 老版本备注：手机的蓝牙重新开关，或者APP重启之后，这个虚拟地址会变化，因此如果涉及到重新开关蓝牙的逻辑，请记得重新搜索设备。
     • 新版本备注：本插件新版本会调用 access.addPersistentDeviceId 原生接口持久化映射地址，此举是实现不搜索直接连接的重要基础，但是还是需要搜索和连接一次以此固定设备地址！

   • 在Android上，MAC地址就是设备实际的MAC地址，不会变化，可以实现内置指定MAC地址进行连接
   • 在iOS上，MAC地址被重映射为随机的UUID，并且根据某些系统规律进行变化，不是固定的

     温馨提示：设备的MAC地址最好是现场搜索现场使用，千万不要缓存到本地，因为下一次就不一定是这个了！

9. 当服务或者特征的UUID重复出现时，如何在操作时区分同一UUID的不同实例

   • 如果可以，设备固件开发时，尽量不要做成一样的UUID，不然很多小程序平台没办法兼容这种设计，最终为难的还是设备厂家自己
   • 本着插件少更新，小更新，尽量减少大批量更新带来的不稳定的可能性的原则，暂不考虑支持相同UUID的服务
   • 对于特征的UUID重复，开发者可在连接设备后，通过 getBLEDeviceCharacteristics 接口返回的 handle 字段值去标记不同的实例，然后在调用操作接口的时候，设置到 characteristicHandle 字段中，就可以区分不同实例了
   • 参考WX的解决方案的实现（此实现未公开）: 跳转阅览
   • 参考github的解决方案：跳转阅览

     注意：目前只支持Android平台，且不要缓存 handle 值，因为此值会在不确定的条件下有所变化！尽量只在一次连接中去使用。

未实现的接口列表

2. makeBluetoothPair

   功能描述：蓝牙配对接口，仅安卓支持。

   文档链接：微信文档

3. isBluetoothDevicePaired

   功能描述：查询蓝牙设备是否配对，仅安卓支持。

   文档链接：微信文档

4. getBLEDeviceRSSI

   功能描述：获取蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)。

   文档链接：微信文档

tips：有些接口用上的频率比较低，或者是实现的复杂度比较高，本插件的开发者会优先实现其他的接口，上述的接口后期会慢慢更新支持

接口的使用前提

1. 安装此插件到你的工程中（如果你是在DCLOUD插件市场中，请点击右侧按钮 ‘试用’）

2. 导入插件

   • (1) 导入js二次封装库（UniAppJS引擎项目推荐此方法）

     import * as UTSBLE from '@/uni_modules/xl-uts-bluetooth/jssdk/BLE.js';

     • 适用于UniappJS引擎的 IOS & Android & 鸿蒙NEXT 项目
     • 适用于UniappX引擎JS逻辑层的IOS项目
     • 支持代码提示，且参数自动修正为UTS要求类型，避免闪退
     • 支持Promise语法调用，异步api的success，fail，complete三个回调都不传则返回一个Promise对象

   • (2) 导入UTS插件原生支持库（不推荐，原因看下方事项）

     import * as UTSBLE from '@/uni_modules/xl-uts-bluetooth';

     • 适用于Android端的 UniappX引擎 的项目
     • 适用于鸿蒙NEXT端的 UniappX引擎 和 Uniapp引擎 的项目
     • 不支持Promise语法调用

   • (3) 导入uts二次封装库（UniAppX引擎项目推荐此方法）

     import * as UTSBLE from '@/utils/ble.uts';

     • 适用于IOS、Android、鸿蒙NEXT、三端的 UniappX引擎 的项目
     • 不支持UniappX swift逻辑层的IOS项目（官方未上线swift逻辑层，但是我先备注说明）
     • 支持Promise语法调用，异步api的success，fail，complete三个回调都不传则返回一个Promise对象

     注：ble.uts源码可在 开源示例项目 找到。 在下载 ble.uts 完成后，将其放入到你的工程中（注意，不要放入到任何的uni_modules文件夹内），如果工程根目录已有utils文件夹，则可以直接放入进去然后参考上述文章的导入语法 如果 ble.uts 的存放目录有任何的变动，导入时也请修正为正确的路径！

   • 导入插件的额外注意事项和参考备注：

     • iOS端的 UniAppX引擎JS逻辑层 的项目，第1和2和3种方式都支持。但是建议用第1（无跨端需求）或者第3种（有跨端需求），可以解决很多的已知问题
     • UniAppJS引擎的 Android & IOS工程 & 鸿蒙NEXT 支持第1、2两种形式导入。只是第2种导入没有代码提醒和Promise化的支持，且可能导致重复注册回调，且类型或者值错误有可能会导致闪退，不建议使用。建议使用 BLE.js 也就是第1种
     • UniAppX引擎的 Android工程 只支持第2、3种调用方式。最终都是编译为kotlin原生代码，没有JS运行环境，如果没有跨端需求可以用第2种调用方式
     • UniAppX引擎的 鸿蒙NEXT工程，编译之后是ARKTS，只支持第2、3种调用方式。最终都是编译为ARKTS原生代码，没有JS运行环境
     • UniAppX引擎的项目，如果需要兼容 Android & IOS & 鸿蒙NEXT 可使用第3种调用方式导入 ble.uts 进行调用，其内部已自动条件编译

3. 按照下方接口文档，调用接口

已实现的接口列表

如果遇到特性没有完全对齐的情况，可以酌情向插件开发者反馈，插件开发者会在接口下方标注，然后尽量抹除差异进行对齐

调用时请根据您的import方式进行调用，如果您的import是别名as方式，请使用别名进行调用，比如 UTSBLE.openBluetoothAdapter(参数)

标准接口

以下无序接口列表不带文档，是对齐到Uni的官方API或者WX的官方API的标准接口，因此不再重复书写文档，请参照指定链接的文档进行开发

• stopBluetoothDevicesDiscovery
• startBluetoothDevicesDiscovery
• openBluetoothAdapter
• onBluetoothDeviceFound
  • 只能注册一个，多设备链接可能受影响，解决方案参考顶上的已知问题
• onBluetoothAdapterStateChange
  • 只能注册一个，多设备链接可能受影响，解决方案参考顶上的已知问题
• offBluetoothDeviceFound
• offBluetoothAdapterStateChange
• getBluetoothDevices
• getConnectedBluetoothDevices
  • 在IOS上一定需要指定主服务的UUID，才能检索到已连接的BLE设备
  • 在ANDROID上一定要将主服务的UUID列表设置为空列表，才能检索到已连接的BLE设备
  • 在鸿蒙NEXT上同ANDROID一致，描述同上。（注：功能已实现，但是HBX的云打包机的SDK版本太旧，会编译失败，因此鸿蒙NEXT暂时不开放此接口）
  • 局限性：无法获得搜索才能获得的信息，比如广播数据，RSSI之类的，且一般来说是用于GATT特性的设备的，并且本插件开发者对其他协议比如音频相关的了解甚少，不建议使用此接口查询诸如此类的设备。
• getBluetoothAdapterState
  • 在蓝牙未授权或是未开启的状态下，本接口走success回调上报available为false
• closeBluetoothAdapter
  • 关闭适配器会导致所有的设备都断开连接，所有设置的回调都被清除，非app退出请勿关闭适配器
• writeBLECharacteristicValue
  • Android端一次性写入过多的数据，某些高级别的系统版本上可能会返回 fail writeCharacteristic return false，请根据MTU进行分包发送
  • 在IOS和鸿蒙NEXT上，一次性传入过多的数据进行写入，可能会出现回调成功但是实际上数据并未达到/完全达到设备端的问题，请根据MTU进行分包发送
• setBLEMTU
• readBLECharacteristicValue
• onBLEMTUChange
• onBLEConnectionStateChange
• onBLECharacteristicValueChange
  • 只能注册一个，多设备链接可能受影响，解决方案参考顶上的已知问题
  • iOS端返回的是无符号(0到255)的number[]，Android端返回的是有符号(-128到127)的number[]，可通过 toUnsignedBytes() 函数转换为无符号
• offBLEMTUChange
• offBLEConnectionStateChange
• offBLECharacteristicValueChange
• notifyBLECharacteristicValueChange
  • type的默认值为 ‘indication’。iOS上不受type影响，会同时打开 ‘indication’ 和 ‘notification’
• getBLEMTU
• getBLEDeviceServices
  • ⚠️ IOS端在设备连接后，会自动发起服务探索，ANDROID和鸿蒙NEXT有兼容性问题所以没有加入这个逻辑，因此需要你调用此接口确认探索到你需要操作的服务之后，再操作读写特征。
  • 连接成功后立刻调用可能会报错 10004，请自行实现在指定的时间内反复重试的逻辑
• getBLEDeviceCharacteristics
  • 连接成功后立刻调用可能会报错 10005，请自行实现在指定的时间内反复重试的逻辑
• createBLEConnection
  • 就算对同一个deviceId的设备并行调用此接口也只会创建一个BLE链接，且开发者并行调用了几次就会回调几次
  • 不搜索直接创建链接的特性：
    • iOS平台的deviceId是变动的，因此不支持此特性
    • Android端deviceId就是固定的mac地址，可直接使用此特性（微信小程序也支持此特性）
    • 鸿蒙NEXT需搜索一次设备，得到需要连接的设备地址，调用此接口后该地址从此固定，除非卸载APP，此后支持直接连接（需要申请额外权限，请参考权限章节）

      非跨端特性，勿滥用，否则会给跨端需求带来烦恼。

• closeBLEConnection

非标接口

以下无序接口列表，是非标准接口，参考文档请点击对应接口链接跳转阅览，再次提醒您，使用以下接口可能会导致跨端/跨平台移植难度增加，请和产品经理开会讨论之后再决定是否使用

• setBluetoothEnable
• batchWriteBLECharacteristicValue
  • 可用 writeBLECharacteristicValue 接口模拟（速度无提升）