更新记录

1.0.0（2026-07-03）

• 首发 BleLib 实例化 API
• 支持 Android / iOS App 端 BLE 扫描、连接、读写与广播
• Harmony 保留 stub

平台兼容性

uni-app(5.14)

uni-app x(5.14)

hans-ble-kit

BLE UTS 插件，目标是用同一套 BleLib 实例 API 同时服务 uni-app 和 uni-app x 的 Android / iOS App 端。

支持平台

快速接入

import { BleLib } from '@/uni_modules/hans-ble-kit'

const ble = new BleLib()

ble.setDebugMode(true)
ble.onBluetoothStateListener((res) => {
  console.log('state', res)
})

ble.startScanBleDevice({
  namePrefix: 'demo',
  timeout: 3000,
  autoStop: true,
})

API 概览

• 状态：isEnabled、getBluetoothSystemSetting、getBluetoothAuthorizeSetting、openBluetooth、openBluetoothSettings、onBluetoothStateListener、offBluetoothStateListener
• 扫描：startScanBleDevice、stopScanBle、onScanDataListener、offScanDataListener
• 连接：connect、close、onConnectStateListener、offConnectStateListener、isConnected、getConnectMac
• 服务与特征：scanServices、getUUIDs、selectUUID(serviceId)、getServiceUUID、getNotifyUUID、getWriteUUID、getReadUUID
• 广播：isAdvertising、startAdvertise、stopAdvertise、onAdvertiseStateListener、offAdvertiseStateListener
• 读写：onNotifyBleData、offNotifyBleData、onReadData、offReadData、sendData、readRssi、setMtu、setPhy2MMode
• 编解码：encodeText、decodeText
• 调试与生命周期：setDebugMode、setThreadTypeName、setIOSConnectNotifyAlertEnabled、destroy

扫描、广播、写入配置对象按 UTSJSONObject 接收；同步返回值和回调 res 也直接使用 UTSJSONObject。插件不导出设备、通知、结果等强类型别名，字段契约以本文档为准。

通用结果

除同步布尔值、字符串和数组 getter 外，带回调的 API 均返回同一层 UTSJSONObject 结果：

• type: number，事件类型。0 表示同步请求成功，1001 状态，1002 扫描，1003 连接，1004 服务，1005 通知，1006 读取，1007 写入，1008 RSSI，1009 MTU，1010 PHY，1011 广播，1099 错误。
• message: string，结果说明。
• data: any，具体数据，按事件类型变化。
• instanceId: number，BleLib 实例 id。
• platform: string，android / ios / harmony。
• timestamp: number，毫秒时间戳。

错误结果

当 type == 1099 时，data 固定为错误对象：

• errSubject: string，固定为 hans-ble-kit。
• errCode: number，插件错误码。
• errMsg: string，稳定错误消息。
• method: string，触发错误的 API 名；原生异步事件无法精确归因时为 nativeEvent。
• details: UTSJSONObject | null，原生层带回的上下文，例如 reason、status、code、mac、serviceId、characteristicId、payload。

错误码：

• 9010001: unsupported
• 9010002: invalid parameter
• 9010003: bluetooth disabled
• 9010004: permission denied
• 9010005: not initialized
• 9010006: scan failed
• 9010007: connect failed
• 9010008: disconnect failed
• 9010009: service not found
• 9010010: characteristic not found
• 9010011: notify failed
• 9010012: read failed
• 9010013: write failed
• 9010014: rssi failed
• 9010015: mtu unsupported
• 9010016: phy unsupported
• 9010017: settings unavailable
• 9010018: advertise failed
• 9010019: not connected
• 9010099: unknown

data 字段契约

系统设置，来自 getBluetoothSystemSetting() 或状态事件：

• bluetoothSupported: boolean，当前平台/设备是否支持蓝牙。
• bluetoothEnabled: boolean，系统蓝牙是否开启。
• bluetoothError: string | null，不可用原因。

授权设置，来自 getBluetoothAuthorizeSetting() 或状态事件：

• bluetoothAuthorized: string，authorized / denied / not determined / config error / unsupported。
• scanAuthorized: string，扫描授权状态。
• connectAuthorized: string，连接授权状态。
• advertiseAuthorized: string，广播授权状态。
• scanReady: boolean，是否可直接扫描。
• connectReady: boolean，是否可直接连接。
• advertiseReady: boolean，是否可直接广播。
• authError: string | null，授权或配置错误。

扫描设备，来自 onScanDataListener 或 startScanBleDevice({ onScanResult })：

• deviceId: string，平台设备 id；Android 通常等于 MAC，iOS 通常为 peripheral UUID。
• mac: string | null，设备地址；iOS 无真实 MAC 时为空。
• name: string | null，设备名。
• device: UTSJSONObject，含 address、name。
• rssi: number | null，信号强度。
• connectable: boolean，是否可连接。
• services: string[]，广播中的 service UUID。
• manufacturerData: string | null，十六进制厂商数据。
• serviceData: string | null，十六进制 service data。
• advertisement: string | null，十六进制广播原始数据。

连接状态，来自 connect、close、onConnectStateListener 或连接事件。connect/close 的回调会先收到请求回执，并继续收到本次连接生命周期内的成功、失败或断开事件：

• mac: string | null，连接目标。
• deviceId: string | null，平台设备 id。
• autoConnect: boolean | null，仅请求回执中可能存在。

服务 profile，来自 scanServices 和 getUUIDs()：

• serviceId: string，服务 UUID。
• serviceName: string | null，服务名。
• readId: string | null，读取特征 UUID。
• writeId: string | null，写入特征 UUID。
• notifyId: string | null，通知特征 UUID。
• indicateId: string | null，indicate 特征 UUID。
• properties: string[]，如 read、write、notify、indicate。

通知/读取数据，来自 onNotifyBleData、onReadData 或异步通知：

• serviceId: string，服务 UUID。
• characteristicId: string，特征 UUID。
• hexStrData: string，十六进制数据。
• data: number[]，字节数组。
• buffer: ArrayBuffer | null，平台可用时返回。
• mac: string | null，设备地址或设备 id。

写入回执，来自 sendData：

• serviceId: string，服务 UUID。
• characteristicId: string，写入特征 UUID。
• payload: string，十六进制写入内容。
• withoutResponse: boolean，是否无响应写。
• segmentSize: number，分包大小，0 表示不强制分包。
• segmentInterval: number，分包间隔毫秒。

RSSI / MTU / PHY / 广播：

• RSSI data: rssi number。
• MTU data: mtu number。
• PHY data: txPhy number、rxPhy number、status number。
• 广播 data: isAdvertising boolean；失败时错误上下文在 details.code 或 details.reason。

options 字段契约

startScanBleDevice(options, cb?)：

• serviceUUIDs: string[]，按服务 UUID 过滤。
• deviceIds: string[]，按设备 id 过滤。
• name: string，按完整设备名过滤。
• namePrefix: string，按设备名前缀过滤。
• allowDuplicates: boolean，是否允许重复上报。
• autoStop: boolean，超时后是否自动停止。
• timeout: number，扫描超时毫秒；大于 0 时默认 autoStop=true。
• scanMode: number，Android 扫描模式，默认 2。
• onScanResult: function，单设备扫描回调。
• scanComplete: function，停止扫描回调。

startAdvertise(options, cb?)：

• profile: UTSJSONObject | null，服务 profile。
• serviceId: string，服务 UUID，优先级高于 profile.serviceId。
• serviceName: string，服务名。
• localName: string，本机广播名。
• connectable: boolean，是否可连接。
• includeDeviceName: boolean，是否携带设备名。
• includeTxPowerLevel: boolean，是否携带发射功率。
• autoStop: boolean，超时后是否自动停止。
• timeout: number，广播超时毫秒。
• onAdvertiseResult: function，停止广播回调。

sendData(data, cb?)：

• serviceId: string，服务 UUID；为空时使用当前选中的 service。
• characteristicId: string，写入特征 UUID；为空时使用当前选中的 write/notify UUID。
• buffer: ArrayBuffer，写入二进制数据。
• data: number[]，写入字节数组。
• hexStrData: string，写入十六进制字符串。
• text: string，写入文本。
• charset: string，utf-8 / hex。
• withoutResponse: boolean，是否无响应写。
• segmentSize: number，分包大小。
• segmentInterval: number，分包间隔毫秒。

监听器生命周期

• onBluetoothStateListener(cb) / offBluetoothStateListener()：注册或移除蓝牙状态监听。
• onScanDataListener(cb) / offScanDataListener()：注册或移除扫描结果监听；不会停止扫描。
• onConnectStateListener(cb) / offConnectStateListener()：注册或移除连接状态监听；不会主动连接或断开。
• onAdvertiseStateListener(cb) / offAdvertiseStateListener()：注册或移除广播状态监听；不会停止广播。
• onNotifyBleData(serviceId, characteristicId, enable, cb?) / offNotifyBleData()：注册或移除通知数据回调；关闭底层通知仍应调用 onNotifyBleData(..., false)。
• onReadData(serviceId, characteristicId, cb?) / offReadData()：发起读取并注册读取回调；offReadData() 只移除后续读取事件回调。

服务 profile 保留在插件内部，页面按 serviceId 调用 selectUUID 选择后，通过 getter 读取当前 UUID。

当前已知边界

• iOS setMtu / setPhy2MMode 当前明确返回 unsupported。
• iOS peripheral / advertising 当前明确返回 unsupported，发布配置中不声明 NSBluetoothPeripheralUsageDescription 或 bluetooth-peripheral 后台模式。
• 广播 / peripheral 能力已经有入口，但仍需要按验证清单补齐真机验收。

权限说明

• Android：声明 BLUETOOTH、BLUETOOTH_ADMIN、ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、BLUETOOTH_SCAN、BLUETOOTH_CONNECT、BLUETOOTH_ADVERTISE，用于扫描、连接、读写和广播 BLE 设备。
• iOS：声明 NSBluetoothAlwaysUsageDescription，用于扫描、连接和读写 BLE 设备。
• 插件不主动上传蓝牙数据到服务器；业务侧如需存储或上传扫描结果、设备标识或读写数据，应自行完成用户授权和隐私声明。