更新记录

1.0.0（2026-07-24）

• 首发 lizhao-ble Android BLE Central UTS API 插件，支持 uni-app Vue2/Vue3、nvue 与 uni-app x。
• 提供蓝牙适配器开关与状态、设备扫描与筛选、连接/断开、服务与特征发现、特征读写、通知订阅和状态监听。
• 提供 MTU 协商、RSSI 读取、UTF-8 文本写入、Hex 写入、串行分包写入、多连接和受控自动重连。
• 提供 getCapabilities 与 getRuntimeState，用于在展示业务入口前判断能力并读取运行态快照。
• 保留 openBtBluetooth、startScanBle、connectBle 等兼容别名，以及 filterNames/fliterNames、scanComplete/scanComplate 拼写兼容。
• Android 5.0+ 为真实实现；iOS、Harmony、Web、微信小程序与支付宝小程序保留类型一致的降级入口，核心 API 明确返回 9014001，不伪造成功。
• Android 12+ 需要蓝牙扫描与连接运行时权限；Android 11 及以下扫描可能需要位置权限。
• 包含 uni-app 与 uni-app x 最小示例、完整 API 文档、错误码、权限说明和上架前回归清单。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-ble

当前版本：1.0.0

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

功能特色

• Android BLE Central 完整链路：适配器、扫描、连接、服务发现、特征发现、读、写、通知和多连接。
• 常用链路增强：MTU 协商、RSSI 读取、UTF-8 文本写入、Hex 写入和串行分包写入。
• 连接策略可控：支持自动重连开关、最大尝试次数与重连间隔，不会无限重试。
• 运行状态可观测：getCapabilities 用于能力探测，getRuntimeState 用于读取设备、连接和通知订阅快照。
• API 兼容性：保留常见方法别名，并兼容 filterNames/fliterNames、scanComplete/scanComplate 两组拼写。
• 平台边界真实：Android 为实际实现；其他平台返回明确错误，不伪造扫描、连接或写入成功。

接入方式选择

支持平台

环境与安装

• HBuilderX 5.07+
• Android 5.0+（API 21+）
• 通过 HBuilderX 将插件导入项目的 uni_modules/lizhao-ble
• 页面和其他插件只能从插件根目录导入，不要导入 utssdk 内部文件

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

Android 调试必须使用包含本插件 Kotlin 混编代码、Manifest 权限和 UTS 生成物的自定义基座。标准基座或旧自定义基座不能承载新导入的原生代码。

权限准备

插件已在 AndroidManifest.xml 声明所需权限，但 Android 危险权限仍需业务应用在运行时向用户申请：

请在调用扫描、连接等 API 前完成授权。插件检测到权限缺失时会进入 fail，返回 9014013，不会绕过系统授权。

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

最小可运行示例

uni-app（Vue2 / Vue3）

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

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

    // 运行时权限应在此之前由业务应用完成申请。
    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 版本所需的运行时权限。
2. 注册 onBluetoothDeviceFound、onBLEConnectionStateChange 等监听器。
3. 调用 openBluetoothAdapter。
4. 调用 startBluetoothDevicesDiscovery，拿到目标 deviceId 后停止扫描。
5. 调用 createBLEConnection。
6. 调用 getBLEDeviceServices 与 getBLEDeviceCharacteristics。
7. 根据特征属性执行读取、写入或 notifyBLECharacteristicValueChange。
8. 页面退出时关闭通知、断开连接、停止扫描并移除监听器。

常见增强示例

自动重连

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

// 仅在非主动断开时尝试有限次数重连。
Ble.createBLEConnection({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  timeout: 10000,
  autoReconnect: true,
  reconnectAttempts: 3,
  reconnectInterval: 2000,
  success(res) {
    console.log('连接成功', res)
  },
  fail(err) {
    console.log('连接失败', err)
  }
})

MTU 与 RSSI

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

// 实际 MTU 由 Android 系统和外设共同决定。
Ble.requestBLEMTU({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  mtu: 185,
  success(res) {
    console.log('协商后的 MTU', res.mtu)
  }
})

// RSSI 读取要求设备已经连接。
Ble.readBLEDeviceRSSI({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  success(res) {
    console.log('当前 RSSI', res.RSSI)
  }
})

文本、Hex 与分包写入

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

const target = {
  deviceId: 'AA:BB:CC:DD:EE:FF',
  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

示例页用于功能回归，不会替业务应用自动申请系统权限，也不会替代真实 BLE 外设验收。

API 列表

通用回调参数

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

适配器 API

openBluetoothAdapter(options)

说明

初始化 Android 蓝牙适配器。调用前应已获得权限并确保系统蓝牙可用。

支持平台

Android 5.0+；其他平台通过 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)

写入增强 API

writeBLECharacteristicValueByText(options)

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

writeBLECharacteristicValueByHex(options)

writeBLECharacteristicValueChunked(options)

返回值

链路增强 API

requestBLEMTU(options)

返回值

readBLEDeviceRSSI(options)

返回值

通知 API

notifyBLECharacteristicValueChange(options)

监听 API

监听器均持续有效，直到调用对应 offXxx。offXxx() 不传 listener 时清空该类全部监听器。

诊断 API

getCapabilities(options)

返回值

getRuntimeState(options)

返回值

兼容别名

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

错误码

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

自定义基座与发布

• 首次导入插件、升级插件原生代码或权限后，需要重新制作 Android 自定义基座。
• 仅更新 wgt/appResource 不能替换旧基座中已经编译的 UTS/Kotlin 原生代码。
• 正式发布 App 时，使用当前插件源码重新执行原生联编或云打包。
• 付费插件试用需要使用与当前 appid、包名匹配的自定义基座；旧工程或其他账号生成的基座不能作为当前试用证据。

注意事项

• BLE 外设协议并不统一；服务 UUID、特征 UUID、字节序、校验、分包和响应规则由具体设备协议决定。
• chunkSize=20 是兼容默认值。协商更大 MTU 后，仍应按外设实际可接受长度设置分包大小。
• writeNoResponse=true 只适用于声明 writeWithoutResponse 的特征；不支持时应改用有响应写入。
• 自动重连仅处理非主动断开；主动调用 closeBLEConnection 或 closeBluetoothAdapter 会清理重连状态。
• 页面销毁时应停止扫描、关闭不再使用的通知和连接，并移除持续监听器。
• 自动编译不能替代 Android 真机与真实 BLE 外设验收。

作者系列 UTS 插件