去年做鸿蒙应用适配时最让我头疼的一件事就是项目里那套用 React Native 写的界面怎么搬到完全不再兼容 Android 的鸿蒙设备上。刚开始我以为 RN 代码可以直接跑结果发现新一代鸿蒙系统已经不在运行时层面加载 Android 格式的安装包RN 的底层渲染宿主直接没了。这条路走不通就只能换方向让 React Native 去驱动鸿蒙原生组件组件用 ArkTS 写渲染交给 ArkUI 引擎。这篇文章就是把这条路的关键环节拆开讲清楚包括鸿蒙开发的基础概念、RN 与鸿蒙原生交互的桥接机制以及一个可以直接参考的落地示例。适合正在做鸿蒙化改造的 RN 团队也适合想把自己的 RN 技能迁移到鸿蒙生态的开发者。1. 为什么要在 React Native 项目里集成鸿蒙组件1.1 鸿蒙系统的运行边界已经变了先说一个最核心的背景鸿蒙系统已经不再把 Android 运行时当作默认兼容层。这意味着以前那种“拿一个 Android 安装包直接装到鸿蒙设备上”的玩法在新版本上基本行不通。RN 应用本质上是一个 Android/iOS 原生工程里的解释器加视图容器JS 代码靠原生宿主去渲染。一旦原生的 Android View 或者 iOS UIKit 不在系统里RN 就失去了最底层的“画板”。但 RN 本身只是一种 JS 框架它并不关心画板是 Android View 还是 ArkUI 组件。只要有人实现了鸿蒙系统上的渲染宿主RN 的 JS 逻辑照样能跑只是渲染出来的每一个视图组件都换成了鸿蒙自己的 ArkUI 组件。这就意味着RN 页面要能在鸿蒙设备上显示必须做一层原生桥接把 RN 框架里的组件请求翻译成 ArkUI 组件。而我们说的“开发鸿蒙组件”其实就是这个桥接里最关键的部分你写一个鸿蒙原生组件让 RN 侧能像使用普通 React 组件一样去使用它。1.2 集成鸿蒙组件能解决的不只是界面问题很多团队一开始会觉得既然鸿蒙上有自己的声明式 UI为什么不直接用 ArkTS 重写何必绕一圈用 RN这里有几个实际场景第一存量代码与团队技能的复用。如果团队里已经有成熟的 RN 页面完全重写 ArkTS 的成本非常高。通过桥接层大量逻辑层代码可以继续复用只有真正需要原生控件的地方封装成鸿蒙组件。第二原生系统能力的使用。鸿蒙有很多系统级能力比如分布式文件、跨端流转、原子化服务等这些东西没法从 JS 层直接拿必须通过原生模块暴露出来。把这类能力封装成组件或模块RN 侧就能跟平时调用一个普通 JS 模块一样使用它。第三性能考虑。高频刷新或复杂绘制的模块如果用 JS 写桥接层丢数据会非常吃力。放进鸿蒙原生组件里由 ArkUI 直接渲染性能会稳很多。所以集成鸿蒙组件这件事本质上是一个原生能力边界问题你在 RN 侧能用到鸿蒙系统的多少能力取决于你封装了多少鸿蒙原生组件和模块。这也解释了为什么动手前必须先了解鸿蒙开发的基础。2. 鸿蒙开发基础动手前必知的几个概念2.1 工程模型与 ArkTS 语言鸿蒙应用工程和 Android/iOS 都不一样。跑在设备上的入口叫 Ability通常 UIAbility 就是包含界面的能力。工程里的源代码一般放在src/main/ets目录下组件写在components目录页面写在pages目录。开发语言主要用 ArkTS它基于 TypeScript 做了裁剪和扩展比如不允许用any、不能用运行时反射那一套代码风格更像 SwiftUI 或 Compose 的声明式写法。最基础的自定义组件是一个用struct声明的结构体上面用Component装饰器标记然后在build()方法里写 UI。举个例子Component export struct Greeting { Prop name: string World build() { Column() { Text(Hello, ${this.name}) .fontSize(20) } } }这里的Prop是组件外部传入的属性属性变化时 UI 会自动刷新。这个思路其实和 React 的 props 很像但 ArkTS 是原生编译的状态更新不经过 JS 引擎刷新路径短很多。2.2 状态管理、属性传递与 UI 刷新在鸿蒙组件里状态管理是核心。你用State声明组件内部状态用Prop声明外部传入的单向属性用Link建立双向同步。类似地还有Provide和Consume用于跨层共享数据。如果配合 RN 使用你会发现一个很重要的对应关系RN 里通过 JS 传给原生的 props到了鸿蒙侧就是Prop字段RN 侧的原生事件回调到了鸿蒙侧就是组件内的事件回调函数。实际调试中我遇到过一个问题RN 侧修改了一个 prop但鸿蒙组件没有刷新。后来发现是因为我在鸿蒙组件里用State保存了 prop 的副本而State只在组件内部变化时触发更新外部传入的字段变化不会被它感知。正确做法是直接用Prop接收或者用Watch监听外部传入字段的变化。这一点非常容易踩坑尤其在封装自定义组件时。2.3 组件生命周期与页面生命周期鸿蒙组件的生命周期和 RN 组件不完全对齐。ArkUI 里自定义组件有几个关键方法aboutToAppear组件即将出现在页面时、build渲染 UI、aboutToDisappear组件即将销毁时。UIAbility 的生命周期则包括onCreate、onWindowStageCreate、onForeground、onBackground、onDestroy等。在集成 RN 时通常 RN 的页面会挂载到一个 UIAbility 上鸿蒙原生组件作为页面里的子组件展示。这里要特别留意RN 侧组件可能因为路由变化频繁卸载和重建但鸿蒙侧 UIAbility 可能还活着所以不能在组件生命周期里做太多“一次性注册”的操作。比如全局事件监听最好注册在 UIAbility 级别组件内部只在aboutToAppear里做临时绑定在aboutToDisappear里解除绑定。3. React Native 集成鸿蒙的技术路径与方案选型3.1 适配层到底在适配什么React Native 本身不是一个完整的界面框架它把所有跨平台差异都藏在“Host”这一层。你的 JS 代码调用ViewRN 框架会找到当前平台对应的原生 View 组件。Android 上对应的是ReactViewGroupiOS 上对应的是UIView的封装。在鸿蒙系统上要实现这样的能力就必须有一个适配层把 RN 的组件命令映射到 ArkUI 组件。这个适配层做的事情听起来简单但实际上非常重JS 引擎的接入、渲染命令的分发、触摸事件的转换、模块消息的转发、线程模型的适配全都要有。目前比较成熟的做法是鸿蒙官方提供了一个 RN 适配框架社区里也有基于开源鸿蒙实现的适配方案。你在项目里要做的其实就是依赖这个适配层然后在上面写自己的原生模块和原生组件。3.2 NativeModule 与自定义 UI 组件的分工RN 提供两种与原生通信的方式原生模块NativeModule和自定义原生 UI 组件。我在实际项目中经常看到有人混淆这两个概念。原生模块是一段不参与界面渲染的代码用来暴露 API。比如你想在鸿蒙上读取某个系统参数就可以写一个NativeModule在 JS 里通过NativeModules.xxx调用。自定义 UI 组件则是真正渲染出一个原生视图JS 侧通过requireNativeComponent引入后作为 React 组件放到 JSX 里。我们需要开发的“鸿蒙组件”走的是第二条路写一个 ArkUI 组件再把它注册给 RN 适配层让它能被 JSX 直接使用。第一条路通常用来封装系统能力比如文件读取、蓝牙广播等它可以被 UI 组件内部调用但不会直接产生界面。开发鸿蒙组件时建议把业务逻辑和 UI 表现分开UI 组件负责渲染NativeModule 负责能力调用。这样后续维护时哪怕 UI 结构改了系统能力的逻辑也不用动。3.3 版本匹配是第一优先级集成 RN 和鸿蒙组件时最让人抓狂的不是代码难写而是版本不匹配。RN 适配层往往绑定特定的 RN 版本和鸿蒙 SDK 版本。比如你项目里用的是 RN 0.72但适配层只适配到 0.71那就会在编译阶段报一堆接口找不到的错误。所以我一般建议先确定一个稳定的技术组合比如固定使用某个 RN 版本、某个鸿蒙 SDK API 级别、某个适配层版本然后锁死不要轻易升级其中一个。另外鸿蒙系统本身的 API 也在持续演进。不要让项目依赖太新的 API除非你能确保适配层已经同步支持。如果是团队新接触鸿蒙开发可以先用 API 级别较稳定、文档更充分的版本避免被新特性带偏。4. 实操从零开发一个 RN 可调用的鸿蒙组件4.1 准备一个鸿蒙工程和 RN 工程这里我用一个模拟项目来演示场景是一个“数据统计卡片”显示一个标题和一个数字点击卡片后把点击事件传回 RN。这个例子虽然简单但覆盖了属性传递、事件回调、自定义组件注册三个关键点。首先准备两个工程一个鸿蒙工程负责实现原生组件一个 RN 工程负责业务逻辑。鸿蒙工程建议用官方 IDE 创建工程模板选择 Stage 模型的空应用SDK 选好目标 API 版本。RN 工程直接用react-native init创建然后把 JS bundle 的构建产物集成到鸿蒙工程的资源目录里。这里要注意鸿蒙工程其实是最后打包成安装包的宿主所以 RN 更像是一个“构建 JS 代码的前端工程”真正运行和打包靠鸿蒙工程。4.2 编写鸿蒙侧的自定义组件先写一个最普通的 ArkUI 统计卡片组件。注意我们不直接把这个组件暴露给 RN而是用适配层提供的基础类再做一层封装。先写基础组件Component export struct StatCard { Prop title: string Prop count: number 0 onClick: () void () {} build() { Column({ space: 8 }) { Text(this.title) .fontSize(16) .fontColor(#333333) Text(String(this.count)) .fontSize(28) .fontWeight(FontWeight.Bold) } .padding(16) .backgroundColor(#F5F5F5) .borderRadius(12) .onClick(() { this.onClick() }) } }接下来为了让 RN 适配层能识别并驱动这个组件我们要写一个桥接组件类继承适配层的自定义组件基类。在这里我保持组件名与你即将在 RN 侧引用的名称一致也就是RNStatCardComponent export struct RNStatCard extends ComponentBase { Prop title: string Prop count: number 0 build() { StatCard({ title: this.title, count: this.count, onClick: () { this.callOnClick() } }) } callOnClick() { // 通过适配层把事件发送给 RN } }适配层基类ComponentBase暴露了一些方法可以在属性变化时同步给 RN也可以把原生事件发回去。具体方法名会随适配层版本略有差异但整体流程都是固定的把接收到的Prop传给真正的 UI 组件把原生事件转换成适配层的事件对象发出。4.3 在 RN 侧注册与调用在 RN 工程里我们新建一个封装组件文件。传统写法是先用requireNativeComponent把原生组件注册成 React 组件然后导出import { requireNativeComponent } from react-native; const RNStatCard requireNativeComponent(RNStatCard); export default RNStatCard;然后在页面中使用RNStatCard title今日新增用户 count{42} onClick{event { console.log(native event:, event.nativeEvent); }} /这个过程中RN 适配层会自动完成几件事把title和count转换成 ArkTS 侧可序列化的基础类型传给鸿蒙组件组件内点击事件触发后通过事件通道把数据传回 JS 侧JS 侧重新渲染时如果props发生变化也会自动把新值同步给原生组件。4.4 构建、打包与真机调试集成后的调试流程和纯 RN 项目不太一样。由于真正的运行宿主是鸿蒙工程所以你需要先在鸿蒙 IDE 里把工程编成安装包再把 JS bundle 作为资源一起打进包里。建议调试的时候分两步走第一步在 RN 工程里把 bundle 打出来确认 JS 代码没有报错第二步到鸿蒙工程里编译原生代码用 IDE 的日志输出过滤鸿蒙适配层和自定义组件的关键日志。有一点很重要鸿蒙真机调试时若 RN bundle 是动态加载的需要保证鸿蒙应用能访问到本机的 dev server。这时要设置好 IP 和端口同时确保鸿蒙应用有网络权限。如果懒得折腾动态加载可以先把 bundle 编译进工程走离线包模式这样问题更少。5. 常见问题与排查技巧实录5.1 白屏与组件注册失败集成初期最常见的问题是页面出来一块空白可是没有报错。这类问题九成出在组件名对不上。RN 侧的requireNativeComponent(RNStatCard)需要和鸿蒙侧注册到适配层的组件名完全一致。组件名大小写、下划线、空格都不能差。另一个隐蔽问题是组件类名和注册名不一致你有两个文件一个叫RNStatCard一个叫StatCardBridge注册的时候写错了一个JS 侧却还在用老名字最后白屏。排查方法很简单打开鸿蒙 IDE 的日志过滤搜component或者UIManager相关关键字它能告诉你某个组件名是否被找到。找不到的话优先检查注册文件里导出的组件名。5.2 类型映射和数据边界RN 的 JS 数据类型和 ArkTS 的严格类型之间有一条线。基础类型number、string、boolean能直接映射但对象、数组也有一定的序列化限制。函数不能作为属性直接传进去因为 ArkTS 侧没有直接从 JS 拿函数的通道。如果你需要回调一定要用事件机制而不是试图把闭包作为 prop 传过去。还有一个常见问题是精度丢失。JS 的Number是双精度浮点但 ArkTS 里如果用number还好如果原生侧是int或者long大数字在转换时可能溢出。处理金额、ID 这类数据时最好用字符串传递不要用数值类型。我踩过这个坑之后就把所有超过安全整数范围的参数全部改成 string虽然难看了点但再也没丢过数据。5.3 事件回调丢失或延迟事件从鸿蒙原生传到 RN 侧走的是 EventEmitter 通道。很多人在aboutToAppear里注册监听事件在aboutToDisappear里忘记移除结果导致事件被重复监听或者收到错乱的数据。比如卡片组件内部有定时器每次重新进入页面就多一个定时器事件就发重复了。更好的做法是鸿蒙组件只负责一次性定义事件回调RN 侧通过调用更新 props 来触发逻辑而不是自己在原生侧维护全局监听。如果确实需要广播式监听建议把监听器放到 UIAbility 或者一个全局的单例模块里组件销毁时不要注销它而是让监听器中判断当前组件实例是否仍然存活。5.4 生命周期不同步RN 侧组件可能会在 JS 层更新时重建而鸿蒙原生组件可能还持有上一次的状态。最典型的情况你在 RN 里用同一个组件名渲染多个不同业务卡片滚出屏幕后重新滚回来发现原生组件展示的还是上一次的数据。原因是原生组件的Prop没有正确同步或者说新 props 被其他生命周期函数覆盖了。解决办法是在鸿蒙侧自定义组件中增加一个Watch方法去监听关键 prop 的变化每次数据更新都直接刷新 UI 数据源。另外尽量避免在原生组件的构造函数里保存 props 的快照要始终从最新的Prop取数据。5.5 性能表现与 JS 线程压力RN 和原生组件混搭时性能瓶颈往往出现在 JS 线程到原生线程的事件传输。如果每次数据变化都从 JS 侧发一个事件让原生组件刷新高频交互下会有明显卡顿。我后来把高频变化的计数器放进鸿蒙原生组件内部管理内部通过State更新 UI只有最终结果才回传给 RN。这样 JS 线程的压力小了很多交互也跟手了。另外要留意 ArkUI 里的布局单位是 vpRN 默认单位是 dp 或 px。如果尺寸在跨端传递时没有换算组件会看起来偏大或偏小。这个细节我在示例里没有展开但实际项目中一定要处理。6. 工程落地时的几点额外建议到这里核心操作已经讲完了。最后想以个人经验的角度再多说几句因为代码能跑通只是第一步真正放到团队项目里还有不少工程化的问题。第一个建议是尽量让鸿蒙组件保持“薄”。也就是说原生组件只做 UI 展示和简单的交互事件转发业务逻辑尽量留在 RN 的 JS 层。这样做的好处是后续如果 UI 需要调整你可以不碰原生代码如果鸿蒙 SDK 升级导致接口变化改动面也不会很大。组件薄了测试成本也会明显降低。第二个建议是组件协议要提前定好。数据模型、事件名、错误码、回调格式都要在 RN 和鸿蒙两端同时维护一份文档。我在实际项目里吃过亏原生侧事件名叫onCardClickRN 侧监听的是onPress结果调试了很久才发现是命名不一致。这种问题靠编译查不出来只能靠运行时日志慢慢排查。第三个建议是权限与安全要区分清楚。鸿蒙系统在权限管理上有自己的一套逻辑你在原生组件里访问联系人、位置等敏感权限时需要在使用前检查权限并请求授权。RN 侧不能直接替原生请求权限必须先通过原生模块暴露权限检查接口。考虑到权限弹窗对用户体验影响很大建议把权限触发时机设计得比普通页面逻辑更谨慎一些。最后分享一个调试小技巧在鸿蒙 IDE 里同时打开 RN 的 Chrome 调试器和 ArkUI 的 UI Inspector。RN 侧报 JS 错误时先在浏览器端的调试器里看堆栈UI 布局或属性同步问题时再用 UI Inspector 看 ArkUI 的实时组件树。两个窗口对比着看很多跨端问题一眼就能定位。如果你也要走这条集成路线希望这些经验能帮你少踩几个坑。