更新记录

1.0.0（2026-09-30） 下载此版本

• 首次发布：BLE 透传会话 API（openAdapter / startScan / connect / write / disconnect）
• Android：Nordic BLE Library 2.3.1 + Scanner 1.4.3（扫描 UTS 直调；连接/写/通知经薄 Kotlin 封装）
• iOS：CoreBluetooth
• HarmonyOS：ConnectivityKit
• 数据：hex 字符串收发；官方 options.success / fail / complete，持续回调 onFound / onNotify / onDisconnect

平台兼容性

uni-app x(5.21)

其他

BLE 透传（Android / iOS / 鸿蒙）

面向 uni-app x（含蒸汽模式） 的三端 UTS BLE 透传插件。统一 openAdapter / startScan / connect / write / disconnect 会话式 API，报文以 hex 字符串 收发，适合智能硬件透传、自定义 BLE 协议、门锁/表计/模组等场景。

功能特性

平台兼容性

• HBuilderX：^4.27（@UTSJS.keepAlive 需要）
• uni-app x：App-Android / App-iOS / App-HarmonyOS（含蒸汽模式）

快速开始

import {
  openAdapter, closeAdapter,
  startScan, stopScan,
  connect, write, disconnect,
  isConnected, getDeviceId,
  BLE_WRITE_WITHOUT_RESPONSE
} from '@/uni_modules/bin-ble'

// 1. 打开适配器（幂等；蓝牙未开/未授权走 fail）
openAdapter({
  success: (ok) => {
    if (!ok) return
    // 2. 扫描
    startScan({
      namePrefix: 'DEV',        // 或 serviceUuids
      timeout: 10000,
      allowDuplicates: false,
      onFound: (device) => {
        // { deviceId, name, rssi, advertisData }
        console.log(device.deviceId, device.name, device.rssi)
      },
      onEnd: () => console.log('scan end'),
      fail: (err) => uni.showToast({ title: err.errMsg, icon: 'none' })
    })
  },
  fail: (err) => uni.showToast({ title: err.errMsg, icon: 'none' })
})

// 3. 连接（deviceId 直连，或 namePrefix 扫描后连接）
connect({
  deviceId: 'AA:BB:CC:DD:EE:FF', // 与 namePrefix 二选一
  // namePrefix: 'DEV',
  serviceUuid: '0000fff0-0000-1000-8000-00805f9b34fb',
  writeUuid: '0000fff1-0000-1000-8000-00805f9b34fb',
  notifyUuid: '0000fff2-0000-1000-8000-00805f9b34fb',
  writeType: BLE_WRITE_WITHOUT_RESPONSE, // 默认
  mtu: 247,                              // 可选
  scanTimeout: 10000,                    // namePrefix 扫描超时
  success: (result) => {
    // { deviceId, name, mtu, writeType }
    write('a50100ff', {
      success: () => {},
      fail: (err) => uni.showToast({ title: err.errMsg, icon: 'none' })
    })
  },
  fail: (err) => uni.showToast({ title: err.errMsg, icon: 'none' }),
  onNotify: (hex) => {
    // 持续回调：设备 notify，小写 hex
    console.log('notify', hex)
  },
  onDisconnect: () => {
    // 持续回调：被动断开（主动 disconnect 不触发）
  }
})

// 4. 主动断开并清理会话
disconnect()
closeAdapter()

业务侧包 Promise（可选）

插件遵循官方 UTS 回调约定，不返回 Promise。需要串行流程时可在业务侧包装：

function connectAsync(opts) {
  return new Promise((resolve, reject) => {
    connect({
      ...opts,
      success: (r) => resolve(r),
      fail: (e) => reject(e),
      onNotify: opts.onNotify,
      onDisconnect: opts.onDisconnect
    })
  })
}

complete 入参为 any，业务侧勿用 . 取属性。持续回调放在 connect.options 上是安全的：connect 为 void + keepAlive，不是 Promise。

API

常量

openAdapter(options): void

检查并准备蓝牙适配器。蓝牙可用时 success(true)；系统蓝牙未开时按平台尝试引导开启，失败回 fail。

closeAdapter(): void

释放适配器相关资源。不影响已建立业务语义的会话清理；离开蓝牙功能页时建议调用。

startScan(options): void

开始扫描。onFound 持续回调；超时或主动 stopScan 后触发 onEnd 与 complete。

BleDevice：

stopScan(): void

主动停止扫描。幂等。

connect(options): void

建立透传会话。同时只保留一个会话：新 connect 会替换旧会话，旧会话以 9050011 结束。

BleConnectResult：{ deviceId, name, mtu, writeType }

write(hex, options?): void

写入一包数据。同一时刻只允许一次未完成写入，冲突回 9050011。

disconnect(options?): void

主动断开并清理会话。success / complete 可选。不触发 onDisconnect。幂等。

isConnected(): boolean / getDeviceId(): string

当前会话是否已连接；当前连接设备 deviceId（未连接时为空串）。

错误码

fail 参数为 BleFail（继承 UniError），errSubject = 'bin-ble'。业务 toast 优先展示 errMsg。

errMsg 为中文用户文案；个别分支会附加简短中文说明（如「未搜索到设备」）。

集成说明

Android

• 依赖经 Gradle maven 拉取：
  • no.nordicsemi.android:ble:2.3.1
  • no.nordicsemi.android:log:2.2.0
  • no.nordicsemi.android.support.v18:scanner:1.4.3
• 真机调试请用 自定义基座 / 云打包（标准基座无三方依赖）。
• 权限：
  • API 31+：BLUETOOTH_SCAN / BLUETOOTH_CONNECT 运行时申请
  • API 23–30：ACCESS_FINE_LOCATION（扫描需要）
  • 低版本：BLUETOOTH / BLUETOOTH_ADMIN
• 未使用 Nordic DFU；固件升级请另选方案。

iOS

• 系统 CoreBluetooth，无 CocoaPods 三方依赖。
• 需在业务工程配置 NSBluetoothAlwaysUsageDescription。
• 含 PrivacyInfo.xcprivacy（仅 UserDefaults，无 Tracking）。
• deviceId 为 iOS 芯片 UUID，不可当作跨平台 MAC 使用；跨端请以扫描结果缓存或业务侧映射为准。

HarmonyOS

• 使用系统 ConnectivityKit 蓝牙能力。
• 需 ohos.permission.ACCESS_BLUETOOTH，并在应用权限声明中配置。
• 部分机型/系统版本对写特征属性较严：设备不支持所选 writeType 时会回 9050009。

行为约定

1. 插件层无 Promise：全部为 void + 官方 success / fail / complete；持续回调靠 @UTSJS.keepAlive 保活（需 HBuilderX ≥ 4.27）。
2. 单会话：全局仅一个透传连接；重复 connect 会替换旧连接（旧连接 fail(9050011)）。
3. 主动 disconnect 不触发 onDisconnect；仅被动断开（对端断电、链路丢失等）触发。
4. write 串行：前一次写入未完成时再次 write 回 9050011。
5. hex 约定：写入与 notify 均为无分隔十六进制；奇数长度或含非 hex 字符回 9050010。
6. complete 入参为 any，请勿用 . 取属性。
7. 扫描/连接中的页面退出时，调用 stopScan / disconnect / closeAdapter 清理，避免后台扫描与会话泄漏。

最佳实践

1. 先 openAdapter 再扫描/连接，在 fail 里引导用户开蓝牙或授权。
2. 优先 deviceId 直连（扫描结果缓存后连接），比 namePrefix 更快、更稳。
3. 协议层自行分包：插件每次 write 发送一包；大于 MTU 的业务报文请在调用方切分。
4. notify 流水线：onNotify 可能粘包/半包，业务侧按自定义协议组帧。
5. 离页清理：onUnload 里 stopScan + disconnect（若仍连接）+ closeAdapter。

开发文档

• UTS 语法
• UTS API 插件
• UTS 原生混编
• Android 蓝牙权限
• CoreBluetooth