更新记录

1.1.69（2026-07-14）

修复用户反馈Android的闪退问题

1.1.68（2026-07-07）

优化用户反馈的闪退问题

1.1.67（2026-07-03）

增加 Android iOS 鸿蒙 onIndicate 真实订阅与数据读取功能 优化 Android indicate 特征判断与回调 优化 iOS 与鸿蒙 indicate 订阅成功失败和数据回调

平台兼容性

uni-app(4.07)

uni-app x(4.07)

其他

android-ble

android-ble 是一个面向 uni-app / uni-app x 的 BLE 低功耗蓝牙插件，支持 Android、iOS、鸿蒙、微信小程序。

插件市场相关资源：

• BLE 插件：android-ble 支付多端 安卓 ios 鸿蒙 微信小程序
• 经典蓝牙 SPP 插件：安卓Spp经典蓝牙插件
• Ble服务端插件Android ble低功耗蓝牙周边服务蓝牙服务端
• uni-app 示例工程压缩包：bt_uniapp.zip
• uni-app x 示例页面：App.uvue、pages/Multi/Multi.uvue

功能概览

• 支持 BLE 扫描、停止扫描、扫描结果过滤
• 支持连接、断开、自动重连、连接超时设置
• 支持扫描服务与特征值、自动识别可写/可通知 UUID
• 支持通知订阅、indicate 订阅、主动读取、RSSI 读取、MTU 设置
• 支持十六进制字符串、数字数组、ArrayBuffer 写入
• 支持分包发送
• 支持多蓝牙连接场景
• iOS 支持按服务 UUID 获取系统已连接设备，并接管到当前 BleLib 实例
• 支持监听系统蓝牙开关状态

平台支持

补充说明：

• iOS 需 iOS 13 及以上版本。
• Android / iOS / 鸿蒙运行原生能力时，建议使用自定义基座验证。
• 微信小程序端按 BleLib 实例维护连接状态，适合一个对象对应一个蓝牙连接。
• getConnectedDevicesWithServices 与 redictToConnect 是 iOS 专属方法，只有 iOS 可以调用，Android、鸿蒙、微信小程序、Web 都不支持调用。

安装与运行

插件试用与下载

1. 在插件市场选择试用，并绑定目标项目 appid。
2. 下载插件到本地项目。
3. 在页面中从 @/uni_modules/android-ble 引入 BleLib 与相关类型。

快速上手

本节用于帮助开发者快速跑通 BLE 标准流程，下面给出 uni-app x 与 uni-app 双端示例。

最短接入步骤

1. 引入 BleLib，创建蓝牙对象实例。
2. 调用 openBtBluetooth 初始化蓝牙适配器。
3. 调用 onStartScanBle 开始扫描设备。
4. 拿到目标设备地址后调用 connect。
5. 连接成功后调用 scanServices。
6. 调用 getUUIDs 查看自动识别出的可用 UUID 组合。
7. 必要时调用 setSelectUUID 切换到目标 service/notify/write 组合。
8. 调用 onNotityBleData 开启通知，或调用 onIndicate 开启 indicate 订阅。
9. 调用 sendData 发送数据。
10. 结束时调用 close 断开连接。

uni-app x 快速上手

import { BleLib, MyApiResult, BleScanResult, WNuuid, WriteData, NotityData, ScanPara } from "@/uni_modules/android-ble"

let lib = new BleLib()
let firstMac = ""

lib.openBtBluetooth(function(res:MyApiResult){
  console.log("openBtBluetooth", res)
})

lib.onBtOpenStateListener(function(res:MyApiResult){
  console.log("bt state", res)
})

let scanPara:ScanPara = {
  scantime:10 * 1000,
  showEmptyName:0,
  btNameFilter:"",
  onScanResult:function(res:MyApiResult){
    // type 为0 扫描成功  10001 表示无蓝牙权限 10002 表示蓝牙未开启
    if(res.type == 0){
      let scan = res.data as BleScanResult
      console.log("scan", scan)
      if(firstMac == ""){
        firstMac = scan.device.address
      }
    }
  },
  scanComplate:function(){
    console.log("scan complete")
    if(firstMac != ""){
      lib.connect(firstMac,false,function(res:MyApiResult){
        console.log("connect", res)
        // type  0  成功  10000 蓝牙连接失败 10001 蓝牙异常断开  10002 表示蓝牙未开启  10003表示无蓝牙权限  10004 表示蓝牙已经连接 10005  鸿蒙虚拟蓝牙地址无效
        if(res.type == 0){
          lib.scanServices(function(serviceRes:MyApiResult){
            console.log("services", serviceRes)
            if(serviceRes.type == 0){
              let uuidList = lib.getUUIDs() as WNuuid[]
              console.log("uuidList", uuidList)
              let uuids = lib.getUUIDs()
              console.log("uuids", uuids)
              if(uuids.length > 0){
                lib.setSelectUUID(0)
                lib.onNotityBleData(
                  lib.getServiceUUID(),
                  lib.getNotityUUID(),
                  true,
                  function(notifyRes:MyApiResult){
                    // type 为0 表示通知数据  1000 表示订阅成功  1001 表示订阅失败
                    if(notifyRes.type == 0){
                      let data = notifyRes.data as NotityData
                      console.log("notify", data)
                    }
                  }
                )
                let writeData:WriteData = {
                  serviceId:lib.getServiceUUID(),
                  characteristicId:lib.getwriteUUID(),
                  fenbao:false,
                  hexStrData:"FF001122"
                }
                lib.sendData(writeData,function(sendRes:MyApiResult){
                  console.log("send", sendRes)
                })
                let readData:WriteData = {
                  serviceId:lib.getServiceUUID(),
                  characteristicId:lib.getwriteUUID(),
                  fenbao:false,
                  data:[0xff,0x00,0x11,0x22] as number[]
                }
                lib.sendData(readData,function(sendRes:MyApiResult){
                  console.log("send", sendRes)
                })
              }
            }
          })
        }
      })
    }
  }
}

lib.onStartScanBle(scanPara)

uni-app 快速上手

import { BleLib } from "@/uni_modules/android-ble"

var lib = new BleLib()
var firstMac = ""

lib.openBtBluetooth(function(res){
  console.log("openBtBluetooth", res)
})

lib.onBtOpenStateListener(function(res){
  console.log("bt state", res)
})

lib.onStartScanBle({
  scantime:10 * 1000,
  showEmptyName:0,
  btNameFilter:"",
  onScanResult:function(res){
    // type 为0 扫描成功  10001 表示无蓝牙权限 10002 表示蓝牙未开启
    if(res.type == 0){
      var scan = res.data
      console.log("scan", scan)
      if(firstMac == ""){
        firstMac = scan.device.address
      }
    }
  },
  scanComplate:function(){
    console.log("scan complete")
    if(firstMac != ""){
      lib.connect(firstMac,false,function(res){
        console.log("connect", res)
        // type  0  成功  10000 蓝牙连接失败 10001 蓝牙异常断开  10002 表示蓝牙未开启  10003表示无蓝牙权限  10004 表示蓝牙已经连接 10005  鸿蒙虚拟蓝牙地址无效
        if(res.type == 0){
          lib.scanServices(function(serviceRes){
            console.log("services", serviceRes)
            var uuids = lib.getUUIDs()
            console.log("uuids", uuids)
            if(uuids.length > 0){
              lib.setSelectUUID(0)
              lib.onNotityBleData(
                lib.getServiceUUID(),
                lib.getNotityUUID(),
                true,
                function(notifyRes){
                  // type 为0 表示通知数据  1000 表示订阅成功  1001 表示订阅失败
                  console.log("notify", notifyRes)
                }
              )
              lib.sendData({
                serviceId:lib.getServiceUUID(),
                characteristicId:lib.getwriteUUID(),
                fenbao:false,
                hexStrData:"FF001122"
              },function(sendRes){
                console.log("send", sendRes)
              })
            }
          })
        }
      })
    }
  }
})

自定义基座

1. 在 HBuilderX 中执行云打包并制作自定义基座。
2. 基座制作完成后，运行到手机或模拟器。
3. 选择运行到 Android App 基座，并选择自定义基座。
4. 如果之前安装过旧基座，请先卸载旧版本后再安装。

iOS 蓝牙权限配置

iOS 端除了引入插件，还需要在项目 manifest.json 的 app-ios.distribute.privacyDescription 中配置蓝牙用途说明，否则首次访问蓝牙时可能不弹权限框，系统设置里也不会出现应用的蓝牙权限开关。

参考配置：

{
  "app-ios": {
    "distribute": {
      "privacyDescription": {
        "NSBluetoothAlwaysUsageDescription": "应用需要使用蓝牙扫描、连接和通信外设设备",
        "NSBluetoothPeripheralUsageDescription": "应用需要使用蓝牙扫描、连接和通信外设设备"
      }
    }
  }
}

说明：

• 修改后需要重新云打包或重新生成 iOS 安装包才会生效。
• 建议卸载旧包后再安装新包。
• iOS 一般在首次扫描、连接等真正访问蓝牙时弹权限框，不一定在应用启动瞬间弹出。

推荐调用流程

建议按下面顺序接入：

1. 创建 BleLib 实例。
2. 调用 openBtBluetooth 初始化蓝牙适配器。
3. 可选：调用 onBtOpenStateListener 监听系统蓝牙开关状态。
4. 调用 onStartScanBle 或 startScanBleDevice 扫描设备。
5. 拿到设备地址后调用 connect 连接。
6. 连接成功后调用 scanServices 扫描服务。
7. 通过 getUUIDs 获取自动识别出的可用服务组合，必要时调用 setSelectUUID 切换。
8. 调用 onNotityBleData 开启通知。
9. 调用 sendData 发送数据，或调用 onReadData 主动读取。
10. 完成后调用 close 断开连接。

iOS 已连接设备恢复场景：

• 先调用 getConnectedDevicesWithServices 按服务 UUID 获取系统当前已连接设备。
• 再把返回结果中的 device.address 传给 redictToConnect，让当前 BleLib 实例接管连接。

多设备场景建议：

• 每个蓝牙连接使用一个独立的 BleLib 实例。
• 可参考 pages/Multi/Multi.uvue 的多连接演示页面。

主要类型

ScanPara

扫描参数，常用字段如下：

• btNameFilter：按名称关键字过滤
• fliterNames：按多个名称前缀过滤
• scantime：扫描时长，单位毫秒
• showEmptyName：是否返回空名称设备，0 表示不返回，1 表示返回
• iosFilterUUIDs：按 service UUID 数组过滤扫描，当前支持 iOS、Android、鸿蒙、微信小程序
• onScanResult：扫描结果回调
• scanComplate：扫描结束回调

WNuuid

自动识别出的可用服务组合：

• serviceId
• wuuid
• nuuid

WriteData

写入参数：

• serviceId：服务 UUID
• characteristicId：写入特征 UUID
• writeType：写入类型，0 为 WRITE，1 为 WRITE_NO_RESPONSE
• buffer：原始二进制数据，优先级最高
• data：数字数组
• hexStrData：十六进制字符串
• fenbao：是否自动分包发送

写入优先级：buffer > data > hexStrData

MyApiResult

统一回调结构：

• type：状态码
• message：状态说明
• data：返回数据

NotityData

通知 / indicate / 读取回调数据结构：

• data：字节数组
• mac：设备地址，部分平台返回
• serviceId：服务 UUID
• characteristicsId：特征 UUID

API 清单

适配器与状态

• isEnabled：检测蓝牙是否开启
• openBtBluetooth：初始化蓝牙适配器
• openBluetooth：打开或关闭蓝牙
• openBluetoothSettings：打开蓝牙设置页
• onBtOpenStateListener：监听系统蓝牙开关状态

扫描相关

• onStartScanBle：新版扫描接口，推荐使用
• startScanBleDevice：旧版扫描接口，兼容保留
• onScanDataListener：监听广播信号变化
• stopScanBle：停止扫描

连接相关

• connect：连接蓝牙
• close：断开蓝牙
• isConnected：是否已连接
• getConnectMac：获取当前已连接设备地址
• setBtConnectTimeout：设置连接超时时间
• setBtAutoConnectTime：设置自动连接间隔
• cancelAutoConnectBt：取消自动重连

iOS 专属连接恢复

• 本小节两个方法只有 iOS 可以调用，其他平台都不支持。

• getConnectedDevicesWithServices：按服务 UUID 获取系统当前已连接设备

• redictToConnect：接管 getConnectedDevicesWithServices 返回的已连接设备

服务与特征值

• scanServices：扫描当前连接设备的服务与特征值
• getUUIDs：获取自动识别出的可用 service + notify + write 组合
• setSelectUUID：切换当前使用的 UUID 组合
• getSericUUID：获取当前服务 UUID，旧命名，兼容保留
• getServiceUUID：获取当前服务 UUID
• getNotityUUID：获取当前通知 UUID
• getWriteUUID：获取当前写入 UUID
• getwriteUUID：获取当前写入 UUID，旧命名，兼容保留

数据通信

• onNotityBleData：开启或关闭通知订阅
• onIndicate：开启 indicate 订阅并监听设备主动上报数据
• onReadData：主动读取蓝牙数据
• sendData：写入数据，支持字符串、数组、ArrayBuffer
• readRssi：读取 RSSI
• setMtu：设置 MTU，仅 Android 有效
• setPhy2MMode：设置 Android PHY 2M 模式，仅 Android 有效

调试与线程

• setDebugMode：打开调试日志
• setThreadTypeName：设置回调线程名

方法说明与调用示例

本节按方法逐个列出用途、参数、返回值与调用示例，并同时给出 uni-app x 与 uni-app 参考写法。

isEnabled

• 用途：检测当前系统蓝牙是否处于开启状态。
• 参数：无。
• 返回：boolean。
• 常见场景：进入页面后先判断是否需要提示用户开蓝牙。
• uni-app x / uni-app

var open = lib.isEnabled()
console.log(open)

openBtBluetooth

• 用途：初始化蓝牙适配器，并触发回调告知初始化结果。
• 参数：callback。
• 返回：无，结果通过回调返回。
• iOS 说明：iOS 端该方法主要用于初始化和检查蓝牙状态，不会像 Android 一样主动打开系统蓝牙。
• iOS 回调说明：type=0 表示蓝牙已开启，type=10002 表示系统蓝牙未开启，type=10003 表示蓝牙权限被拒绝、受限或待确认。
• 常见场景：扫描和连接前先调用一次。
• uni-app x

lib.openBtBluetooth(function(res:MyApiResult){
  // type 为0 表示初始化成功  其它值可结合 message 查看失败原因
  console.log(res)
})

• uni-app

lib.openBtBluetooth(function(res){
  // type 为0 表示初始化成功  其它值可结合 message 查看失败原因
  console.log(res)
})

openBluetooth

• 用途：按布尔值控制打开或关闭蓝牙。
• 参数：on:boolean。
• 返回：无。
• 常见场景：Android 或小程序场景下快捷控制蓝牙状态。
• uni-app x / uni-app

lib.openBluetooth(true)
lib.openBluetooth(false)

openBluetoothSettings

• 用途：跳转到系统蓝牙相关设置页。
• 参数：无。
• 返回：无。
• iOS 说明：iOS 端会跳转到当前应用的系统设置页，适合在用户拒绝蓝牙权限后引导其手动开启。
• 常见场景：蓝牙关闭且需要引导用户手动开启时使用。
• uni-app x / uni-app

lib.openBluetoothSettings()

• 推荐搭配 openBtBluetooth 使用

lib.openBtBluetooth(function(res){
  if(res.type == 10003){
    // iOS 用户拒绝蓝牙权限后，可引导用户跳转系统设置手动开启
    lib.openBluetoothSettings()
  }
})

onBtOpenStateListener

• 用途：监听系统蓝牙开关状态变化。
• 参数：callback。
• 返回：无，结果通过回调返回。
• 常见场景：页面常驻监听蓝牙状态变化。
• uni-app x

lib.onBtOpenStateListener(function(res:MyApiResult){
  // data 为 true 表示蓝牙开启 false 表示蓝牙关闭
  console.log(res)
})

• uni-app

lib.onBtOpenStateListener(function(res){
  // data 为 true 表示蓝牙开启 false 表示蓝牙关闭
  console.log(res)
})

onStartScanBle

• 用途：新版 BLE 扫描接口，支持过滤条件与扫描完成回调。
• 参数：ScanPara。
• 返回：无，扫描结果通过 onScanResult 返回。
• 常见场景：绝大多数新项目建议优先使用该接口。
• 补充说明：如需按服务 UUID 过滤扫描结果，可通过 iosFilterUUIDs 传入 UUID 数组，当前支持 iOS、Android、鸿蒙、微信小程序。
• uni-app x

let scanPara:ScanPara = {
  scantime:10 * 1000,
  showEmptyName:0,
  btNameFilter:"",
  onScanResult:function(res:MyApiResult){
    // type 为0 扫描成功  10001 表示无蓝牙权限 10002 表示蓝牙未开启
    if(res.type == 0){
      let scan = res.data as BleScanResult
      console.log(scan)
    }
  },
  scanComplate:function(){
    console.log("scan complete")
  }
} as ScanPara
lib.onStartScanBle(scanPara)

• uni-app

lib.onStartScanBle({
  scantime:10 * 1000,
  showEmptyName:0,
  btNameFilter:"",
  onScanResult:function(res){
    // type 为0 扫描成功  10001 表示无蓝牙权限 10002 表示蓝牙未开启
    if(res.type == 0){
      var scan = res.data
      console.log(scan)
    }
  },
  scanComplate:function(){
    console.log("scan complete")
  }
})

startScanBleDevice

• 用途：旧版扫描接口，保留给旧项目兼容使用。
• 参数：扫描时长、回调函数。
• 返回：无，结果通过回调返回。
• 常见场景：已有老代码迁移成本较高时继续使用。
• uni-app x

lib.startScanBleDevice(15000,function(res:MyApiResult){
  // type 为0 扫描成功  10001 表示无蓝牙权限 10002 表示蓝牙未开启
  if(res.type == 0){
    let scan = res.data as BleScanResult
    console.log(scan)
  }
})

• uni-app

lib.startScanBleDevice(15000,function(res){
  // type 为0 扫描成功  10001 表示无蓝牙权限 10002 表示蓝牙未开启
  if(res.type == 0){
    var scan = res.data
    console.log(scan)
  }
})

onScanDataListener

• 用途：实时监听扫描过程中的广播变化与 RSSI 数据。
• 参数：callback。
• 返回：无，数据通过回调返回。
• 常见场景：需要显示信号强度变化或原始广播数据。
• uni-app x

lib.onScanDataListener(function(res:MyApiResult){
  let data = res.data as ScanRssiBR
  console.log(data)
})

• uni-app

lib.onScanDataListener(function(res){
  console.log(res)
})

stopScanBle

• 用途：停止当前 BLE 扫描。
• 参数：无。
• 返回：无。
• 常见场景：页面离开、用户手动停止扫描、连接前停止扫描。
• uni-app x / uni-app

lib.stopScanBle()

connect

• 用途：连接指定蓝牙设备。
• 参数：设备地址、是否自动连接、回调函数。
• 返回：无，结果通过回调返回。
• 回调 type 说明：0 成功，10000 蓝牙连接失败，10001 蓝牙异常断开，10002 表示蓝牙未开启，10003 表示无蓝牙权限，10004 表示蓝牙已经连接，10005 表示鸿蒙虚拟蓝牙地址无效。
• 常见场景：用户点击扫描结果后发起连接。
• iOS 说明：若你希望控制应用退到后台后，连接成功、连接断开、收到通知时系统是否弹出唤回应用提示，请在 connect 前先调用 setIOSConnectNotifyAlertEnabled。
• uni-app x

lib.connect(device.device.address,false,function(res:MyApiResult){
  console.log(res)
  // type  0  成功  10000 蓝牙连接失败 10001 蓝牙异常断开  10002 表示蓝牙未开启  10003表示无蓝牙权限  10004 表示蓝牙已经连接 10005  鸿蒙虚拟蓝牙地址无效
  if(res.type == 0){

  }else{

  }
})

getConnectedDevicesWithServices

• 用途：按服务 UUID 查询 iOS 系统当前已经连接的 BLE 外设。
• 参数：string[]，传入目标设备对应的服务 UUID 数组。
• 返回：MyApiResult，data 为 BleScanResult[]。
• 平台说明：只有 iOS 可以调用；Android、鸿蒙、微信小程序、Web 都不支持该方法。
• 返回说明：返回结果中的 device.address 为 iOS 外设标识 identifier.uuidString，后续需要原样传给 redictToConnect。
• 常见场景：App 重启后恢复已连接设备、需要接管系统层已保持连接的外设。
• uni-app x / uni-app（仅 iOS）

var serviceIds = ["FFF0"]
var res = lib.getConnectedDevicesWithServices(serviceIds)
console.log(res)

if(res.type == 0){
  var list = res.data || []
  if(list.length > 0){
    console.log(list[0].device.address)
  }
}

redictToConnect

• 用途：把 getConnectedDevicesWithServices 查到的已连接 iOS 外设接管到当前 BleLib 实例。
• 参数：设备地址、回调函数。
• 返回：无，结果通过回调返回。
• 平台说明：只有 iOS 可以调用；Android、鸿蒙、微信小程序、Web 都不支持该方法。
• 调用前提：必须先调用 getConnectedDevicesWithServices，并使用其返回结果中的 device.address 作为第一个参数。
• 回调 type 说明：0 表示接管成功，10001 表示设备已断开。
• 常见场景：业务层拿到系统已连接设备后，继续调用 scanServices、onNotityBleData、sendData 等插件能力。
• uni-app x / uni-app（仅 iOS）

var res = lib.getConnectedDevicesWithServices(["FFF0"])
if(res.type == 0){
  var list = res.data || []
  if(list.length > 0){
    var deviceId = list[0].device.address
    lib.redictToConnect(deviceId,function(connectRes){
      console.log(connectRes)
      if(connectRes.type == 0){
        lib.scanServices(function(serviceRes){
          console.log(serviceRes)
        })
      }
    })
  }
}

setIOSConnectNotifyAlertEnabled

• 用途：控制 iOS 端在应用进入后台后，连接成功、连接断开、收到通知时系统是否显示唤回应用提示。
• 参数：enabled:boolean。
• 返回：无。
• 默认值：true，即默认允许系统显示相关提示。
• 生效时机：必须在 connect 前调用；连接发起后再修改，不影响当前这次连接。
• 平台说明：仅 iOS 生效，Android、鸿蒙、微信小程序为空实现，用于保持多端调用一致。
• uni-app x / uni-app

lib.setIOSConnectNotifyAlertEnabled(false)
lib.connect(device.device.address,false,function(res){
  console.log(res)
})

• uni-app

lib.connect(device.device.address,false,function(res){
  console.log(res)
  // type  0  成功  10000 蓝牙连接失败 10001 蓝牙异常断开  10002 表示蓝牙未开启  10003表示无蓝牙权限  10004 表示蓝牙已经连接 10005  鸿蒙虚拟蓝牙地址无效
  if(res.type == 0){

  }else{

  }
})

close

• 用途：断开当前蓝牙连接并释放连接状态。
• 参数：无。
• 返回：无。
• 常见场景：页面卸载、切换设备、手动断开。
• uni-app x / uni-app

lib.close()

isConnected

• 用途：判断当前对象是否已连接蓝牙设备。
• 参数：无。
• 返回：boolean。
• 常见场景：发送、读取、订阅前做前置判断。
• uni-app x / uni-app

var isconnect = lib.isConnected()
console.log(isconnect)

getConnectMac

• 用途：获取当前已连接设备地址。
• 参数：无。
• 返回：设备地址字符串，未连接时通常为空字符串。
• 常见场景：业务层记录当前连接目标。
• uni-app x / uni-app

var deviceId = lib.getConnectMac()
console.log(deviceId)

setBtConnectTimeout

• 用途：设置蓝牙连接超时时间。
• 参数：超时时间，单位毫秒。
• 返回：无。
• 常见场景：外设连接较慢，需要调整默认超时值。
• uni-app x / uni-app

lib.setBtConnectTimeout(12000)

setBtAutoConnectTime

• 用途：设置自动重连的时间间隔。
• 参数：时间间隔，单位毫秒。
• 返回：无。
• 常见场景：需要控制自动连接重试节奏时使用。
• uni-app x / uni-app

lib.setBtAutoConnectTime(12000)

cancelAutoConnectBt

• 用途：取消自动重连。
• 参数：无。
• 返回：无。
• 常见场景：用户主动退出当前连接流程。
• uni-app x / uni-app

lib.cancelAutoConnectBt()

scanServices

• 用途：扫描当前连接设备的服务与特征值。
• 参数：回调函数。
• 返回：无，服务列表通过回调返回。
• 常见场景：连接成功后必须执行一次，供后续通知与写入使用。
• uni-app x

lib.scanServices(function(resSevice:MyApiResult){
  console.log(resSevice)
  if(resSevice.type == 0){
    let d = resSevice.data as BleServices[]
    console.log(d)
  }
})

• uni-app

lib.scanServices(function(resSevice){
  console.log(resSevice)
})

getUUIDs

• 用途：获取插件自动识别出的可用 service + notify + write 组合列表。
• 参数：无。
• 返回：WNuuid[]。
• 常见场景：设备存在多个服务组合时供业务层选择。
• uni-app x / uni-app

var uuids = lib.getUUIDs()
console.log(uuids)

setSelectUUID

• 用途：切换当前使用的 UUID 组合。
• 参数：组合下标。
• 返回：无。
• 常见场景：自动识别到多组候选服务时手动切换。
• uni-app x / uni-app

lib.setSelectUUID(0)

getSericUUID

• 用途：获取当前选中的服务 UUID，旧命名接口。
• 参数：无。
• 返回：string。
• 常见场景：兼容旧项目代码。
• uni-app x / uni-app

console.log(lib.getSericUUID())

getServiceUUID

• 用途：获取当前选中的服务 UUID。
• 参数：无。
• 返回：string。
• 常见场景：写入、订阅、主动读取前获取服务 UUID。
• uni-app x / uni-app

console.log(lib.getServiceUUID())

getNotityUUID

• 用途：获取当前选中的通知特征 UUID。
• 参数：无。
• 返回：string。
• 常见场景：开启通知前读取当前通知 UUID。
• uni-app x / uni-app

console.log(lib.getNotityUUID())

getWriteUUID

• 用途：获取当前选中的写入特征 UUID。
• 参数：无。
• 返回：string。
• 常见场景：发送数据前获取写入 UUID。
• uni-app x / uni-app

console.log(lib.getWriteUUID())

getwriteUUID

• 用途：获取当前选中的写入特征 UUID，旧命名接口。
• 参数：无。
• 返回：string。
• 常见场景：兼容旧项目代码。
• uni-app x / uni-app

console.log(lib.getwriteUUID())

onNotityBleData

• 用途：开启或关闭通知订阅，并监听设备主动上报数据。
• 参数：服务 UUID、通知 UUID、开关状态、回调函数。
• 返回：无，订阅状态与通知数据通过回调返回。
• 常见场景：连接成功并完成服务扫描后开启通知。
• uni-app x

lib.onNotityBleData(
  lib.getSericUUID(),
  lib.getNotityUUID(),
  true,
  function(res:MyApiResult){
    // type 为0 表示通知数据  1000 表示订阅成功  1001 表示订阅失败
    if(res.type == 0){
      let data = res.data as NotityData
      console.log(data)
    }
  }
)

onIndicate

• 用途：开启 indicate 订阅，并监听设备主动上报的 indicate 数据。
• 参数：服务 UUID、indicate 特征 UUID、回调函数。
• 返回：无，订阅状态与 indicate 数据通过回调返回。
• 常见场景：设备特征值属性为 INDICATE，需要带确认机制的数据上报时使用。
• 平台说明：Android、iOS、鸿蒙已支持真实 indicate 订阅；微信小程序端当前未实现该接口。
• uni-app x

lib.onIndicate(
  "serviceUUID",
  "indicateUUID",
  function(res:MyApiResult){
    // type 为0 表示 indicate 数据  1000 表示订阅成功  1001 表示订阅失败
    if(res.type == 0){
      let data = res.data as NotityData
      console.log(data)
    }
  }
)

• uni-app

lib.onIndicate(
  "serviceUUID",
  "indicateUUID",
  function(res){
    // type 为0 表示 indicate 数据  1000 表示订阅成功  1001 表示订阅失败
    console.log(res)
  }
)

• uni-app

lib.onNotityBleData(
  lib.getSericUUID(),
  lib.getNotityUUID(),
  true,
  function(res){
    // type 为0 表示通知数据  1000 表示订阅成功  1001 表示订阅失败
    console.log(res)
  }
)

onReadData

• 用途：主动读取某个特征值的数据。
• 参数：服务 UUID、读取 UUID、回调函数。
• 返回：无，读取结果通过回调返回。
• 常见场景：设备不主动通知，需要业务端手动拉取数据。
• uni-app x

lib.onReadData("sericeUUID","readUUID",function(res:MyApiResult){
  console.log(res)
})

• uni-app

lib.onReadData("sericeUUID","readUUID",function(res){
  console.log(res)
})

sendData

• 用途：向指定特征值写入数据。
• 参数：WriteData、回调函数。
• 返回：无，写入结果通过回调返回。
• 常见场景：发送控制指令、配置参数、透传数据。
• uni-app x 发送 16 进制字符串

let writeData:WriteData = {
  serviceId:lib.getServiceUUID(),
  characteristicId:lib.getwriteUUID(),
  fenbao:false,
  hexStrData:"FF001122"
}
lib.sendData(writeData,function(res:MyApiResult){
  // 发送结果可结合 type 和 message 判断是否成功
  console.log(res)
})

• uni-app 发送 16 进制字符串

lib.sendData({
  serviceId:lib.getServiceUUID(),
  characteristicId:lib.getwriteUUID(),
  fenbao:false,
  hexStrData:"FF001122"
},function(res){
  console.log(res)
})

• uni-app x 发送字节数组

let writeBytes:WriteData = {
  serviceId:lib.getServiceUUID(),
  characteristicId:lib.getwriteUUID(),
  fenbao:false,
  data:[0xff,0x00,0x11,0x22] as number[]
}
lib.sendData(writeBytes,function(res:MyApiResult){
  // 发送结果可结合 type 和 message 判断是否成功
  console.log(res)
})

• uni-app 发送字节数组

lib.sendData({
  serviceId:lib.getServiceUUID(),
  characteristicId:lib.getwriteUUID(),
  fenbao:false,
  data:[0xff,0x00,0x11,0x22]
},function(res){
  console.log(res)
})

• uni-app x 发送 ArrayBuffer

let buffer = new ArrayBuffer(4)
let view = new Uint8Array(buffer)
view[0] = 0xff
view[1] = 0x00
view[2] = 0x11
view[3] = 0x22
let writeBuffer:WriteData = {
  serviceId:lib.getServiceUUID(),
  characteristicId:lib.getwriteUUID(),
  fenbao:false,
  buffer:buffer
}
lib.sendData(writeBuffer,function(res:MyApiResult){
  console.log(res)
})

readRssi

• 用途：读取当前连接设备的 RSSI 信号强度。
• 参数：回调函数。
• 返回：无，读取结果通过回调返回。
• 常见场景：显示连接质量或调试信号强度。
• uni-app x

lib.readRssi(function(res:MyApiResult){
  console.log(res)
})

• uni-app

lib.readRssi(function(res){
  console.log(res)
})

setMtu

• 用途：设置 BLE 连接的 MTU。
• 参数：MTU 值、回调函数。
• 返回：无，设置结果通过回调返回。
• 常见场景：需要发送较大数据包时在 Android 端提高 MTU。
• uni-app x

lib.setMtu(512,function(res:MyApiResult){
  console.log(res)
})

• uni-app

lib.setMtu(512,function(res){
  console.log(res)
})

setPhy2MMode

• 用途：切换 Android BLE PHY 2M 模式。
• 参数：无。
• 返回：无。
• 常见场景：Android 设备支持高物理层速率时启用。
• uni-app x / uni-app

lib.setPhy2MMode()

setDebugMode

• 用途：打开或关闭插件内部调试日志。
• 参数：debug:boolean。
• 返回：无。
• 常见场景：联调阶段查看内部扫描、连接、通知过程。
• uni-app x / uni-app

lib.setDebugMode(true)
lib.setDebugMode(false)

setThreadTypeName

• 用途：设置插件回调线程名。
• 参数：线程名字符串。
• 返回：无。
• 常见场景：需要和现有线程调度策略保持一致时使用。
• uni-app x / uni-app

lib.setThreadTypeName("main")

常用返回码

不同接口返回码略有差异，常见约定如下：

说明：不同平台和不同接口对错误码的语义可能略有差异，建议结合 message 一起判断。

平台注意事项

Android

• 运行原生 BLE 能力建议使用自定义基座。
• setMtu 与 setPhy2MMode 为 Android 特有能力。
• Android 12 及以上系统请注意蓝牙权限授权。
• Android 端支持通过 iosFilterUUIDs 按服务 UUID 过滤扫描。
• Android 端现已支持真实 onIndicate 订阅与数据回调。

iOS

• 仅支持 iOS 13 及以上。
• iOS 扫描在部分系统版本下建议配合 iosFilterUUIDs 使用。
• 多连接与多通知场景已做兼容，但仍建议每个连接使用独立实例。
• 若应用进入后台后不希望系统在连接、断开、通知事件发生时弹出唤回应用提示，可在连接前调用 setIOSConnectNotifyAlertEnabled(false)。
• 该开关底层对应 iOS 连接参数中的 CBConnectPeripheralOptionNotifyOnConnectionKey、CBConnectPeripheralOptionNotifyOnDisconnectionKey、CBConnectPeripheralOptionNotifyOnNotificationKey。
• iOS 端现已支持真实 onIndicate 订阅与数据回调。
• getConnectedDevicesWithServices 与 redictToConnect 只有 iOS 可以调用，Android、鸿蒙、微信小程序、Web 都不支持；推荐按“先查已连接设备，再传 device.address 接管连接”的顺序调用。

鸿蒙

• 部分虚拟蓝牙地址场景可能返回特定错误码。
• 建议在真机环境验证扫描、连接、RSSI 与发送流程。
• 鸿蒙端支持通过 iosFilterUUIDs 按服务 UUID 过滤扫描。
• 鸿蒙端现已支持真实 onIndicate 订阅与数据回调。

微信小程序

• 需在微信小程序蓝牙权限与机型能力允许的前提下运行。
• 建议一个 BleLib 实例绑定一个设备连接。
• 支持多对象多蓝牙连接。
• 微信小程序端支持通过 iosFilterUUIDs 按服务 UUID 过滤扫描。

示例入口

• App.uvue：基础单连接示例
• pages/Multi/Multi.uvue：多连接、UUID 选择、通知与发送示例

如果你需要查看完整调用方式，优先参考项目内这两个页面的实际示例。

旧接口说明

历史接口与旧版示例已保留在 old.md 中，主要用于兼容旧项目：

• onNotityReadBleData
• writeDataToBle
• writeDataToBleWithType
• writeStringDataToBle

新项目建议优先使用：

• onNotityBleData
• sendData
• getServiceUUID
• getWriteUUID

更新记录

版本变更请查看 changelog.md。