更新记录

1.0.0(2026-11-21)

  • 正式发布:插件 id 为 acupday-ble
  • BLE Central,对齐微信 / uni.* 蓝牙 API
  • 支持 App-Android(Kotlin GATT)、App-iOS(CoreBluetooth)、App-HarmonyOS NEXT(ConnectivityKit)、微信小程序(转调 uni.*)
  • H5 明确不支持,统一返回 errCode=20001
  • 能力:开/关适配器、扫描与过滤、连接/断开、发现服务与特征、Notify/读/写、MTU、RSSI
  • 扩展:有限自动重连(setBLEReconnectOptions / createBLEConnection 单次覆盖)、分包写入(chunkSize / chunkInterval)
  • Android 按场景申请权限(open→CONNECT,scan→SCAN+定位);系统蓝牙关闭时可引导开启
  • iOS 插件 info.plist 含蓝牙用途说明;setBLEMTU 返回 10009(系统不支持主动协商)
  • 鸿蒙声明 ACCESS_BLUETOOTH;开适配器申请权限,关蓝牙时可 enableBluetooth()

平台兼容性

uni-app(5.0)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ - - √ √ √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
√ √ - - - - - - - - - -

uni-app x(5.0)

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

acupday-ble

uni-app x BLE Central UTS 插件:对齐微信 / uni.* 蓝牙 API,支持 App-Android / App-iOS / App-HarmonyOS NEXT / 微信小程序。含有限自动重连与分包写入。H5 不支持(统一 errCode=20001)。

本工程示例页:pages/ble/index。

当前版本(1.0.0)

平台 支持 实现要点
App Android ✅ UTS + Kotlin(BluetoothGatt)
App iOS ✅ UTS + Swift(CoreBluetooth)
App HarmonyOS NEXT ✅ UTS → ArkTS(@kit.ConnectivityKit)
微信小程序 ✅ 转调 uni.*,叠加分包写 / 重连
H5 / 其它 ❌ 20001

Android / iOS 须用含本插件的自定义基座;鸿蒙用 HBuilderX + DevEco 本地编译真机验证。

安装

  1. 将本目录放入项目 uni_modules/acupday-ble
  2. 打 自定义调试基座 / 云打包(含原生代码,标准基座不可用)
  3. 宿主 manifest 建议声明 Android 蓝牙/定位权限;iOS 覆盖 NSBluetoothAlwaysUsageDescription 等用途说明(插件 info.plist 已有中文缺省)
  4. 改 BleNative.kt / BleNative.swift / 插件 Manifest / 鸿蒙 module.json5 后须重打基座或重新同步原生工程;仅改各端 index.uts 通常不用

导入

只从插件根导入,禁止深入 utssdk/:

import {
  openBluetoothAdapter,
  closeBluetoothAdapter,
  startBluetoothDevicesDiscovery,
  stopBluetoothDevicesDiscovery,
  onBluetoothDeviceFound,
  offBluetoothDeviceFound,
  createBLEConnection,
  closeBLEConnection,
  getBLEDeviceServices,
  getBLEDeviceCharacteristics,
  notifyBLECharacteristicValueChange,
  readBLECharacteristicValue,
  writeBLECharacteristicValue,
  setBLEMTU,
  getBLEMTU,
  setBLEReconnectOptions,
} from '@/uni_modules/acupday-ble'

标准流程(与微信文档一致)

  1. 先注册 onBluetoothDeviceFound / onBLEConnectionStateChange / onBLECharacteristicValueChange
  2. openBluetoothAdapter({ success, fail })
  3. startBluetoothDevicesDiscovery(可带 services)→ 拿到 deviceId → stopBluetoothDevicesDiscovery
  4. createBLEConnection
  5. getBLEDeviceServices → getBLEDeviceCharacteristics
  6. notifyBLECharacteristicValueChange / read / write
  7. 结束:closeBLEConnection、off*、closeBluetoothAdapter
openBluetoothAdapter({
  success: () => {
    startBluetoothDevicesDiscovery({
      allowDuplicatesKey: false,
      success: () => {},
      fail: (e) => console.error(e),
    })
  },
  fail: (e) => console.error(e),
})

微信:无服务 UUID 过滤时不要传 services(禁止 null / []),否则可能 fail「no service」;有过滤再传非空数组。

扩展:有限自动重连

全局默认:

setBLEReconnectOptions({
  enable: true,
  maxAttempts: 3,
  interval: 2000,
})

单次连接覆盖:

createBLEConnection({
  deviceId,
  timeout: 10000,
  autoReconnect: true,
  maxReconnectAttempts: 3,
  reconnectInterval: 2000,
})

断线重连成功后须重新发现服务/特征并按需再开 notify。主动 closeBLEConnection 不会触发重连。

扩展:分包写入

writeBLECharacteristicValue({
  deviceId,
  serviceId,
  characteristicId,
  value, // ArrayBuffer
  writeType: 'write', // 或 writeNoResponse
  chunkSize: 20,
  chunkInterval: 20,
})

chunkSize 不传则单次写入;传入后按长度切片串行发送。

MTU

setBLEMTU({
  deviceId,
  mtu: 512,
  success: (res) => {
    // res.mtu = 协商后的实际值(可能小于请求值)
  },
  fail: (e) => console.error(e),
})

getBLEMTU({
  deviceId,
  success: (res) => console.log(res.mtu),
})
平台 行为
Android setBLEMTU 等 onMtuChanged 后再 success,回传实际 mtu
iOS 不支持主动协商,setBLEMTU 返回 10009;可用 getBLEMTU 读估算值
微信 转调 uni.setBLEMTU / uni.getBLEMTU

UTS 可能对 getBLEMTU / setBLEMTU 的 success 强转为 GetBLEMTUSuccess 等;桥接层必须回传该类型实例,禁止 UTSJSONObject(否则 ClassCastException)。

权限(分场景申请)

Android

插件 AndroidManifest.xml 已声明;运行时按场景申请:

场景 权限
打开适配器 BLUETOOTH_CONNECT(Android 12+;低版本无运行时权限)
开始扫描 BLUETOOTH_SCAN + ACCESS_FINE_LOCATION(Android 12+);低版本仅定位
连接设备 BLUETOOTH_CONNECT(Android 12+)

系统蓝牙关闭时,open 会弹系统「开启蓝牙」对话框(ACTION_REQUEST_ENABLE),用户取消则 10001。

注意: 最终 App 合并清单必须含 BLUETOOTH_CONNECT;宿主 manifest / 原生工程建议同步声明。CONNECT 勿用 tools:node="replace"。

iOS

插件 info.plist 含 NSBluetoothAlwaysUsageDescription / NSBluetoothPeripheralUsageDescription。正式产品请在宿主 manifest 的 privacyDescription 覆盖。

系统蓝牙关闭:open 用 ShowPowerAlertKey 弹系统提示;挂起直到用户开启(success)或仍未开(10001)。

鸿蒙

插件 module.json5 声明 ohos.permission.ACCESS_BLUETOOTH;open 会 requestPermissionsFromUser,关蓝牙时 enableBluetooth()。无过滤扫设备传 startBLEScan(null)(勿传空数组)。

主要错误码

errCode 含义
0 成功
10000 未初始化适配器
10001 蓝牙不可用 / 用户未开启
10002 无设备
10003 连接失败
10004 / 10005 无服务 / 无特征
10006 无连接
10007 特征属性不支持
10008 系统错误
10009 系统不支持(如 iOS setMTU)
10012 操作超时
20001 平台不支持(H5)
20002 分包写入失败
20003 重连次数耗尽

完整常量见 utssdk/unierror.uts。

改插件踩坑(摘要)

  1. Android:禁止 import … from './BleNative.kt',用包名 uts.sdk.modules.acupdayBle
  2. Android UTS:禁止 Number(x),用 as number
  3. MTU/RSSI success 必须构造 GetBLEMTUSuccess 等类型,禁止 UTSJSONObject
  4. 异步/多次回调:遵循工程 AGENTS.md(@UTSJS.keepAlive + export function)
  5. 改 Kotlin / Swift / Manifest / 鸿蒙权限资源 → 重打自定义基座或重编鸿蒙工程

示例

宿主示例:pages/ble/index(开适配器、扫描过滤、连接、发现服务/特征、Notify/读/写、MTU)。

路线图

  • 示例与市场资料完善
  • 上架「权限同步告知」(可选接入 uni-registerRequestPermissionTips)
  • 按业务需要扩展广播解析、多连接会话管理等

隐私、权限声明

1. 本插件需要申请的系统权限列表:

蓝牙;Android 扫描另需定位;鸿蒙 ACCESS_BLUETOOTH

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。