更新记录

0.2.4（2026-08-20）

• Android 扫描启动增加异常保护，权限或系统状态异常时改为返回错误，避免原生崩溃。
• Android 连接前校验 deviceId，非法 MAC 地址返回明确错误。
• 新增 bleOffDeviceFound、bleOffConnectionStateChange、bleOffValueChange，支持按需取消全局回调。
• 新增 bleRelease，一次性停止扫描、断开连接、清理等待操作并移除监听。
• Demo 页面退出时改用统一释放 API，避免反复进入页面后旧回调残留。

平台兼容性

uni-app x(4.45)

其他

BLE Kit

ble-kit 是面向 uni-app x 的 Android/iOS BLE Central（主机端）通信插件，使用 UTS 直接调用 Android BLE API 与 iOS CoreBluetooth。

项目本身就是一个可真机运行的 .uvue Demo；插件目录位于 uni_modules/ble-kit。

对标插件结论

主要参考插件为 DCloud 插件市场的 android-ble（页面 ID：20243）。截至 2026-08-19，页面信息为：

• 普通授权：66 元；源码授权：888 元。
• 支持 uni-app / uni-app x 的 Android、iOS、HarmonyOS 和微信小程序，Web 不支持。
• 主要能力包括过滤扫描、多设备连接、连接超时与重连、UUID 自动识别、读写、Notify/Indicate、RSSI、MTU、PHY 2M 和分包发送。

ble-kit 0.2.4 当前重点：

• 使用当前 uni-app x / UTS / uvue 技术形态。
• 支持名称关键词、名称前缀、Service UUID、空名称和重复数据扫描控制，并支持超时自动停止。
• 连接支持超时；可查询当前连接状态与设备 ID。
• 实时监听系统蓝牙开关、受限和不支持状态；蓝牙关闭时自动停止扫描并清理连接。
• 支持从 Demo/API 跳转系统蓝牙设置或应用权限设置页。
• Android 不包含额外 .so，无 ABI 架构绑定问题；iOS 不引入第三方 Pod。
• 连接后可枚举真实服务和特征，并返回特征属性，避免盲目读写。
• 可自动推荐 Service / Read / Write / Notify UUID 组合。
• 在读、写、Notify 前校验特征能力，错误会明确提示“不支持 read/write/notify”。
• 写入支持 ArrayBuffer、HEX 字符串、数字数组、自动分包和进度回调。
• Android 写入等待原生完成回调；Notify 等待 CCCD 写入结果。
• Android 与 iOS 均使用平台返回的 deviceId；不把 Android MAC 当作跨平台业务主键。
• Android 主动协商 MTU；iOS 返回 CoreBluetooth 实际最大写入载荷。

适配设备

适用于实现标准 Bluetooth Low Energy GATT 的设备，例如：

• BLE 串口透传模块：HM-10/CC254x、JDY 系列、Nordic UART Service、ESP32 BLE UART 等。
• 智能硬件：美容仪、穿戴设备、传感器、温湿度计、血压计、电子秤、门锁、灯控、运动器材等。
• 自研硬件：只要设备作为 BLE Peripheral 广播，并提供可读、可写或可通知的 GATT Characteristic。

不适用于：

• 经典蓝牙 SPP/A2DP/HFP 设备。
• 只提供厂商私有 SDK、未开放 GATT 协议的设备。
• BLE Peripheral/广播端开发（本插件当前只实现 Central 主机端）。
• Web、HarmonyOS、小程序。

说明：插件负责 BLE 连接与字节传输，不内置具体厂商的业务协议。接入某款设备前，需要取得其 Service UUID、Characteristic UUID、读写属性和指令格式。

兼容性

建议首轮真机覆盖：Android 8、10、12、13、14、15；iOS 15、16、17、18、19。未经真机验证的版本不应在市场页标注为“已测试”。

API

import {
  bleIsSupported,
  bleIsEnabled,
  bleRequestPermissions,
  bleOpenAdapter,
  bleCloseAdapter,
  bleOnAdapterStateChange,
  bleOffAdapterStateChange,
  bleOpenSystemSettings,
  bleStartDiscovery,
  bleStopDiscovery,
  bleOnDeviceFound,
  bleOffDeviceFound,
  bleCreateConnection,
  bleCloseConnection,
  bleOnConnectionStateChange,
  bleOffConnectionStateChange,
  bleGetServices,
  bleGetCharacteristics,
  bleNotifyValueChange,
  bleReadValue,
  bleWriteValue,
  bleWriteHexValue,
  bleWriteNumberArray,
  bleWriteValueChunked,
  bleGetRecommendedProfile,
  bleIsConnected,
  bleGetConnectedDeviceId,
  bleOnValueChange,
  bleOffValueChange,
  bleReadRssi,
  bleSetMtu,
  bleRelease,
  BLECallbackOptions
} from '@/uni_modules/ble-kit'

蓝牙状态与系统设置

bleOnAdapterStateChange((res : any) => {
  // state: on / off / turningOn / turningOff / unauthorized / unsupported / unknown
  console.log(res)
})

// Android 跳蓝牙设置；iOS 会跳当前 App 设置页
bleOpenSystemSettings({ settingsType: 'bluetooth' } as BLECallbackOptions)

// Android/iOS 均可跳当前 App 设置页
bleOpenSystemSettings({ settingsType: 'app' } as BLECallbackOptions)

// 页面销毁时取消监听
bleOffAdapterStateChange()

初始化与扫描

bleRequestPermissions({
  success: (_res : any) => {
    bleOpenAdapter({
      success: (_openRes : any) => {
        bleStartDiscovery({} as BLECallbackOptions)
      }
    } as BLECallbackOptions)
  }
} as BLECallbackOptions)

bleOnDeviceFound((res : any) => {
  // Android 返回 { devices: [...] }
  // iOS 为保证 UTS 跨线程回调稳定，扫描结果可能以 JSON 字符串返回。
  console.log(res)
})

bleStartDiscovery({
  duration: 10000,
  nameFilter: 'BLE-KIT-TEST',
  showUnnamed: false,
  allowDuplicates: true,
  scanComplete: (res : any) => console.log('scan complete', res)
})

页面退出与资源释放

onUnload() {
  bleRelease({} as BLECallbackOptions)
}

bleRelease 会停止扫描、断开当前连接、清理未完成的 GATT 操作，并移除适配器、设备、连接和数据回调。如果只需移除单个监听，可调用 bleOffDeviceFound、bleOffConnectionStateChange 或 bleOffValueChange。

连接、发现服务和特征

bleCreateConnection(deviceId, {
  success: (_res : any) => {
    bleGetServices(deviceId, {
      success: (serviceRes : any) => console.log(serviceRes)
    } as BLECallbackOptions)
  }
} as BLECallbackOptions)

bleGetCharacteristics(deviceId, serviceId, {
  success: (res : any) => {
    // characteristics[].properties 为平台原生位掩码：
    // 0x02 READ, 0x04 WRITE_NO_RESPONSE, 0x08 WRITE,
    // 0x10 NOTIFY, 0x20 INDICATE
    console.log(res)
  }
} as BLECallbackOptions)

Notify 与接收数据

bleOnValueChange((res : any) => {
  const data = res as UTSJSONObject
  const value = data['value'] as ArrayBuffer
  console.log(new DataView(value))
})

bleNotifyValueChange(
  deviceId,
  serviceId,
  notifyCharacteristicId,
  true,
  {} as BLECallbackOptions
)

HEX、数组与分包写入

插件底层接收 ArrayBuffer。Demo 已提供 HEX 与 ArrayBuffer 互转实现，并会根据特征属性自动选择有响应/无响应写入。

bleWriteValue(
  deviceId,
  serviceId,
  writeCharacteristicId,
  buffer,
  {
    success: (_res : any) => console.log('write ok'),
    fail: (err : any) => console.log(err)
  } as BLECallbackOptions
)

bleWriteHexValue(deviceId, serviceId, writeCharacteristicId, 'A0 01 FF', {
  writeType: 'auto',
  chunkSize: 20,
  interval: 40,
  progress: (res : any) => console.log('progress', res),
  success: (res : any) => console.log('write complete', res)
})

bleWriteNumberArray(deviceId, serviceId, writeCharacteristicId, [0xA0, 0x01, 0xFF], {
  writeType: 'withResponse'
})

writeType 支持 auto、withResponse、withoutResponse。设置 chunkSize > 0 时启用串行分包。

自动推荐通信 UUID

服务和特征发现完成后调用：

bleGetRecommendedProfile(deviceId, serviceId, {
  success: (res : any) => console.log(res)
})

返回推荐的 readCharacteristicId、writeCharacteristicId、notifyCharacteristicId 和 writeType。

权限配置

Demo 的 manifest.json 已配置完整权限。

Android 12+：

• android.permission.BLUETOOTH_SCAN
• android.permission.BLUETOOTH_CONNECT

Android 11 及以下：

• android.permission.BLUETOOTH
• android.permission.BLUETOOTH_ADMIN
• android.permission.ACCESS_FINE_LOCATION

iOS：

• NSBluetoothAlwaysUsageDescription
• NSBluetoothPeripheralUsageDescription

稳定性建议

• 扫描到目标后立即停止扫描，再发起连接。
• 每次连接后重新发现服务和特征，不缓存旧的原生对象。
• 断开、页面销毁或 App 退出业务流程时主动调用断开和关闭适配器。
• iOS 不要把设备 MAC 写死；用扫描得到的 deviceId，业务绑定应结合厂商广播数据或设备自身序列号。
• 长包可以使用 bleWriteValueChunked 或给 bleWriteHexValue 设置 chunkSize 和 interval。
• iOS 锁屏后台持续通信需要具体业务评估后台模式、连接时长和 App Store 审核要求，默认不承诺无限后台保活。

运行 Demo

1. 使用 HBuilderX 打开 ble-kit 目录。
2. 连接 Android 或 iPhone 真机。
3. 运行到 App；若使用自定义基座，需重新制作包含本地 UTS 插件的基座。
4. 默认过滤名称为 BLE-KIT-TEST，依次点击“申请权限”“打开适配器”“开始扫描”。
5. 点击设备连接，Demo 会自动执行“一键发现并选择”。
6. 根据特征属性测试读取、订阅和 HEX 写入。

BLE 无法在普通浏览器或缺少真实外设的模拟器上完整验证。

定价建议

首发建议：

• 加密使用版：49.90 元。
• 源码版：129.90 元。
• 首发期可用 29.90 / 99.90 做冷启动，积累真实设备兼容反馈后恢复原价。

理由：当前主要参考插件普通授权 66 元、源码授权 688 元。本插件首发普通授权略低于同类产品以降低试用门槛，源码版先以较低价格积累真实设备兼容反馈，同时保留后续维护和技术支持成本。