@react-native-ohos/react-native-nitro-modules

v0.31.11

Published

22 days ago

Insanely fast native C++, Swift or Kotlin modules with a statically compiled binding layer to JSI.

文档模板：v0.4.2

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-nitro-modules 版本所属关系如下：

| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 | | ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | | @react-native-ohos/react-native-nitro-modules | ~ 0.31.11 | Gitcode Releases | 0.77.*/0.82.* | partially(0.82) | API12+ | 0.31.10 | master |

简介

Nitro Modules 是一种面向 React Native 的高性能、类型安全的原生模块，它通过静态编译生成与 JSI 的绑定代码。Nitro Modules 由两部分组成：

react-native-nitro-modules：核心 C++ 库，为所有 Nitro Modules 提供底层支持。
nitrogen：一个可选的代码生成器，供 Nitro 模块库作者使用。

下载安装

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

npm

npm install @react-native-ohos/react-native-nitro-modules

yarn

yarn add @react-native-ohos/react-native-nitro-modules

Link

| | 是否支持autolink | RN框架版本 | |--------------------------------------|-----------------|------------| | ~ 0.31.11 | partially(0.82) | 0.77/0.82 |

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

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

打开 entry/src/main/cpp/CMakeLists.txt，添加：

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
+    "./HybridMath.cpp"
)

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
+ #include "HybridObjectRegistry.hpp"
+ #include "HybridMath.hpp"

using namespace rnoh;
+ using namespace margelo::nitro;
+ using namespace margelo::nitro::test;
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
+    HybridObjectRegistry::registerHybridObjectConstructor(
+        "Math", []() -> std::shared_ptr<HybridObject> { return std::make_shared<HybridMath>(); });
    return {
      std::make_shared<SamplePackage>(ctx)
    };
}

打开entry/src/main/cpp/HybridMath.hpp，添加：

+ #include "HybridObject.hpp"
+ namespace margelo::nitro::test {
+ class HybridMath: public HybridObject {
+ public:
+   HybridMath(): HybridObject(NAME) { }

+ public:
+   double add(double a, double b);

+ protected:
+   void loadHybridMethods() override;

+ private:
+   static constexpr auto NAME = "Math";
+ };
+ }

打开entry/src/main/cpp/HybridMath.cpp，添加：

+ #include "HybridMath.hpp"
+ namespace margelo::nitro::test {
+ double HybridMath::add(double a, double b) {
+   return a + b;
+ }
+
+ void HybridMath::loadHybridMethods() {
+   // register base methods (toString, ...)
+   HybridObject::loadHybridMethods();
+   // register custom methods (add)
+   registerHybrids(this, [](Prototype& proto) {
+     proto.registerHybridMethod(
+       "add",
+       &HybridMath::add
+     );
+   });
+ }
+ }

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

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

2. 引入原生端代码

目前有两种方法：

通过 har 包引入；
直接链接源码。

方法一：通过 har 包引入（推荐）

[!TIP] har 包位于三方库安装路径的 harmony 文件夹下。

打开 entry/oh-package.json5，添加以下依赖

"dependencies": {
    "@react-native-ohos/react-native-nitro-modules": "file:../../node_modules/@react-native-ohos/react-native-nitro-modules/harmony/nitro_modules.har"
  }

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

方法二：直接链接源码

[!TIP] 如需使用直接链接源码，请参考直接链接源码说明

3. 配置 CMakeLists 和引入 NitroModulesPackage、注册HybridObject、新增HybridMath.hpp和HybridMath.cpp文件

打开 entry/src/main/cpp/CMakeLists.txt，添加：

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-nitro-modules/src/main/cpp" ./nitro_modules)
# 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"
+    "./HybridMath.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_nitro_modules)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
+ #include "NitroModulesPackage.h"
+ #include "HybridObjectRegistry.hpp"
+ #include "HybridMath.hpp"

using namespace rnoh;
+ using namespace margelo::nitro;
+ using namespace margelo::nitro::test;
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
+    HybridObjectRegistry::registerHybridObjectConstructor(
+        "Math", []() -> std::shared_ptr<HybridObject> { return std::make_shared<HybridMath>(); });
    return {
      std::make_shared<SamplePackage>(ctx),
+     std::make_shared<NitroModulesPackage>(ctx)
    };
}

打开entry/src/main/cpp/HybridMath.hpp，添加：

+ #include "HybridObject.hpp"
+ namespace margelo::nitro::test {
+ class HybridMath: public HybridObject {
+ public:
+   HybridMath(): HybridObject(NAME) { }

+ public:
+   double add(double a, double b);

+ protected:
+   void loadHybridMethods() override;

+ private:
+   static constexpr auto NAME = "Math";
+ };
+ }

打开entry/src/main/cpp/HybridMath.cpp，添加：

+ #include "HybridMath.hpp"
+ namespace margelo::nitro::test {
+ double HybridMath::add(double a, double b) {
+   return a + b;
+ }
+
+ void HybridMath::loadHybridMethods() {
+   // register base methods (toString, ...)
+   HybridObject::loadHybridMethods();
+   // register custom methods (add)
+   registerHybrids(this, [](Prototype& proto) {
+     proto.registerHybridMethod(
+       "add",
+       &HybridMath::add
+     );
+   });
+ }
+ }

4. 在 ArkTs 侧引入 NitroModulesPackage

打开 entry/src/main/ets/RNPackagesFactory.ts，添加：

  ...
+ import { NitroModulesPackage } from '@react-native-ohos/react-native-nitro-modules/ts';

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

运行

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

RNOH: 0.77.33; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
RNOH: 0.82.7; SDK: HarmonyOS 6.1.0 Release SDK; IDE: DevEco Studio 6.1.0.830; ROM: 6.0.0.130;

使用示例

下面的代码展示了这个库的基本使用场景：

[!WARNING] 使用时 import 的库名不变。

import React from 'react';
import { View, Text, Pressable, StyleSheet } from 'react-native';
import type {TurboModule} from 'react-native/Libraries/TurboModule/RCTExport';
import {TurboModuleRegistry} from 'react-native';
import { type HybridObject, NitroModules } from 'react-native-nitro-modules'

interface Math extends HybridObject<{}> {
    add(a: number, b: number): number
}

export interface Spec extends TurboModule {
    install(): void;
}

const PlatformConstants	= TurboModuleRegistry.get<Spec>('NitroModules');
if(PlatformConstants) {
    PlatformConstants.install()
}

const App = () => {
  const handleButtonClick = () => {
    const math = NitroModules.createHybridObject<Math>("Math")
    const result = math.add(15, 7) // --> 22
    console.info("result:", result) 
  };

  return (
    <View style={styles.container}>
      <Text style={styles.text}>Hello React Native TSX!</Text>
      <View style={styles.buttonWrapper}>
        <Pressable
          onPress={handleButtonClick}
          style={styles.button}
          android_ripple={{ color: '#ccc' }}
        >
          <Text style={styles.buttonText}>add</Text>
        </Pressable>
      </View>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#f5f5f5',
  },
  text: {
    fontSize: 18,
    color: '#333',
    marginBottom: 20,
  },
  buttonWrapper: {
    paddingVertical: 20,
    paddingHorizontal: 20,
  },
  button: {
    paddingVertical: 8,
    paddingHorizontal: 16,
    backgroundColor: '#007AFF',
    borderRadius: 4,
  },
  buttonText: {
    fontSize: 16,
    color: '#fff',
    textAlign: 'center',
  },
});

export default App;

使用说明

接口说明

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "OpenHarmony Support"列为 yes 表示 OpenHarmony平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

属性

| 名称 | 参数类型 | 默认值 | 必填 | 平台 | OpenHarmony平台支持 | 描述 | |------------------------------|--------------------|------------|---------------|------|------------------|---------------| | buildType | 'debug' 或者 'release' | 无 | no | iOS/Android | yes | 获取在 NITRO_DEBUG 中定义的当前构建类型配置| | version | string | 无 | no | iOS/Android | yes | 获取此应用所构建使用的原生Nitro Modules核心运行时版本 | | name | string | 无 | no | iOS/Android | yes | 混合对象的名称 | | AnyHybridObject | interface | 无 | no | iOS/Android | yes | 表示基础 HybridObject 类型的值，所有其他 HybridObjects 均继承自它 | | CustomType | type | 无 | no | iOS/Android | yes | 表示一种自定义的、手动编写的本地类型 | | Sync | type | 无 | no | iOS/Android | yes | 将给定函数标记为同步函数，使其能够在同一线程上同步调用 | | HybridView | type | 无 | no | iOS/Android | no | 表示Nitro混合视图 |

API

| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | OpenHarmony平台支持 | 描述 | |--------|---------|-----|-------|-------|--------|-----|-----------------| | hasHybridObject | function | string | boolean | no | iOS/Android | yes | 返回指定@linkcode name的HybridObject是否已注册 | | isHybridObject | function | object | boolean | no | iOS/Android | yes | 返回给定的@linkcode object是否为@linkcode HybridObject | | getAllHybridObjectNames | function | / | string[] | no | iOS/Android | yes | 获取所有已注册混合对象的列表 | | box | function | T | BoxedHybridObject | no | iOS/Android | yes | 将给定的@linkcode hybridObject装箱为@linkcode BoxedHybridObject，之后可以在单独的运行时中将其拆箱 | | unbox | function | / | T | no | iOS/Android | yes | 表示一个装箱的@linkcode HybridObject，之后可以再次拆箱 | | hasNativeState | function | unknown | boolean | no | iOS/Android | yes | 返回给定的@linkcode object是否具有NativeState | | updateMemorySize | function | HybridObject | T | no | iOS/Android | yes | 重新计算给定@linkcode HybridObject的memorySize，并通知JS虚拟机更新后的内存占用情况 | | getHybridObjectConstructor | function | string | HybridObjectConstructor | no | iOS/Android | yes | 获取给定 HybridObject @linkcode T 的构造函数 | | toString | function | / | string | no | iOS/Android | yes | 返回给定HybridObject的字符串表示形式 | | equals | function | HybridObject | boolean | no | iOS/Android | yes | 返回此 HybridObject 是否与 @linkcode other 是同一个对象 | | dispose | function | / | void | no | iOS/Android | yes | 释放此@linkcode HybridObject可能持有的任何原生资源，并释放此@linkcode HybridObject的NativeState | | createHybridObject | function | string | T | no | iOS/Android | yes | 创建 HybridObject @linkcode T 的新实例 | | getHostComponent | function | string | HostComponent | no | iOS/Android | no | 通过给定的@linkcode name查找并返回原生视图（即“HostComponent”）| | getConstants | function | / | Record<string, unknown> | no | HarmonyOS | yes | 返回暴露给 JavaScript 的 Nitro Modules 常量对象，包含 buildType、version、platform三个字段 |

遗留问题

不支持HybridView和getHostComponent： issue#12。

其他

目录结构

/rntpc_react-native-nitro-modules  # 项目根目录
├── packages\react-native-nitro-modules\harmony                # 鸿蒙适配代码
│                                        └─ nitro_modules.har  # har包
│                                        └─ nitro_modules      # 鸿蒙适配核心代码
│                                              └─ index.ets    # 鸿蒙适配代码入口    
│                                              └─ src/main/cpp  
│                                              └─ src/main/ets  
├── packages\react-native-nitro-modules/src                    # RN代码
│                                        └─ index.ts           # 入口文件          
├── README.md      # 中文安装使用方法
├── README_en.md   # 英文安装使用方法

贡献代码

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

开源协议

本项目基于 The MIT License (MIT) ，请自由地享受和参与开源。