更新记录

1.1.0（2026-08-07） 下载此版本

• 示例项目切换为 Vue3，满足 HBuilderX HarmonyOS NEXT 编译要求。
• BleScanOptions 新增 duration 字段，兼容旧示例中使用的扫描时长参数。
• 更新 package.json 平台兼容信息，仅将 app-harmony 标记为已支持，Android / iOS 标记为未验证。
• Android / iOS 入口改为明确 unsupported 返回，避免误用为已验证能力。
• 重写 README，补充安装方式、API 文档、HarmonyOS NEXT 权限说明、平台差异、常见问题和发布建议。
• 清理示例项目默认生命周期日志。

1.0.0（2026-07-07） 下载此版本

1.0.0

【新增】

1. 支持 HarmonyOS NEXT BLE 蓝牙核心能力。
2. 支持蓝牙权限申请。
3. 支持 BLE 设备扫描和停止扫描。
4. 支持设备名称关键字过滤。
5. 支持 GATT 设备连接和断开连接。
6. 支持自动发现 Service 和 Characteristic。
7. 支持特征值 HEX 数据写入。
8. 支持特征值读取。
9. 支持 Notify 通知订阅。
10. 支持监听蓝牙设备返回数据。
11. 支持获取 RSSI。
12. 支持设置 MTU。
13. 支持 destroy 释放蓝牙资源。
14. 提供 Vue3 示例组件，方便快速接入。

【优化】

1. 兼容 HarmonyOS NEXT 部分版本 startBLEScan 参数校验严格的问题。
2. 兼容鸿蒙 BLE Notify 开启时参数校验严格的问题。
3. 连接后优先自动识别真实蓝牙服务和特征值，避免写死 UUID。
4. Web/H5 端提供空实现，避免多端编译报错。

【说明】 本插件适用于 uni-app Vue3 / uni-app x 的 HarmonyOS NEXT BLE 蓝牙接入场景，可用于智能硬件、IoT 外设、车载蓝牙设备、蓝牙控制类项目。

平台兼容性

uni-app(5.14)

HarmonyOS NEXT BLE 蓝牙原生插件

sl-harmony-ble 是一个适用于 uni-app 的 HarmonyOS NEXT BLE 低功耗蓝牙 UTS 插件，封装权限申请、设备扫描、GATT 连接、服务发现、特征值读写、Notify 订阅、RSSI、MTU、断开连接和资源释放。

为兼容已上架的 DCloud 插件，插件 ID 继续保持为 sl-harmony-ble。

功能

• 蓝牙权限申请
• 获取蓝牙状态
• BLE 设备扫描、停止扫描、设备发现回调
• GATT 连接与连接状态监听
• 获取 GATT 服务
• 读取特征值
• 写入 HEX 特征值
• 开启 / 关闭 Notify
• 监听 Notify 数据变化
• 获取 RSSI
• 设置 MTU
• 断开连接、关闭 GATT、释放资源

平台

安装

将插件目录放到项目根目录：

uni_modules/sl-harmony-ble

业务代码中引入：

import {
  requestBlePermissions,
  onDeviceFound,
  onConnectionChange,
  onCharacteristicChange,
  startScan,
  stopScan,
  connect,
  getServices,
  enableNotify,
  writeCharacteristic,
  readCharacteristic,
  disconnect,
  destroy
} from '@/uni_modules/sl-harmony-ble'

快速示例

let currentDevice = null

async function searchDevice() {
  const permission = await requestBlePermissions()
  if (!permission.ok) return

  onDeviceFound((device) => {
    currentDevice = device
  })

  await startScan({
    keyword: 'BLE',
    timeoutMs: 10000,
    allowDuplicates: false
  })
}

async function connectDevice() {
  await stopScan()
  await connect({
    deviceId: currentDevice.deviceId,
    timeoutMs: 10000,
    autoGetServices: true
  })
}

async function openNotify(serviceUuid, notifyUuid) {
  onCharacteristicChange((data) => {
    // data.valueHex 为 Notify 收到的 HEX 字符串
  })

  await enableNotify({
    serviceUuid,
    characteristicUuid: notifyUuid,
    enableCccd: true
  })
}

async function sendHex(serviceUuid, writeUuid) {
  await writeCharacteristic({
    serviceUuid,
    characteristicUuid: writeUuid,
    hex: 'AA010203'
  })
}

API

requestBlePermissions()

申请 HarmonyOS NEXT 蓝牙相关权限。

getBluetoothState()

获取系统蓝牙状态。

openBluetooth()

请求打开蓝牙能力。

closeBluetooth()

请求关闭蓝牙能力。

startScan(options)

开始扫描 BLE 设备。

stopScan()

停止扫描，返回已发现设备列表。

onDeviceFound(callback)

监听扫描到的设备。

返回数据：

{
  deviceId: string,
  name: string,
  rssi: number,
  addressType: string,
  advertisDataHex: string,
  serviceUuids: string[]
}

connect(options)

连接 BLE 设备。

getServices()

读取 GATT 服务列表。建议连接后先调用一次，并从真实服务中选择 serviceUuid、writeCharacteristicUuid、notifyCharacteristicUuid。

readCharacteristic(options)

读取特征值。

writeCharacteristic(options)

写入特征值，hex 支持空格、冒号、横杠分隔，例如 AA 01 02 03。

enableNotify(options)

开启 Notify。enableCccd: true 时会尝试写入 2902 描述符。

disableNotify(options)

关闭 Notify。

getRssi()

获取当前连接设备的 RSSI。

setMtu(mtu)

设置 MTU。

disconnect()

断开当前连接。

closeGatt()

断开连接并释放当前 GATT 连接对象。

destroy()

停止扫描、断开连接、清理回调。页面卸载时建议调用。

HarmonyOS NEXT 权限

插件已在 utssdk/app-harmony/module.json5 声明：

ohos.permission.ACCESS_BLUETOOTH
ohos.permission.APPROXIMATELY_LOCATION
ohos.permission.LOCATION

常见问题

扫描不到设备

• 确认设备蓝牙已打开。
• 确认 App 已授予蓝牙和定位权限。
• 尝试不传 serviceUuid，先用 keyword 或空过滤扫描。

enableNotify 失败

通常是 serviceUuid 或 characteristicUuid 不是设备真实 Notify 特征。建议先调用 getServices() 查看真实服务和特征后再开启 Notify。

写入失败

• 确认设备已连接。
• 确认特征支持 write 或 writeNoResponse。
• 尝试切换 writeType: 1。
• 确认写入 HEX 长度不超过当前 MTU 可承载长度。

发布建议

• 插件市场更新时建议保持 id: sl-harmony-ble，避免历史用户升级路径断开。
• 上传前删除项目根目录中的 unpackage 构建产物。
• HarmonyOS NEXT 项目需使用 Vue3。
• Android / iOS 原生 BLE 适配未完成前，不建议在插件市场声明为已支持平台。