文档模板：v0.4.2

react-native-nitro-modules

本项目基于 react-native-nitro-modules 开发。

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

简介

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 add @react-native-ohos/react-native-nitro-modules

链接

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

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

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
+    "./HybridMath.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)
    };
}

+ #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";
+ };
+ }

+ #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
+     );
+   });
+ }
+ }

{
  "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 包引入（推荐）

打开 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

方法二：直接链接源码

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

然后编译、运行即可。

约束与限制

兼容性

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

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

使用示例

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

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;

使用说明

接口说明

属性

API

遗留问题

• 不支持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) ，请自由地享受和参与开源。