从零开始在HarmonyOS上开发React Native应用

最新推荐文章于 2025-12-18 15:34:10 发布

原创最新推荐文章于 2025-12-18 15:34:10 发布 · 362 阅读

19 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #react native #华为

本文原创发布在华为开发者联盟社区，欢迎前往与更多开发者进行互动。
更多相关问题可点击原帖进行交流：从零开始在HarmonyOS上开发React Native应用。

问题描述
React Native框架是一个基于JavaScript与React的开源框架，主要用于开发原生渲染的移动应用程序。React Native for OpenHarmony（RNOH）在React Native原有能力之上，进行了深度的鸿蒙化适配与扩展，使开发者能够基于熟悉的React技术栈，高效地构建适用于HarmonyOS的应用程序。
从0到1构建HarmonyOS React-Native项目主要涉及以下几部分：
1.环境准备
2.创建React Native工程
3.创建HarmonyOS工程
4.在HarmonyOS工程中集成RNOH
5.加载Bundle包
6.启动并运行工程

1.环境准备
1.下载与安装DevEco Studio
选择最新的release版本下载并安装：

2.设置 DevEco Studio 代理
DevEco Studio 开发环境需要依赖于网络环境，需要连接上网络才能确保工具的正常使用，详情请参考配置代理。

3.配置 CAPI 版本环境变量
当前React-Native框架提供的Demo工程默认为CAPI版本，需要配置环境变量RNOH_C_API_ARCH = 1。

4.编辑用户级 .npmrc 配置文件
为了使用加速 npm 包的下载，可以配置镜像源，关闭 SSL 证书校验还可以进一步加速下载，但是这会降低安全性，需用户评估后再使用。
配置文件位置：C:\Users\用户名.npmrc（Windows），如果没有可以手动创建。
修改 registry 后需执行 npm cache clean --force 清理缓存，以确保新的 registry 生效。参考.npmrc 配置文件内容如下：

strict-ssl=false

sslVerify=false

registry=https://repo.huaweicloud.com/repository/npm/

5.hdc环境配置
hdc 是 OpenHarmony 为开发人员提供的用于调试的命令行工具，HarmonyOS ReactNative 工程使用 hdc 进行真机调试。
hdc 工具通过 OpenHarmony SDK 获取，存放于 SDK 的 toolchains 目录下，请将 {DevEco Studio安装路径}/sdk/{SDK版本}/openharmony/toolchains 的完整路径添加到环境变量中。

6.设备调试可选择使用本地真机运行应用或者使用模拟器运行应用。

2.创建ReactNative工程
1.创建新项目
可选择一个目录，例如 D 盘根目录，使用 ReactNative 内置的命令行工具来创建一个名为 “MyRNProject” 的新项目。
这个命令行工具不需要安装，可以直接用 node 自带的npx命令来创建，目前 ReactNative for OpenHarmony 仅支持 0.72.5 版本的 ReactNative。

npx react-native@0.72.5 init MyRNProject --version 0.72.5

命令运行结果如下：

运行成功后会在D:\RN目录下创建MyRNProject文件夹，文件夹目录结构如下：

2.配置鸿蒙依赖
打开 MyRNProject 目录下的 package.json，在 scripts 下新增 OpenHarmony 的依赖, 添加依赖后的package.json文件如下所示。

{

 "name": "AwesomeProject",

 "version": "0.0.1",

 "private": true,

 "scripts": {

   "android": "react-native run-android",

   "ios": "react-native run-ios",

   "lint": "eslint .",

   "start": "react-native start",

   "test": "jest",

   "dev": "react-native bundle-harmony --dev"

 },

 "dependencies": {

   "react": "18.2.0",

   "react-native": "0.72.5"

 },

 "devDependencies": {

   "@babel/core": "^7.20.0",

   "@babel/preset-env": "^7.20.0",

   "@babel/runtime": "^7.20.0",

   "@react-native/eslint-config": "^0.72.2",

   "@react-native/metro-config": "^0.72.11",

   "@tsconfig/react-native": "^3.0.0",

   "@types/react": "^18.0.24",

   "@types/react-test-renderer": "^18.0.0",

   "babel-jest": "^29.2.1",

   "eslint": "^8.19.0",

   "jest": "^29.2.1",

   "metro-react-native-babel-preset": "0.76.8",

   "prettier": "^2.4.1",

   "react-test-renderer": "18.2.0",

   "typescript": "4.8.4"

 },

 "engines": {

   "node": ">=16"

 }

}

3.安装鸿蒙依赖包
在 AwesomeProject 目录下运行安装依赖包命令：

npm i @react-native-oh/react-native-harmony

4.配置metro.config.js并添加OpenHarmony适配代码
右键选择记事本打开 AwsomeProject\metro.config.js，并添加 OpenHarmony 的适配代码。配置文件的详细介绍，可以参考React Native 中文网。修改完成后的文件内容如下：

const {mergeConfig, getDefaultConfig} = require('@react-native/metro-config');

const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');



/**

* @type {import("metro-config").ConfigT}

*/

const config = {

  transformer: {

    getTransformOptions: async () => ({

      transform: {

        experimentalImportSupport: false,

        inlineRequires: true,

      },

    }),

  },

};



module.exports = mergeConfig(getDefaultConfig(__dirname), createHarmonyMetroConfig({

  reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',

}), config);

5.生成bundle
在 AwesomeProject 目录下运行生成 bundle 文件的命令。

npm run dev

成功运行结果如下：

如遇报错：error: unknown command 'bundle-harmony'，需要手动在D:\RN\MyRNProject\MyRNProject\package.json文件中添加依赖：

"memfs":"^4.17.2"

运行成功后，会在 AwesomeProject/harmony/entry/src/main/resources/rawfile 目录下生成 bundle.harmony.js 和 assets 文件夹，assets 用来存放图片（如果 bundle 中不涉及本地图片，则没有 assets 文件夹）:

3.创建HarmonyOs工程
1.打开deveco studio, 创建新工程。

点击 Next 按钮，并在 Compile SDK 中选择 API20，创建一个名为 “MyRNApplication” 的项目。注意项目路径不要太长，如图所示：

2.配置签名
连接真机，点击 File > Project Structure，在弹窗界面点击 Signing Configs，勾选 Support HarmonyOS 和 Automatically generate signature，然后点击 Sign In 登录华为账号，并签名。

3.添加 React Native 配置
在刚创建的HarmonyOS工程的entry（D:\RN\MyRNApplication\entry>）目录下执行命令：

ohpm i @rnoh/react-native-openharmony

执行完成后会在工程级目录以及模块级目录下生成 oh_modules 文件夹。

4.在HarmonyOS工程中集成RNOH
1.补充CPP侧代码
在D:\RN\MyRNApplication\entry\src\main目录下新建cpp文件夹，并新增CMakeLists.txt文件：

将 RNOH 的适配层代码添加到CMakeLists.txt中用于编译生成librnoh_app.so，例如将以下代码复制到新创建的CMakeLists.txt中：

project(rnapp)

cmake_minimum_required(VERSION 3.4.1)

set(CMAKE_SKIP_BUILD_RPATH TRUE)

set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")



set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/src/main/cpp")

set(RNOH_GENERATED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/generated")

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")

add_compile_definitions(WITH_HITRACE_SYSTRACE)

set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use



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



add_library(rnoh_app SHARED

    "./PackageProvider.cpp"

    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"

)



target_link_libraries(rnoh_app PUBLIC rnoh)

2.在cpp 目录下新增 PackageProvider.cpp并复制以下代码。

#include "RNOH/PackageProvider.h"



using namespace rnoh;



std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {

    return {};

}

3.打开 MyRNApplication\entry\build-profile.json5，将 cpp 中的代码添加到应用工程的编译构建任务中。
如果在 x86_64 架构的模拟器上运行应用，需在 externalNativeOptions 配置中额外添加 abiFilters 字段，并包含 x86_64 架构参数。
如下所示，abiFilters 字段当前被注释，默认仅构建适用于 arm64-v8a 架构的版本。详细介绍可以参考模块级build-profile.json5。

{

 "apiType": "stageMode",

 "buildOption": {

+   "externalNativeOptions": {

+      "path": "./src/main/cpp/CMakeLists.txt",

+      "arguments": "",

+      "cppFlags": "",

+      // "abiFilters": ["arm64-v8a", "x86_64"]

+    }

 },

 "targets": [

   {

     "name": "default"

   },

   {

     "name": "ohosTest",

   }

 ]

}

4.补充ArkTS侧的代码
打开 MyRNApplication\entry\src\main\ets\entryability\EntryAbility.ets，替换为如下代码。

import { RNAbility } from '@rnoh/react-native-openharmony';

import { hilog } from '@kit.PerformanceAnalysisKit';



export default class EntryAbility extends RNAbility {

  getPagePath() {

    return 'pages/Index';

  }



  override onCreate(want: Want): void {

    super.onCreate(want);

    hilog.info(0x0000, 'testTag', '%{public}s', 'EntryAbility onCreate');

  }

}

5.在 MyRNApplication\entry\src\main\ets 目录下新增 RNPackagesFactory.ets, 复制如下代码。

import { RNPackageContext, RNPackage } from '@rnoh/react-native-openharmony/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {

  return [];

}

6.打开 MyRNApplication\entry\src\main\ets\pages\Index.ets，添加RNOH的使用代码，修改后如下。

import {

  AnyJSBundleProvider,

  ComponentBuilderContext,

  FileJSBundleProvider,

  MetroJSBundleProvider,

  ResourceJSBundleProvider,

  RNApp,

  RNOHErrorDialog,

  RNOHLogger,

  TraceJSBundleProviderDecorator,

  RNOHCoreContext

} from '@rnoh/react-native-openharmony';

import { createRNPackages } from '../RNPackagesFactory';



@Builder

export function buildCustomRNComponent(ctx: ComponentBuilderContext) {}



const wrappedCustomRNComponentBuilder = wrapBuilder(buildCustomRNComponent)



@Entry

@Component

struct Index {

  @StorageLink('RNOHCoreContext') private rnohCoreContext: RNOHCoreContext | undefined = undefined

  @State shouldShow: boolean = false

  private logger!: RNOHLogger



  aboutToAppear() {

    this.logger = this.rnohCoreContext!.logger.clone("Index")

    const stopTracing = this.logger.clone("aboutToAppear").startTracing();



    this.shouldShow = true

    stopTracing();

  }



  onBackPress(): boolean | undefined {

    // NOTE: this is required since `Ability`'s `onBackPressed` function always

    // terminates or puts the app in the background, but we want Ark to ignore it completely

    // when handled by RN

    this.rnohCoreContext!.dispatchBackPress()

    return true

  }



  build() {

    Column() {

      if (this.rnohCoreContext && this.shouldShow) {

        if (this.rnohCoreContext?.isDebugModeEnabled) {

          RNOHErrorDialog({ ctx: this.rnohCoreContext })

        }

        RNApp({

          rnInstanceConfig: {

            createRNPackages,

            enableNDKTextMeasuring: true, // 该项必须为true，用于开启NDK文本测算

            enableBackgroundExecutor: false,

            enableCAPIArchitecture: true, // 该项必须为true，用于开启CAPI

            arkTsComponentNames: []

          },

          initialProps: { "foo": "bar" } as Record<string, string>,

          appKey: "AwesomeProject",

          wrappedCustomRNComponentBuilder: wrappedCustomRNComponentBuilder,

          onSetUp: (rnInstance) => {

            rnInstance.enableFeatureFlag("ENABLE_RN_INSTANCE_CLEAN_UP")

          },

          jsBundleProvider: new TraceJSBundleProviderDecorator(

            new AnyJSBundleProvider([

              new MetroJSBundleProvider(),

              // NOTE: to load the bundle from file, place it in

              // `/data/app/el2/100/base/com.rnoh.tester/files/bundle.harmony.js`

              // on your device. The path mismatch is due to app sandboxing on OpenHarmony

              new FileJSBundleProvider('/data/storage/el2/base/files/bundle.harmony.js'),

              new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'hermes_bundle.hbc'),

              new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'bundle.harmony.js')

            ]),

            this.rnohCoreContext.logger),

        })

      }

    }

    .height('100%')

    .width('100%')

  }

}

RNApp的参数appKey需要与RN工程中AppRegistry.registerComponent注册的appName保持一致，否则会导致白屏。

5.加载bundle包
本地加载 bundle。将MyRNProject\harmony\entry\src\main\resources\rawfile目录下的 bundle 文件和 assets 文件夹粘贴复制到HarmonyOS工程MyRNApplication\entry\src\main\resources\rawfile路径下，在 entry/src/main/ets/pages/Index.ets 中使用。

6.启动并运行工程
使用 DevEco Studio 运行 MyRNApplication 工程。如果运行按钮灰色不可用，需要先执行file->sync and refresh project。
执行完成后，控制台如图所示：

首次运行耗时可能需要10分钟左右，请耐心等待。
运行结果：

解决方案
顶一顶