更新记录

1.0.2（2026-11-13）

更新适应范围

1.0.1（2026-11-13）

更新使用说明

1.0.0（2026-11-13）

初始化

平台兼容性

uni-app x(4.81)

其他

yk-ble 使用说明

三端 BLE 蓝牙 UTS 插件（Android / iOS / HarmonyOS NEXT），源码混编，支持扫描、连接、服务/特征发现、读写、notify/indicate 订阅、MTU 协商与批量写入。

要求：HBuilderX ^4.66，uni-app x ^4.81。

1. 安装

把 uni_modules/yk-ble 整个目录放到你工程的 uni_modules/ 下，保持目录名不变，然后重新「运行到手机」。

import * as POC from '@/uni_modules/yk-ble'

import 路径以 uni_modules 下的实际目录名为准。

2. 权限配置

2.1 Android

插件已自带 utssdk/app-android/AndroidManifest.xml，声明了：

• Android 12+：BLUETOOTH_SCAN（neverForLocation）/ BLUETOOTH_CONNECT
• Android 11 及以下：BLUETOOTH / BLUETOOTH_ADMIN / 定位权限

注意：标准基座不会合并插件内的 Manifest 权限。若真机扫描无反应，在主工程 manifest.json 的 app-plus.distribute.android.permissions 里补上同样权限，或制作一次自定义调试基座。运行时权限由插件自动申请。

2.2 iOS

插件已自带 utssdk/app-ios/Info.plist（NSBluetoothAlwaysUsageDescription）与 CoreBluetooth.framework 引用，正常自定义基座/正式打包会合并，无需额外配置。

2.3 HarmonyOS

权限必须写在主工程 harmony-configs/entry/src/main/module.json5（HBuilderX 每次运行都会重新生成鸿蒙工程，插件内的 module.json5 不会进最终 entry）：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  },
  {
    "name": "ohos.permission.ACCESS_BLUETOOTH",
    "reason": "$string:bluetooth_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

并在 resources/base/element/string.json 提供 reason 文案：

{ "name": "bluetooth_reason", "value": "用于扫描和连接蓝牙打印机、电子秤" }

要点：

• 只需 ACCESS_BLUETOOTH，不要加 DISCOVER_BLUETOOTH（受限权限）和定位权限（鸿蒙 BLE 扫描不需要）。
• ACCESS_BLUETOOTH 是运行时权限，插件会在 openBluetoothAdapter 时自动弹窗申请；也可手动调 requestBluetoothPermission 命令。
• 部分机型要求系统「位置信息」开关处于打开状态（属于系统开关，不是权限）。

3. 快速开始

import * as POC from '@/uni_modules/yk-ble'

// 1. 注册事件（设备发现、连接状态、数据上报）
POC.onEvent((json : string) => {
  const ev = JSON.parse(json)
  if (ev.type === 'deviceFound') {
    console.log('发现设备', ev.devices)
  } else if (ev.type === 'characteristicValue') {
    console.log('收到数据', ev.hex, '来源', ev.source)
  }
})

// 2. 初始化并扫描
POC.call('openBluetoothAdapter', '{}', (json : string) => {
  const r = JSON.parse(json)
  if (!r.ok) { console.log('初始化失败', r.errMsg); return }
  POC.call('startBluetoothDevicesDiscovery', '{"services":[]}', (json : string) => {})
})

// 3. 查询插件信息（同步）
console.log(POC.getInfo())   // {"platform":"android|ios|harmony","version":"...","native":true}

// 4. 页面销毁时解注册
// POC.offEvent()

典型调用顺序：

openBluetoothAdapter
  → startBluetoothDevicesDiscovery   （onEvent 收 deviceFound）
  → stopBluetoothDevicesDiscovery
  → createBLEConnection              （onEvent 收 connectionState）
  → getBLEDeviceServices
  → getBLEDeviceCharacteristics
  → notifyBLECharacteristicValueChange / readBLECharacteristicValue / writeBLECharacteristicValue
  → closeBLEConnection → closeBluetoothAdapter

4. API

插件只导出 4 个方法，参数与结果全部是 JSON 字符串。

结果格式：

{ "ok": true, ...附加字段 }
{ "ok": false, "errCode": 10001, "errMsg": "..." }

事件格式：

{ "type": "deviceFound", ...事件字段 }

4.1 命令表

params 为 JSON 字符串，无参数传 "{}"。UUID 支持 4 / 8 / 36 位写法。

4.2 事件表

另有 permission / scanDiagnostics / scanStarted / scanFailed / serviceDiscovery 等诊断事件，仅用于排障，业务可忽略。

4.3 错误码表

errMsg 中可能附带系统错误码：鸿蒙 201（权限）、401（参数非法）、2900099（GATT 忙）、2901008（服务树为空）；Android GATT 133 / 8 / 22。

5. 数据格式约定

• 写数据用 hex 字符串（大写、无分隔符）：1B40 = ESC @。
• writeType：write（默认，有响应）/ writeNoResponse（无响应，部分透传模块只支持这种）。
• batchWrite 的 chunks 是已分好包的 hex 数组，原生层串行发送，每包间隔 interval 毫秒。
• characteristicValue 事件的 source 标识数据来源：read / notify。
• 所有 UUID 支持短写法，如 FFE0、0000ffe0、0000ffe0-0000-1000-8000-00805f9b34fb 均可。

6. 使用注意

1. 只支持 BLE，不支持 SPP 经典蓝牙（部分老款打印机是 SPP，搜不到属正常）。
2. GATT 操作不要并行：连接、发现服务、读、写、订阅一次只做一件，尤其鸿蒙。
3. MTU 协商放在服务发现之后，并按 20 字节分包更稳妥（部分模块协商后仍只收 20 字节）。
4. 改过 .kt / .swift / .ets 后，必须把 package.json 的 version 加 1，否则 HBuilderX 跳过原生编译，真机跑的是旧代码。
5. 页面/应用销毁时调 closeBLEConnection、closeBluetoothAdapter 并 offEvent()。