Ble低功耗蓝牙uts插件支持安卓ios 鸿蒙微信小程序(2025插件大赛三等奖)

插件 ID: 20243
来源: https://ext.dcloud.net.cn/plugin?id=20243
蓝牙 ble UTS 插件支持安卓ios 鸿蒙微信小程序，蓝牙扫描、蓝牙广播连接多蓝牙、读取数据发送数据，蓝牙状态监听、连接状态、数据写入支持GBK编码格式转换等

更新记录

                                                    1.1.65（2026-06-15）

优化群里反馈的闪退问题

                                                    1.1.64（2026-06-14）

增加Android 鸿蒙微信小程序扫描通过uuid过滤优化鸿蒙onReadData 其它群中反馈问题优化

                                                    1.1.63（2026-05-20）

优化ble连接多连接修复已知问题查看更多

平台兼容性

uni-app(4.07)

| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 | | |

|
|
|
| √ | √ | 5.0 | √ | √ | | | 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 | | | √ |
|
|
|
|
|
|
|
|
|
|
| |

uni-app x(4.07)

|
| 5.0 | √ | √ | √ | |

其他

| 多语言 | 暗黑模式 | 宽屏模式 | | | √ | √ | √ | |

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
支持通知订阅、主动读取、RSSI 读取、MTU 设置
支持十六进制字符串、数字数组、ArrayBuffer 写入
支持分包发送
支持多蓝牙连接场景
支持监听系统蓝牙开关状态

平台支持

| 平台 | 支持情况 | | | uni-app Android | 支持 | | | uni-app iOS | 支持 | | | uni-app 鸿蒙 | 支持 | | | uni-app 微信小程序 | 支持 | | | uni-app x Android | 支持 | | | uni-app x iOS | 支持 | | | uni-app x 鸿蒙 | 支持 | | | uni-app x 微信小程序 | 支持 | | | Web | 不支持 | | 补充说明：

iOS 需 iOS 13 及以上版本。
Android / iOS / 鸿蒙运行原生能力时，建议使用自定义基座验证。
微信小程序端按 BleLib 实例维护连接状态，适合一个对象对应一个蓝牙连接。

安装与运行

插件试用与下载

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

快速上手

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

最短接入步骤

引入 BleLib，创建蓝牙对象实例。
调用 openBtBluetooth 初始化蓝牙适配器。
调用 onStartScanBle 开始扫描设备。
拿到目标设备地址后调用 connect。
连接成功后调用 scanServices。
调用 getUUIDs 查看自动识别出的可用 UUID 组合。
必要时调用 setSelectUUID 切换到目标 service/notify/write 组合。
调用 onNotityBleData 开启通知。
调用 sendData 发送数据。
结束时调用 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)
              })
            }
          })
        }
      })
    }
  }
})

自定义基座

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

iOS 蓝牙权限配置

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

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

说明：

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

主要类型

`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`

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

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

API 清单

适配器与状态

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

扫描相关

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

连接相关

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

服务与特征值

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

数据通信

onNotityBleData：开启或关闭通知订阅
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{
  }
})

`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)
    }
  }
)

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")

常用返回码

不同接口返回码略有差异，常见约定如下： | type | 说明 | | | 0 | 成功 | | | 1000 | 通知订阅成功 | | | 1001 | 通知订阅失败，或部分平台表示蓝牙异常断开 | | | 10000 | 连接失败、读取失败或通用失败 | | | 10001 | 蓝牙异常断开，或部分场景表示无权限 | | | 10002 | 蓝牙未开启 | | | 10003 | 无蓝牙权限 | | | 10004 | 蓝牙已经连接 | | | 10005 | 部分平台用于地址无效或未连接 | | 说明：不同平台和不同接口对错误码的语义可能略有差异，建议结合 message 一起判断。

平台注意事项

Android

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

iOS

仅支持 iOS 13 及以上。
iOS 扫描在部分系统版本下建议配合 iosFilterUUIDs 使用。
多连接与多通知场景已做兼容，但仍建议每个连接使用独立实例。
若应用进入后台后不希望系统在连接、断开、通知事件发生时弹出唤回应用提示，可在连接前调用 setIOSConnectNotifyAlertEnabled(false)。
该开关底层对应 iOS 连接参数中的 CBConnectPeripheralOptionNotifyOnConnectionKey、CBConnectPeripheralOptionNotifyOnDisconnectionKey、CBConnectPeripheralOptionNotifyOnNotificationKey。

鸿蒙

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

微信小程序

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

示例入口

App.uvue：基础单连接示例
pages/Multi/Multi.uvue：多连接、UUID 选择、通知与发送示例如果你需要查看完整调用方式，优先参考项目内这两个页面的实际示例。

旧接口说明

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

onNotityReadBleData
writeDataToBle
writeDataToBleWithType
writeStringDataToBle 新项目建议优先使用：
onNotityBleData
sendData
getServiceUUID
getWriteUUID

更新记录

版本变更请查看 changelog.md。

Ble低功耗蓝牙uts插件 支持安卓ios 鸿蒙 微信小程序(2025插件大赛三等奖) ​

更新记录 ​

​

​

​

平台兼容性 ​

uni-app(4.07) ​

uni-app x(4.07) ​

其他 ​

android-ble ​

功能概览 ​

平台支持 ​

安装与运行 ​

插件试用与下载 ​

快速上手 ​

最短接入步骤 ​

uni-app x 快速上手 ​

uni-app 快速上手 ​

自定义基座 ​

iOS 蓝牙权限配置 ​

推荐调用流程 ​

主要类型 ​

ScanPara ​

WNuuid ​

WriteData ​

MyApiResult ​

NotityData ​

API 清单 ​

适配器与状态 ​

扫描相关 ​

连接相关 ​

服务与特征值 ​

数据通信 ​

调试与线程 ​

方法说明与调用示例 ​

isEnabled ​

openBtBluetooth ​

openBluetooth ​

openBluetoothSettings ​

onBtOpenStateListener ​

onStartScanBle ​

startScanBleDevice ​

onScanDataListener ​

stopScanBle ​

connect ​

setIOSConnectNotifyAlertEnabled ​

close ​

isConnected ​

getConnectMac ​

setBtConnectTimeout ​

setBtAutoConnectTime ​

cancelAutoConnectBt ​

scanServices ​

getUUIDs ​

setSelectUUID ​

getSericUUID ​

getServiceUUID ​

getNotityUUID ​

getWriteUUID ​

getwriteUUID ​

onNotityBleData ​

onReadData ​

sendData ​

readRssi ​

setMtu ​

setPhy2MMode ​

setDebugMode ​

setThreadTypeName ​

常用返回码 ​

平台注意事项 ​

Android ​

iOS ​

鸿蒙 ​

微信小程序 ​

示例入口 ​

旧接口说明 ​

更新记录 ​

Ble低功耗蓝牙uts插件支持安卓ios 鸿蒙微信小程序(2025插件大赛三等奖)

更新记录

平台兼容性

uni-app(4.07)

uni-app x(4.07)

其他

android-ble

功能概览

平台支持

安装与运行

插件试用与下载

快速上手

最短接入步骤

`uni-app x` 快速上手

`uni-app` 快速上手

自定义基座

iOS 蓝牙权限配置

推荐调用流程

主要类型

`ScanPara`

`WNuuid`

`WriteData`

`MyApiResult`

`NotityData`

API 清单

适配器与状态

扫描相关

连接相关

服务与特征值

数据通信

调试与线程

方法说明与调用示例

`isEnabled`

`openBtBluetooth`

`openBluetooth`

`openBluetoothSettings`

`onBtOpenStateListener`

`onStartScanBle`

`startScanBleDevice`

`onScanDataListener`

`stopScanBle`

`connect`

`setIOSConnectNotifyAlertEnabled`

`close`

`isConnected`

`getConnectMac`

`setBtConnectTimeout`

`setBtAutoConnectTime`

`cancelAutoConnectBt`

`scanServices`

`getUUIDs`

`setSelectUUID`

`getSericUUID`

`getServiceUUID`

`getNotityUUID`

`getWriteUUID`

`getwriteUUID`

`onNotityBleData`

`onReadData`

`sendData`

`readRssi`

`setMtu`

`setPhy2MMode`

`setDebugMode`

`setThreadTypeName`

常用返回码

平台注意事项

Android

iOS

鸿蒙

微信小程序

示例入口

旧接口说明

更新记录