更新记录

1.1.3（2026-09-06）

• 归并本轮 Android 权限修复：打开蓝牙适配器和扫描前按系统版本与宿主 targetSdkVersion 主动申请附近设备或定位权限，拒绝授权统一返回 9014013；版本号保持 1.1.3，发布时与本版本内容一起提交。
• 修复 uni-app x Android 示例的函数声明顺序、ArrayBuffer 类型和蓝牙结果字段读取导致的 UTS 编译错误。

1.1.2（2026-08-31）

• 新增微信小程序真实 BLE Central 实现，覆盖适配器、扫描、连接、服务/特征发现、读写、通知、MTU、RSSI、分包写入和稳定会话。
• 新增 HarmonyOS NEXT ConnectivityKit 真实 BLE Central 实现，覆盖扫描、GATT 连接、服务/特征发现、读写、通知、MTU、RSSI、多连接和有限自动重连。
• Android、iOS、HarmonyOS 与微信小程序统一公开 API、错误码、运行态、能力矩阵和稳定会话合同；Web 与其他未实现平台继续明确返回 9014001。
• HarmonyOS 声明 ohos.permission.ACCESS_BLUETOOTH，系统蓝牙开关仍由用户控制；Harmony 运行需重新构建包含本版本的 HAP。
• 微信小程序新增可控 wx BLE 模拟运行回归，验证扫描、连接、服务/特征、读写、MTU、RSSI、会话 ready 和通知响应匹配。

1.1.1（2026-08-28）

• 读特征与通知事件新增稳定 hex 字段，修复 Android uni-app 页面收到 UTS ArrayBuffer 桥接包装对象后无法直接显示真实字节的问题；原 value: ArrayBuffer 保持兼容。
• 修复 uni-app 示例在部分 Android App WebView 中依赖缺失的 TextEncoder，原始写入与分包写入改为页面内 UTF-8 编码。
• 修复 Android GATT 回调 UUID 大小写不一致导致读、写和通知订阅回调无法命中，稳定会话现可正常从 subscribing 进入 ready。
• Android uni-app 示例对官方不支持的 ArrayBuffer 入参明确提示兼容边界，保留文本、Hex 与稳定会话的真实可用路径。
• 补全示例的会话阶段文案，服务/特征发现与 closed 停止状态不再显示为未知。
• 使用 RootCanal + Bumble 可控 GATT 外设完成 Android 模拟器扫描、连接、服务/特征发现、读写、通知、MTU 与 RSSI 回归。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-ble

lizhao-ble 是面向 uni-app / uni-app x 的跨端 BLE Central UTS API 插件，统一封装扫描、连接、GATT 读写、通知、RSSI、自动重连和分包写入，适合传感器、门锁、仪表、医疗外设与自定义蓝牙协议等业务。

功能特色

• Android BLE Central 完整链路：适配器、扫描、连接、服务发现、特征发现、读、写、通知和多连接。
• iOS 12+ 前台链路：基于 CoreBluetooth 提供扫描、连接、GATT、通知、RSSI、多连接、分包写入与 iOS 前台有限自动重连。
• HarmonyOS NEXT 原生链路：基于 ConnectivityKit 提供扫描、GATT 连接、服务/特征发现、读写、通知、MTU、RSSI、多连接与有限自动重连。
• 微信小程序原生链路：直接使用微信 BLE API，保留与 App 端一致的基础 API、运行态和稳定会话合同。
• 常用链路增强：MTU 协商、RSSI 读取、UTF-8 文本写入、Hex 写入和串行分包写入。
• 连接策略可控：支持自动重连开关、最大尝试次数与重连间隔，不会无限重试。
• 运行状态可观测：getCapabilities 用于能力探测，getRuntimeState 用于读取设备、连接和通知订阅快照。
• 稳定会话：一次调用完成连接、服务/特征发现和通知订阅，并提供每设备串行请求队列、响应匹配、取消与有限重连。
• API 兼容性：保留常见方法别名，并兼容 filterNames/fliterNames、scanComplete/scanComplate 两组拼写。
• 平台边界真实：Android、iOS、HarmonyOS 与微信小程序使用各自平台真实实现；Web 与其他未实现平台返回明确错误，不伪造成功。

接入方式选择

支持平台

环境与安装

• HBuilderX 5.07+
• Android 5.0+（API 21+）
• iOS 12.0+（仅前台 BLE Central 能力）
• HarmonyOS NEXT（使用 ConnectivityKit）
• 微信小程序（建议使用当前稳定基础库）
• 通过 HBuilderX 将插件导入项目的 uni_modules/lizhao-ble
• 页面和其他插件只能从插件根目录导入，不要导入 utssdk 内部文件

// 正确：从插件根目录导入。
import * as Ble from '@/uni_modules/lizhao-ble'

Android 调试必须使用包含本插件 Kotlin 混编代码、Manifest 权限和 UTS 生成物的自定义基座。标准基座或旧自定义基座不能承载新导入的原生代码。Swift 原生代码更新后必须重新制作并安装匹配的 iOS 自定义基座，更新 wgt 或 appResource 不能替换旧基座内的原生代码。

权限准备

插件已在 AndroidManifest.xml 声明所需权限，并会在首次打开适配器或启动扫描时主动发起对应的系统授权：

Android 12+ 且项目 targetSdkVersion >= 31 时使用“附近设备”授权；旧 target 基座和 Android 6–11 使用定位授权兼容扫描。用户拒绝或永久拒绝时，插件进入 fail 并返回 9014013，不会绕过系统授权。项目也可以在调用插件前自行完成授权。

现代 Android 版本通常不允许普通应用静默打开系统蓝牙。如果蓝牙关闭，请先引导用户在系统设置或系统授权界面中打开蓝牙，再调用插件 API。

iOS 已声明蓝牙用途说明。首次访问蓝牙时由系统弹出授权；插件不能绕过授权，也不能代替用户打开或关闭系统蓝牙开关。插件只在本机内存中处理扫描结果、设备标识和通信数据，不采集业务数据，不上传蓝牙数据。

HarmonyOS 需要 ohos.permission.ACCESS_BLUETOOTH，并使用包含本插件原生代码的 HAP；插件不会静默打开或关闭系统蓝牙。微信小程序需在小程序后台和隐私合规配置中按业务实际声明蓝牙用途，授权与系统蓝牙状态以微信客户端回调为准。

最小可运行示例

uni-app（Vue2 / Vue3）

<script>
import * as Ble from '@/uni_modules/lizhao-ble'

export default {
  onLoad() {
    // 先注册监听，避免漏掉扫描开始后的首批设备。
    Ble.onBluetoothDeviceFound((devices) => {
      console.log('发现 BLE 设备', devices)
    })

    // 插件会按 Android 系统版本和项目 targetSdkVersion 主动申请所需权限。
    Ble.openBluetoothAdapter({
      success: () => {
        Ble.startBluetoothDevicesDiscovery({
          allowDuplicatesKey: false,
          success: (res) => {
            console.log('扫描已启动', res)
          },
          fail: (err) => {
            console.log('扫描失败', err)
          }
        })
      },
      fail: (err) => {
        console.log('打开蓝牙适配器失败', err)
      }
    })
  },
  onUnload() {
    // 页面销毁时停止扫描并清理监听，避免持续占用蓝牙资源。
    Ble.stopBluetoothDevicesDiscovery({})
    Ble.offBluetoothDeviceFound()
    Ble.closeBluetoothAdapter({})
  }
}
</script>

uni-app x（UVUE）

<script setup lang="uts">
import {
  openBluetoothAdapter,
  startBluetoothDevicesDiscovery,
  onBluetoothDeviceFound,
  offBluetoothDeviceFound,
  stopBluetoothDevicesDiscovery
} from '@/uni_modules/lizhao-ble'
import type {
  OpenBluetoothAdapterOptions,
  StartBluetoothDevicesDiscoveryOptions,
  StopBluetoothDevicesDiscoveryOptions
} from '@/uni_modules/lizhao-ble'

// 类型只从插件根目录导入，避免依赖插件内部文件结构。
class BleDemoOptions {
  success?: (res: any) => void
  fail?: (err: any) => void
  complete?: (res: any) => void
  allowDuplicatesKey?: boolean
}

onLoad(() => {
  onBluetoothDeviceFound((devices) => {
    console.log('发现 BLE 设备', devices)
  })

  const openOptions = new BleDemoOptions()
  openOptions.success = (_res: any) => {
    const scanOptions = new BleDemoOptions()
    scanOptions.allowDuplicatesKey = false
    scanOptions.fail = (err: any) => {
      console.log('扫描失败', err)
    }
    startBluetoothDevicesDiscovery(scanOptions as StartBluetoothDevicesDiscoveryOptions)
  }
  openOptions.fail = (err: any) => {
    console.log('打开蓝牙适配器失败', err)
  }
  openBluetoothAdapter(openOptions as OpenBluetoothAdapterOptions)
})

onUnload(() => {
  const stopOptions = new BleDemoOptions()
  stopBluetoothDevicesDiscovery(stopOptions as StopBluetoothDevicesDiscoveryOptions)
  offBluetoothDeviceFound()
})
</script>

推荐调用顺序

1. Android 由插件在首次打开适配器或启动扫描时申请当前系统版本所需权限；iOS 由系统在首次使用时请求蓝牙授权。
2. 注册 onBluetoothDeviceFound、onBLEConnectionStateChange 等监听器。
3. 调用 openBluetoothAdapter。
4. 调用 startBluetoothDevicesDiscovery，拿到目标 deviceId 后停止扫描。iOS 的 deviceId 不是 Android MAC，而是来自 CBPeripheral.identifier 的系统 UUID，必须使用本次扫描或系统检索返回的值。
5. 调用 createBLEConnection。
6. 调用 getBLEDeviceServices 与 getBLEDeviceCharacteristics。
7. 根据特征属性执行读取、写入或 notifyBLECharacteristicValueChange。
8. 页面退出时关闭通知、断开连接、停止扫描并移除监听器。

常见增强示例

自动重连

import * as Ble from '@/uni_modules/lizhao-ble'

// 仅在非主动断开时尝试有限次数重连。
Ble.createBLEConnection({
  deviceId: '从扫描结果取得的 deviceId',
  timeout: 10000,
  autoReconnect: true,
  reconnectAttempts: 3,
  reconnectInterval: 2000,
  success(res) {
    console.log('连接成功', res)
  },
  fail(err) {
    console.log('连接失败', err)
  }
})

自动重连只恢复系统连接状态，不自动恢复已经发现的 GATT 服务、特征或通知订阅。连接状态重新变为已连接后，业务必须再次调用 getBLEDeviceServices、getBLEDeviceCharacteristics，并按需重新调用 notifyBLECharacteristicValueChange。

MTU 与 RSSI

import * as Ble from '@/uni_modules/lizhao-ble'

// Android 可主动请求 MTU；iOS 不支持主动 MTU 协商，调用会 fail(9014001)。
Ble.requestBLEMTU({
  deviceId: '从扫描结果取得的 deviceId',
  mtu: 185,
  success(res) {
    console.log('协商后的 MTU', res.mtu)
  }
})

// RSSI 读取要求设备已经连接。
Ble.readBLEDeviceRSSI({
  deviceId: '从扫描结果取得的 deviceId',
  success(res) {
    console.log('当前 RSSI', res.RSSI)
  }
})

文本、Hex 与分包写入

import * as Ble from '@/uni_modules/lizhao-ble'

const target = {
  deviceId: '从扫描结果取得的 deviceId',
  serviceId: '0000fff0-0000-1000-8000-00805f9b34fb',
  characteristicId: '0000fff2-0000-1000-8000-00805f9b34fb'
}

// UTF-8 文本写入。
Ble.writeBLECharacteristicValueByText({
  ...target,
  text: 'ping'
})

// Hex 支持空格、冒号、短横线和 0x 前缀。
Ble.writeBLECharacteristicValueByHex({
  ...target,
  hex: '70 69 6e 67'
})

// 长数据按 20 字节串行写入，每包间隔 20 ms。
Ble.writeBLECharacteristicValueChunked({
  ...target,
  value: new TextEncoder().encode('long payload').buffer,
  chunkSize: 20,
  interval: 20
})

完整示例

• uni-app：uni_modules/lizhao-ble/example/uniapp/ble.vue
• uni-app x：uni_modules/lizhao-ble/example/uniappx/index.uvue

示例页会触发插件的 Android 系统授权流程，但不会绕过用户选择，也不能替代真实 BLE 外设验收。

稳定会话 API

会话层是可选能力，不会改变底层扫描、连接和特征 API。它适合“写入一条命令并等待通知响应”的设备协议；Android 与 iOS 均支持，且需要包含当前原生源码的自定义基座。

import {
  startBLESession,
  sendBLESessionRequest,
  onBLESessionData
} from '@/uni_modules/lizhao-ble'

onBLESessionData((event) => {
  console.log(event.direction, event.requestId, event.hex, event.matched)
})

startBLESession({
  deviceId: '扫描得到的设备标识',
  serviceId: '服务 UUID',
  writeCharacteristicId: '写特征 UUID',
  notifyCharacteristicId: '通知特征 UUID',
  autoReconnect: true,
  success(state) {
    console.log('会话已就绪', state.phase)
  }
})

sendBLESessionRequest({
  deviceId: '扫描得到的设备标识',
  requestId: 'query-status-1',
  encoding: 'hex',
  hex: 'A001',
  responseMode: 'hexPrefix',
  responseHex: 'A081',
  timeout: 10000,
  success(result) {
    console.log('收到匹配响应', result)
  }
})

sendBLESessionRequest 的 encoding 为 text 时使用 text，为 hex 时使用偶数长度 hex，为 buffer 时使用 value: ArrayBuffer。队列最多保留 100 项；断线时正在执行的请求失败且不会偷偷重发，尚未开始的排队请求可在有限重连恢复后继续。

iOS 闭包监听器无法稳定按对象身份比较，因此 offBLESessionStateChange(listener) 和 offBLESessionData(listener) 无论是否传 listener，都会清空对应类别的全部监听器。

API 列表

通用回调参数

除 onXxx/offXxx 监听器外，异步 API 的 options 均支持以下回调：

适配器 API

openBluetoothAdapter(options)

说明

初始化插件管理的蓝牙适配器资源。调用前应已获得当前平台授权并确保系统蓝牙可用。

支持平台

Android 5.0+、iOS 12+ 前台、HarmonyOS NEXT、微信小程序；Web 与其他未实现平台通过 fail 返回 9014001。

参数

返回值

closeBluetoothAdapter(options)

说明

停止扫描、关闭当前连接并释放插件维护的适配器状态。

参数

返回值

getBluetoothAdapterState(options)

说明

获取当前适配器和扫描状态。

参数

返回值

扫描与设备 API

startBluetoothDevicesDiscovery(options)

说明

启动 BLE 扫描。名称筛选采用不区分大小写的包含匹配；服务 UUID 由 Android 扫描过滤器处理。

参数

返回值

stopBluetoothDevicesDiscovery(options)

说明

停止当前扫描，并在成功后触发 scanComplete/scanComplate。

参数

返回值

getBluetoothDevices(options)

说明

返回插件本次运行期间已发现的设备列表。

返回值

getConnectedBluetoothDevices(options)

说明

返回当前由插件维护的已连接设备列表。

返回值

连接 API

createBLEConnection(options)

说明

连接目标设备，并可配置受控自动重连。

返回值

closeBLEConnection(options)

返回值

服务与特征 API

getBLEDeviceServices(options)

返回值

getBLEDeviceCharacteristics(options)

返回值

readBLECharacteristicValue(options)

返回值

writeBLECharacteristicValue(options)

Android uni-app 页面需要写入文本或十六进制数据时，优先使用 writeBLECharacteristicValueByText 或 writeBLECharacteristicValueByHex；这样不依赖页面与 UTS 插件之间的 ArrayBuffer 入参桥接。

写入增强 API

writeBLECharacteristicValueByText(options)

在 writeBLECharacteristicValue 的设备、服务、特征和回调参数基础上，使用以下字段：

writeBLECharacteristicValueByHex(options)

writeBLECharacteristicValueChunked(options)

Android uni-app 页面无法直接向 UTS 插件传入 ArrayBuffer，因此本接口应在 uni-app x 或支持该桥接的平台调用。Android uni-app 的长文本 / Hex 数据可使用稳定会话的 sendBLESessionRequest，通过 encoding 与 chunkSize 让插件原生层完成分包。

返回值

链路增强 API

requestBLEMTU(options)

返回值

readBLEDeviceRSSI(options)

返回值

通知 API

notifyBLECharacteristicValueChange(options)

监听 API

监听器均持续有效，直到调用对应 offXxx。Android 可按插件实现移除监听；iOS 调用 offXxx(listener) 会清空该类监听，因为 Swift 闭包不能安全依赖跨语言相等比较。offXxx() 不传 listener 时同样清空该类全部监听器。

诊断 API

getCapabilities(options)

返回值

getRuntimeState(options)

返回值

兼容别名

兼容别名与规范 API 参数、回调和平台边界完全相同。新项目建议使用规范 API。

错误码

失败对象包含 errSubject='lizhao-ble'、errCode、errMsg 和可选 details/data。

自定义基座与发布

• 首次导入插件、升级 Kotlin 原生代码或权限后，需要重新制作 Android 自定义基座。
• Swift 原生代码更新后必须重新制作并安装匹配的 iOS 自定义基座；仅更新页面、wgt 或 appResource 不能替换旧基座中的 Swift。
• 仅更新 wgt/appResource 不能替换旧基座中已经编译的 UTS/Kotlin/Swift 原生代码。
• 正式发布 App 时，使用当前插件源码重新执行原生联编或云打包。
• iOS 能力发布前建议在 iOS 12+ 真机与真实 BLE 外设完成扫描、连接、GATT、通知、RSSI、分包、回调次数和前台有限自动重连验收；源码守卫或生成 Swift 不能代替真机证据。
• 付费插件试用需要使用与当前 appid、包名匹配的自定义基座；旧工程或其他账号生成的基座不能作为当前试用证据。

注意事项

• BLE 外设协议并不统一；服务 UUID、特征 UUID、字节序、校验、分包和响应规则由具体设备协议决定。
• chunkSize=20 是兼容默认值。协商更大 MTU 后，仍应按外设实际可接受长度设置分包大小。
• writeNoResponse=true 只适用于声明 writeWithoutResponse 的特征；不支持时应改用有响应写入。
• 无响应写入的 success 仅表示系统接受发送请求，不代表外设已经接收、校验或执行指令；需要业务确认时应设计通知或读取回执。
• iOS 不支持主动 MTU 协商，requestBLEMTU 会返回 9014001；分包上限由 CoreBluetooth 当前连接自动给出。
• 系统蓝牙开关不能由插件关闭；closeBluetoothAdapter 只释放插件管理的扫描、连接、定时器和监听状态。
• 自动重连仅处理非主动断开；主动调用 closeBLEConnection 或 closeBluetoothAdapter 会清理重连状态。
• 页面销毁时应停止扫描、关闭不再使用的通知和连接，并移除持续监听器。
• 自动编译不能替代 Android 真机与真实 BLE 外设验收。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。