更新记录
1.0.0(2026-11-21)
- 正式发布:插件 id 为
acupday-ble - BLE Central,对齐微信 /
uni.*蓝牙 API - 支持 App-Android(Kotlin GATT)、App-iOS(CoreBluetooth)、App-HarmonyOS NEXT(ConnectivityKit)、微信小程序(转调
uni.*) - H5 明确不支持,统一返回
errCode=20001 - 能力:开/关适配器、扫描与过滤、连接/断开、发现服务与特征、Notify/读/写、MTU、RSSI
- 扩展:有限自动重连(
setBLEReconnectOptions/createBLEConnection单次覆盖)、分包写入(chunkSize/chunkInterval) - Android 按场景申请权限(open→CONNECT,scan→SCAN+定位);系统蓝牙关闭时可引导开启
- iOS 插件
info.plist含蓝牙用途说明;setBLEMTU返回10009(系统不支持主动协商) - 鸿蒙声明
ACCESS_BLUETOOTH;开适配器申请权限,关蓝牙时可enableBluetooth()
平台兼容性
uni-app(5.0)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | - | - | √ | √ | √ | √ | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| √ | √ | - | - | - | - | - | - | - | - | - | - |
uni-app x(5.0)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | √ | √ | √ | √ |
acupday-ble
uni-app x BLE Central UTS 插件:对齐微信 / uni.* 蓝牙 API,支持 App-Android / App-iOS / App-HarmonyOS NEXT / 微信小程序。含有限自动重连与分包写入。H5 不支持(统一 errCode=20001)。
本工程示例页:pages/ble/index。
当前版本(1.0.0)
| 平台 | 支持 | 实现要点 |
|---|---|---|
| App Android | ✅ | UTS + Kotlin(BluetoothGatt) |
| App iOS | ✅ | UTS + Swift(CoreBluetooth) |
| App HarmonyOS NEXT | ✅ | UTS → ArkTS(@kit.ConnectivityKit) |
| 微信小程序 | ✅ | 转调 uni.*,叠加分包写 / 重连 |
| H5 / 其它 | ❌ | 20001 |
Android / iOS 须用含本插件的自定义基座;鸿蒙用 HBuilderX + DevEco 本地编译真机验证。
安装
- 将本目录放入项目
uni_modules/acupday-ble - 打 自定义调试基座 / 云打包(含原生代码,标准基座不可用)
- 宿主
manifest建议声明 Android 蓝牙/定位权限;iOS 覆盖NSBluetoothAlwaysUsageDescription等用途说明(插件info.plist已有中文缺省) - 改
BleNative.kt/BleNative.swift/ 插件 Manifest / 鸿蒙module.json5后须重打基座或重新同步原生工程;仅改各端index.uts通常不用
导入
只从插件根导入,禁止深入 utssdk/:
import {
openBluetoothAdapter,
closeBluetoothAdapter,
startBluetoothDevicesDiscovery,
stopBluetoothDevicesDiscovery,
onBluetoothDeviceFound,
offBluetoothDeviceFound,
createBLEConnection,
closeBLEConnection,
getBLEDeviceServices,
getBLEDeviceCharacteristics,
notifyBLECharacteristicValueChange,
readBLECharacteristicValue,
writeBLECharacteristicValue,
setBLEMTU,
getBLEMTU,
setBLEReconnectOptions,
} from '@/uni_modules/acupday-ble'
标准流程(与微信文档一致)
- 先注册
onBluetoothDeviceFound/onBLEConnectionStateChange/onBLECharacteristicValueChange openBluetoothAdapter({ success, fail })startBluetoothDevicesDiscovery(可带services)→ 拿到deviceId→stopBluetoothDevicesDiscoverycreateBLEConnectiongetBLEDeviceServices→getBLEDeviceCharacteristicsnotifyBLECharacteristicValueChange/read/write- 结束:
closeBLEConnection、off*、closeBluetoothAdapter
openBluetoothAdapter({
success: () => {
startBluetoothDevicesDiscovery({
allowDuplicatesKey: false,
success: () => {},
fail: (e) => console.error(e),
})
},
fail: (e) => console.error(e),
})
微信:无服务 UUID 过滤时不要传
services(禁止null/[]),否则可能 fail「no service」;有过滤再传非空数组。
扩展:有限自动重连
全局默认:
setBLEReconnectOptions({
enable: true,
maxAttempts: 3,
interval: 2000,
})
单次连接覆盖:
createBLEConnection({
deviceId,
timeout: 10000,
autoReconnect: true,
maxReconnectAttempts: 3,
reconnectInterval: 2000,
})
断线重连成功后须重新发现服务/特征并按需再开 notify。主动 closeBLEConnection 不会触发重连。
扩展:分包写入
writeBLECharacteristicValue({
deviceId,
serviceId,
characteristicId,
value, // ArrayBuffer
writeType: 'write', // 或 writeNoResponse
chunkSize: 20,
chunkInterval: 20,
})
chunkSize 不传则单次写入;传入后按长度切片串行发送。
MTU
setBLEMTU({
deviceId,
mtu: 512,
success: (res) => {
// res.mtu = 协商后的实际值(可能小于请求值)
},
fail: (e) => console.error(e),
})
getBLEMTU({
deviceId,
success: (res) => console.log(res.mtu),
})
| 平台 | 行为 |
|---|---|
| Android | setBLEMTU 等 onMtuChanged 后再 success,回传实际 mtu |
| iOS | 不支持主动协商,setBLEMTU 返回 10009;可用 getBLEMTU 读估算值 |
| 微信 | 转调 uni.setBLEMTU / uni.getBLEMTU |
UTS 可能对
getBLEMTU/setBLEMTU的 success 强转为GetBLEMTUSuccess等;桥接层必须回传该类型实例,禁止UTSJSONObject(否则 ClassCastException)。
权限(分场景申请)
Android
插件 AndroidManifest.xml 已声明;运行时按场景申请:
| 场景 | 权限 |
|---|---|
| 打开适配器 | BLUETOOTH_CONNECT(Android 12+;低版本无运行时权限) |
| 开始扫描 | BLUETOOTH_SCAN + ACCESS_FINE_LOCATION(Android 12+);低版本仅定位 |
| 连接设备 | BLUETOOTH_CONNECT(Android 12+) |
系统蓝牙关闭时,open 会弹系统「开启蓝牙」对话框(ACTION_REQUEST_ENABLE),用户取消则 10001。
注意: 最终 App 合并清单必须含 BLUETOOTH_CONNECT;宿主 manifest / 原生工程建议同步声明。CONNECT 勿用 tools:node="replace"。
iOS
插件 info.plist 含 NSBluetoothAlwaysUsageDescription / NSBluetoothPeripheralUsageDescription。正式产品请在宿主 manifest 的 privacyDescription 覆盖。
系统蓝牙关闭:open 用 ShowPowerAlertKey 弹系统提示;挂起直到用户开启(success)或仍未开(10001)。
鸿蒙
插件 module.json5 声明 ohos.permission.ACCESS_BLUETOOTH;open 会 requestPermissionsFromUser,关蓝牙时 enableBluetooth()。无过滤扫设备传 startBLEScan(null)(勿传空数组)。
主要错误码
| errCode | 含义 |
|---|---|
| 0 | 成功 |
| 10000 | 未初始化适配器 |
| 10001 | 蓝牙不可用 / 用户未开启 |
| 10002 | 无设备 |
| 10003 | 连接失败 |
| 10004 / 10005 | 无服务 / 无特征 |
| 10006 | 无连接 |
| 10007 | 特征属性不支持 |
| 10008 | 系统错误 |
| 10009 | 系统不支持(如 iOS setMTU) |
| 10012 | 操作超时 |
| 20001 | 平台不支持(H5) |
| 20002 | 分包写入失败 |
| 20003 | 重连次数耗尽 |
完整常量见 utssdk/unierror.uts。
改插件踩坑(摘要)
- Android:禁止
import … from './BleNative.kt',用包名uts.sdk.modules.acupdayBle - Android UTS:禁止
Number(x),用as number - MTU/RSSI success 必须构造
GetBLEMTUSuccess等类型,禁止UTSJSONObject - 异步/多次回调:遵循工程
AGENTS.md(@UTSJS.keepAlive+export function) - 改 Kotlin / Swift / Manifest / 鸿蒙权限资源 → 重打自定义基座或重编鸿蒙工程
示例
宿主示例:pages/ble/index(开适配器、扫描过滤、连接、发现服务/特征、Notify/读/写、MTU)。
路线图
- 示例与市场资料完善
- 上架「权限同步告知」(可选接入
uni-registerRequestPermissionTips) - 按业务需要扩展广播解析、多连接会话管理等

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 7
赞赏 0
下载 12779274
赞赏 1960
赞赏
京公网安备:11010802035340号