文档模板：v0.4.2

react-native-ble-manager

本项目基于 react-native-ble-manager 开发。

该第三方库的仓库已迁移至 GitCode，并支持直接从 npm 下载。新的包名为：@react-native-ohos/react-native-ble-manager。版本对应关系如下：

简介

react-native-ble-manager 是一个用于 React Native 的蓝牙低功耗（BLE）通信管理库。
支持扫描、连接外围设备，获取外围设备的服务与特征，以及特征的读取、写入、开启通知等操作。

下载安装

对于未发布到 npm 的旧版本，请参考安装指南安装 tgz 包。

进入工程目录，并输入以下命令：

npm

npm install @react-native-ohos/react-native-ble-manager

yarn

yarn add @react-native-ohos/react-native-ble-manager

链接

使用 AutoLink 的工程需根据该文档进行配置，Autolink 框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如果您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过 ManualLink 配置。

{
  "overrides": {
    "@rnoh/react-native-openharmony": "~0.82.18" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@react-native-ohos/react-native-ble-manager": "file:../../node_modules/@react-native-ohos/react-native-ble-manager/harmony/ble_manager.har",
  }

cd entry
ohpm install

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-ble-manager/src/main/cpp" ./rnoh_ble_manager)


# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_ble_manager)
# RNOH_END: manual_package_linking_2

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
#include "SamplePackage.h"
+ #include "BleManagerPackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
      std::make_shared<RNOHGeneratedPackage>(ctx),
      std::make_shared<SamplePackage>(ctx),
+     std::make_shared<BleManagerPackage>(ctx)
    };
}

  ...
+ import { BlePackage } from '@react-native-ohos/react-native-ble-manager/ts';


export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new SamplePackage(ctx),
+    new BlePackage(ctx)
  ];
}

运行

点击右上角的 sync 按钮

或在终端中执行：

cd entry
ohpm install

随后编译并运行即可。

约束与限制

兼容性

本文档内容已在以下版本中验证通过：

1. RNOH：0.82.18; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.120 SP7;

权限要求

• 由于本库涉及蓝牙系统控制功能，调用相应接口时需要配置相应权限，权限应配置在entry/src/main目录下module.json5文件中。其中部分权限需要弹窗向用户申请授权。具体权限配置请参见文档：程序访问控制。

• 本库的部分功能和接口需要normal权限：ohos.permission.ACCESS_BLUETOOTH。

编译与运行的 API 要求

使用示例

import BleManager from 'react-native-ble-manager';

async function demo(peripheralId: string, serviceUUID: string, characteristicUUID: string) {
  await BleManager.start();

  const discoverListener = BleManager.addListener(
    'BleManagerDiscoverPeripheral',
    (peripheral) => {
      console.log('发现设备:', peripheral.id, peripheral.name);
    },
  );

  await BleManager.scan([serviceUUID], 5, true);

  await BleManager.connect(peripheralId);
  await BleManager.retrieveServices(peripheralId);
  const value = await BleManager.read(peripheralId, serviceUUID, characteristicUUID);
  console.log('read:', value);
  await BleManager.write(peripheralId, serviceUUID, characteristicUUID, [1]);

  await BleManager.startNotification(peripheralId, serviceUUID, characteristicUUID);

  await BleManager.disconnect(peripheralId);
  discoverListener.remove();
}

使用说明

初始化

调用其他接口前，请先调用 start 初始化蓝牙管理器：

import ReactNativeBleManager from 'react-native-ble-manager';
ReactNativeBleManager.start();

事件监听

import { NativeEventEmitter, NativeModules } from 'react-native';
import ReactNativeBleManager from 'react-native-ble-manager';

const BleManagerModule = NativeModules.BleManager;
const bleManagerEmitter = new NativeEventEmitter(BleManagerModule);

// 监听扫描到的外围设备
const discoverListener = bleManagerEmitter.addListener(
    'BleManagerDiscoverPeripheral',
    (peripheral) => {
        console.log('发现设备：', peripheral.id, peripheral.name);
    }
);

// 监听通知数据（需先调用 startNotification 开启通知）
const notifyListener = bleManagerEmitter.addListener(
    'BleManagerDidUpdateValueForCharacteristic',
    ({ peripheral, characteristic, value }) => {
        console.log('收到通知：', peripheral.id, characteristic, value);
    }
);

// 不再使用时移除监听，避免内存泄漏
discoverListener.remove();
notifyListener.remove();

扫描设备

// 扫描指定服务的外围设备（参数：服务 UUID 列表、扫描时长（秒）、是否记录重复设备）
ReactNativeBleManager.scan(['00001888-0000-1000-8000-00805F9B34FB'], 0, true).then(() => {
    // 扫描结果通过 BleManagerDiscoverPeripheral 事件返回
});

// 停止扫描
ReactNativeBleManager.stopScan();

连接与数据交互

// 连接设备
await ReactNativeBleManager.connect(peripheralId);

// 获取设备的服务与特征列表
const peripheralInfo = await ReactNativeBleManager.retrieveServices(peripheralId);

// 读取特征值
const readData = await ReactNativeBleManager.read(peripheralId, serviceUUID, characteristicUUID);

// 写入特征值
await ReactNativeBleManager.write(peripheralId, serviceUUID, characteristicUUID, [1]);

// 开启特征值通知，数据变化时通过 BleManagerDidUpdateValueForCharacteristic 事件返回
await ReactNativeBleManager.startNotification(peripheralId, serviceUUID, characteristicUUID);

// 断开连接
await ReactNativeBleManager.disconnect(peripheralId);

接口说明

API

遗留问题

• refreshCache 用于清理并刷新蓝牙设备缓存的一部分 issue#3
• requestConnectionPriority 用于请求蓝牙连接优先级 issue#4
• startNotificationWithBuffer 用于启动带缓冲区的通知服务 issue#6
• companionScan 扫描配套设备issue#5
• getAssociatedPeripherals 检索相关外围设备（来自配套管理器） issue#7
• removeAssociatedPeripheral 移除相关外围设备 issue#8
• setName 创建并设置蓝牙适配器名称 issue#9
• supportsCompanion 检查当前设备是否支持配套设备管理器 issue#10
• stopNotification 停止指定特征值的更新通知 issue#11
• writeWithoutResponse 向指定特征值执行无响应写入 issue#12
• removeBond 移除已配对设备 issue#13
• getMaximumWriteValueLengthForWithoutResponse 获取无响应写入支持的最大数据长度 issue#14
• getMaximumWriteValueLengthForWithResponse 获取带响应写入支持的最大数据长度 issue#15

其他

无

目录结构

/rntpc_react-native-ble-manager  # 项目根目录
├── harmony                        # 鸿蒙适配代码
│    ├─ ble_manager.har            # har包
│    ├─ ble_managerGatt.har        # GATT har包
│    ├─ ble_managerServers.har     # Servers har包
│    └─ ble_manager                # 鸿蒙适配核心代码
│         ├─ index.ets             # 鸿蒙适配代码入口
│         ├─ ts.ets                # TS 导出入口
│         └─ src/main
│              ├─ cpp              # C++ 侧代码（BleManagerPackage、codegen 生成代码）
│              └─ ets              # 鸿蒙适配源码
│                   ├─ BlePackage.ets    # 包入口，注册 BleTurboModule
│                   ├─ BleTurboModule.ts # TurboModule 实现，桥接 JS 与原生 BLE 接口
│                   ├─ DefaultScanManager.ts # 扫描管理实现
│                   ├─ NotifyBufferContainer.ts # 通知缓冲区管理
│                   ├─ PeripheralData.ts # 外围设备数据封装
│                   ├─ BleManagerLogger.ts # 日志工具
│                   ├─ types.ts         # 鸿蒙侧类型定义
│                   ├─ utils/Util.ts    # 工具类
│                   └─ generated        # codegen 生成的代码
├── src                            # RN代码
│    ├─ index.ts                   # 入口文件
│    ├─ types.ts                   # 类型文件
│    └─ NativeGeneratedBleManagerTurboModule.ts # codegen类型文件
├── docs                           # 原库文档
├── README.md                      # 中文安装使用方法
└── README_en.md                   # 英文安装使用方法

贡献代码

在使用过程中，如发现任何问题，均可提交 Issue。当然，也非常欢迎提交 PR 。

开源协议

本项目基于 The MIT License (MIT) ，欢迎自由使用并参与开源。