系列写到这里已经第九篇了。前八篇我一直在聊React Native本身的语法、状态管理和性能优化评论区里越来越多的人在问同一件事我们项目马上要适配HarmonyOSRN到底能不能直接用那些系统组件怎么办这篇系列文章的第九篇我专门把鸿组件这件事讲透。先说明一下鸿组件不是某一个独立开源库的名字而是我们团队内部对鸿蒙HarmonyOS原生组件的简称更准确一点说是能通过RN组件机制在JSX里直接调用的ArkUI组件。这篇文章适合正在做RN跨端、又接到了鸿蒙适配任务的开发者也适合想把已有鸿蒙原生组件嵌入RN项目的原生开发同学。1. 鸿组件到底是什么为什么RN开发也得把它当回事1.1 先把这个叫法掰扯清楚很多前端同学第一次听到鸿组件是懵的以为是某种新框架。其实它就是我们很熟悉的原生组件概念只不过换到了HarmonyOS平台上。React Native不是一个完全脱离原生世界的框架。你在JS里写的View、Text、Button最终都会被翻译成对应平台的原生控件Android上是TextView、ButtoniOS上是UILabel、UIButton到了HarmonyOS设备上对应的就是ArkUI里的Text、Button这些基础组件。鸿组件就是这一族ArkUI组件在RN体系里的原生实现。举个最简单的例子你在RN里写Text style{{ fontSize: 16 }}你好鸿蒙/Text到了鸿蒙真机上负责把你好鸿蒙这几个字画到屏幕上的是一个ArkUI的Text组件。RN只是把样式和文本内容通过桥接机制传给了它。这个ArkUI组件就是鸿组件。换句话说鸿组件的存在感越弱说明适配做得越好但开发鸿组件的人必须清楚它的存在。1.2 为什么需要单独开发鸿组件可能有人会说RN内置了大量组件不是开箱即用吗确实RN自带的基础组件在支持鸿蒙的适配版本里大多能跑起来但能跑和够用之间差了十万八千里。业务场景里最常碰到的三类需求几乎都绕不开原生组件第一类是系统级UI能力。比如扫码页的取景框、系统统一的安全键盘、需要调用系统能力的授权弹窗这些在Android和iOS上都有现成的原生能力但在鸿蒙上必须用ArkUI/系统能力接口做一版原生组件再用RN封装一层才能被前端调用。第二类是性能敏感的渲染场景。画布、长列表中的复杂单元、高频更新的图表这些如果用纯JS和一个普通RN组件硬扛帧率很难看。把它们拆成鸿组件在原生侧做布局和绘制性能会稳得多。第三类是复用已有资产。很多团队手里已经有一套鸿蒙原生组件库比如支付面板、扫一扫、地图卡片。RN项目要快速接入鸿蒙最高效的方式不是用JS重写而是把这些已有组件包一层鸿组件接口让前端能直接import。所以你会发现鸿组件开发并不是会不会写ArkUI这一个问题它其实是RN跨端能力在鸿蒙平台上的延伸。你在JS侧定义的组件名、属性、事件回调能不能准确落到原生侧直接决定了一个业务功能在鸿蒙设备上的体验。1.3 谁最需要仔细读这一篇我按读者背景分了三类你可以对号入座RN前端同学大部分时间写JS但一旦涉及鸿组件至少要能读懂原生侧在干嘛知道组件名是怎么对上的事件回调是怎么接的。鸿蒙原生开发同学熟悉ArkUI但不太清楚RN对原生组件有什么约束这篇会给你一条最小可行的接入路径。技术负责人需要判断哪些功能适合做成鸿组件哪些应该继续放在JS层避免团队把简单事情复杂化。2. 开发鸿组件前先把环境和工程结构理清楚2.1 工具链该怎么准备很多人一上来就打开IDE写组件结果卡在编译和签名上白白消耗热情。开发鸿组件前建议按这个顺序把环境理清楚。首先你必须有能跑通的HarmonyOS基础工程。不管是用官方的IDE建一个Ability工程还是直接在现有鸿蒙项目里加模块先在真机或模拟器上跑通一个Hello World确认签名、调试器都正常再做RN相关的东西。这一步的问题前置成本最低。其次RN侧要有一个能构建的工程并且已经接入了支持HarmonyOS的RN适配方案。这里有个容易忽略的点鸿蒙侧的RN适配不是RN官方默认自带的需要引入社区维护的适配库。这个适配库的版本和RN版本有严格的对应关系不能随便升。最后才是写组件。我的建议是不要一上来就调复杂的系统能力先在最简单的页面里跑通一个自定义鸿组件再叠加业务逻辑。2.2 工程目录怎么摆适配方案不同目录细节会有差异但通常你会看到类似这样的结构your-cross-app/ ├── src/ # RN业务代码 ├── package.json ├── harmony/ # 鸿蒙侧工程 │ ├── entry/ │ │ └── src/ │ │ └── main/ │ │ ├── ets/ │ │ │ ├── MainAbility.ets │ │ │ └── components/ │ │ │ └── FloatingButton.ets # 鸿组件实现 │ │ └── cpp/ # 部分桥接逻辑需要C参与 │ └── build-profile.json5RN源码放在src/下鸿侧代码单独放一个harmony/目录两边通过RN框架的桥接机制通信。这个目录划分的核心目的是让RN开发和鸿蒙原生开发的职责边界清晰前端同学不需要理解鸿侧工程的全貌只要知道组件在哪个目录注册即可。2.3 版本匹配是第一个大坑我在真实项目里踩过的第一个大坑就是版本。某天同事把RN从某个旧版本升级到较新版本鸿组件大面积失效页面直接白屏查了整整一天最后发现是适配库版本没跟着升两边接口对不上。这里给出一份版本匹配的基本原则适用于大多数RN适配场景关键项版本匹配原则常见问题RN核心版本尽量锁定不要频繁升级适配库一般滞后于官方版本升级RN需要同步更新适配方案鸿蒙适配库版本必须与当前RN版本严格对应版本错位会导致组件注册失败、事件回调收不到HarmonyOS API版本以目标真机系统版本为准API版本过高低版本真机上会调用失败过低则无法使用新特性我的经验是一旦团队内部确认了一套可用的版本组合就用锁定依赖的方式固定下来任何升级都要单独一个分支验证千万不要在业务代码里顺手升级RN版本。3. RN调用鸿组件的一次完整旅程3.1 从JSX到原生视图发生了什么很多前端同学对桥接的理解停留在RN会魔法般地把JS变成原生其实拆开看非常简单。你在JS里写了一个鸿组件FloatingButton title /RN内部的渲染器会先把这个组件标签解析成一个组件描述对象然后通过桥接层把我要创建名为FloatingButton的组件给它一个title属性这条消息发给原生侧。原生侧收到消息后去组件注册表里找有没有叫FloatingButton的鸿组件找到之后创建对应的ArkUI节点把title的值填进去再挂到页面的视图树上。这个过程里最核心的一句话是组件名是JS侧和原生侧之间唯一的频道。频道对不上消息就丢了。这跟打电话一模一样你拨的号码必须和对方登记的完全一致多一个空格、错一个大小写都不行。在旧架构里前端用requireNativeComponent来声明一个原生组件到了新架构会通过Codegen自动生成类型和桥接代码但本质上仍然需要有一个组件名在两边对齐。所以无论你用哪种方式第一步永远是确认组件名。3.2 属性和事件是怎么流动的鸿组件的交互无非两种JS给原生传数据原生给JS发通知。JS给原生传数据就是属性。不过属性不是每次都整包传输的RN会做diff只在属性变化时更新原生侧。这里有一个非常容易忽略的细节颜色值不能直接传字符串在JS侧要用processColor转成原生侧能理解的颜色数值布尔值、数值、字符串这些类型在桥接时比较直接但对象、数组会走序列化能不用尽量不用。原生给JS发通知就是事件。比如用户点了鸿组件里的按钮原生侧检测到点击动作把你的自定义事件名比如onPress连同参数一起通过桥接层送回JSJS侧拿出你绑定的回调函数执行。这个来回看起来简单但实际开发中80%的Bug都出在命名不一致上。原生侧叫onPressJS侧写成了onpress或者组件名大小写不一致都是让我抓狂过的低级错误。3.3 为什么不能把ArkUI组件直接搬进RN有的原生开发同学一开始会说ArkUI组件写起来不难我直接写一个放到RN里不行吗不行问题出在渲染范式上。ArkUI是声明式UI写组件时你描述的是最终界面应该长什么样而RN是命令式驱动它需要随时根据JS状态的变化去更新原生视图。两者之间需要一个适配层把RN的更新指令翻译成对手组件可执行的状态变更。举一个很实在的例子RN里一个组件可能因为父容器布局变化在某一帧被要求改变宽度。ArkUI组件自己并不会主动监听一个宽度属性然后去重新布局你需要在这个鸿组件里把布局参数映射到ArkUI对应的布局属性上。另外RN里常用的Flexbox布局和部分样式属性到了鸿组件侧不一定能自动生效。你需要像开发Android自定义View一样想清楚哪些样式由JS控制哪些样式由原生侧固定。一般我的做法是布局尺寸尽量由JS侧控制组件内部的固有形态比如圆形按钮的圆角由原生侧负责。4. 从零写一个鸿组件悬浮按钮4.1 先定义JS侧接口我拿一个最常见的悬浮按钮来当例子。业务需求是一个浮动的圆形按钮支持文字、背景色、禁用状态点击之后回调JS。JS侧的封装通常长这样import { requireNativeComponent, processColor } from react-native; import PropTypes from prop-types; const NativeFloatingButton requireNativeComponent(FloatingButton); export default function FloatingButton({ title, backgroundColor, disabled, onPress }) { return ( NativeFloatingButton title{title} backgroundColor{processColor(backgroundColor)} disabled{disabled} onPress{onPress} / ); } FloatingButton.propTypes { title: PropTypes.string, backgroundColor: PropTypes.number, disabled: PropTypes.bool, onPress: PropTypes.func, };注意我在这里做了几件事组件名FloatingButton必须和原生侧注册名完全一致背景色从CSS色值字符串转成了数值等会儿原生侧拿到的就是一个数字onPress是事件属性RN会识别到它是函数类型并把原生侧回调桥接过来。这段代码里我用的是RN旧架构的写法因为它足够直观能看清楚组件名、属性、事件三个关键点的映射关系。如果你的适配方案支持新架构的Codegen流程会更自动化但核心逻辑一样。4.2 原生ArkUI侧实现鸿蒙原生侧我写了一个对应组件核心是定义这个组件的UI形态和事件暴露方式。下面这段代码是示意不同适配方案的导出写法会有差异重点是理解结构Component export struct FloatingButton { title: string ; backgroundColor: number 0xFF5722; disabled: boolean false; onPress?: () void; build() { Button(this.title) .width(56) .height(56) .borderRadius(28) .backgroundColor(this.backgroundColor) .enabled(!this.disabled) .onClick(() { this.onPress this.onPress(); }) } }ArkUI声明式的特点在这里体现得很明显build()里直接描述按钮长什么样点击事件通过onPress回调抛给上层。但要注意这个FloatingButton.ets只是在ArkUI里定义了一个普通组件它要变成RN可使用的鸿组件还必须经过适配层的注册把FloatingButton这个ArkUI组件和RN侧那个NativeFloatingButton对应起来。具体怎么注册取决于你用哪个适配版本但逻辑是一致的提供一个工厂方法RN提到FloatingButton时系统就调这个工厂创建对应的ArkUI节点。4.3 注册和导出注册这一步是前后端命名的最终对账。你的适配库多半会提供一个组件注册表把你写的ArkUI组件登记进去比如// 示意写法具体以适配库提供的能力为准 registerNativeComponent( FloatingButton, FloatingButton );这里有几个细节组件名全局最好唯一不要用Button这种容易冲突的名字。我习惯加前缀比如HmFloatingButton从根上避免冲突。事件名的暴露要很明确。适配层需要知道这个组件有哪些事件要桥接给JS否则JS侧写了onPress也收不到。如果组件涉及测量逻辑还要在注册时绑定对应的LayoutManager之类的东西让RN知道怎么计算这个组件的宽高。总之注册这一步就是给桥接层一张通讯录。谁在哪个频道、能接收哪些数据、能发出哪些事件全部在这里登记。4.4 在页面里使用最后前端页面里的使用方式和一个普通RN组件没有任何区别import FloatingButton from ../components/FloatingButton; export default function HomeScreen() { const addNewRecord () { console.log(用户点了悬浮按钮); }; return ( View style{{ flex: 1 }} Text首页/Text FloatingButton title backgroundColor#FF5722 disabled{false} onPress{addNewRecord} / /View ); }这个过程跑通之后你会得到一个由ArkUI原生渲染的圆形悬浮按钮点击时能触发JS侧的回调。再到这一步鸿组件开发的最小闭环就算完成了。5. 调试鸿组件一份真实的排查链路5.1 把日志分成四段看我最开始调试鸿组件时习惯盯着JS控制台看结果经常一无所获。后来总结了一套四段日志法遇到问题先判断问题出在哪一段。日志段观察点典型工具JS构建阶段组件代码有没有被打包、有没有报语法错误Metro日志、JS控制台RN桥接层有没有创建原生组件的请求发出RN侧debug日志鸿组件创建阶段原生侧有没有收到createView指令鸿蒙系统日志、IDE日志事件回调阶段点击后事件有没有送回JSJS控制台、原生日志排查时按这个顺序往下走比漫无目的地打日志高效得多。5.2 一个黑块问题的完整排查过程我拿一个真实遇到过的场景讲页面正常渲染但鸿组件的位置出现了一个黑色矩形按钮内容没显示。第一步看JS控制台。结果No error说明JS侧组件调用没报错。第二步看RN桥接层日志。确认有创建FloatingButton的请求发出说明JS到桥接这一段是通的。第三步看鸿蒙系统日志。发现原生侧确实创建了一个节点但组件没有执行ArkUI的build()内容。这时候问题基本锁定了不是桥接失败是组件在原生侧没有处理属性更新。第四步检查属性。发现我在JS侧传了title字符串但原生组件内部声明的是title两边是一致的再看背景色我传的是processColor转出来的数值也没问题。最后把目光放在布局上发现父容器给了这个组件一个固定的宽高但组件内部Button用了默认的固定尺寸两者冲突导致内容被挤出了可视区域只剩下一个撑开的容器底色。修复方式也很简单外层容器不直接给定宽高让ArkUI的Button自己决定内容尺寸或者把外层容器背景色设为透明并给Button一个正确的layoutWeight。这个问题如果只看JS侧永远发现不了必须进到原生日志里。我把这段写下来是想说明一个经验鸿组件出现黑块、白块、空白九成九不是桥接断了而是原生侧布局或属性处理出了问题。5.3 生命周期和内存泄漏要提前防鸿组件不是一次性创建、永久存在的。在RN的列表中组件会随着滚动创建、销毁页面切换时组件也会经历完整的生命周期。这些时刻最容易出现两类问题一类是资源没有释放。比如你的鸿组件里监听了系统的传感器、创建了动画循环、持有了媒体播放器离开页面时必须主动释放。ArkUI组件通常有aboutToDisappear这类生命周期钩子一定要在这些钩子里做清理。另一类是事件回调把页面引用泄漏了。JS侧把onPress传给原生侧如果原生侧持有这个回调不放又持有页面的上下文整个页面就永远无法被回收。我的习惯是事件回调里不直接捕获页面对象在组件销毁时清空所有事件绑定封装的鸿组件尽量保持无状态让JS侧持有状态。6. 实测之后沉淀下来的几条规矩6.1 组件粒度别把什么东西都原生化接触鸿组件之后很多原生开发同学容易走另一个极端什么功能都往鸿组件里塞。普通标题、卡片阴影、简单的点击跳转这些东西用RN纯JS实现又简单又好维护没有必要做成鸿组件。我的判断标准是要么它是系统级能力鸿蒙原生侧才有要么它的渲染复杂度很高JS侧做会卡。符合这两条之一才值得投入鸿组件开发。普通按钮、列表项、展示卡片留在JS侧是更划算的选择。封装一个鸿组件的成本不只是写那几十行ArkUI代码还包括前后端联调、打包验证、不同鸿蒙系统版本的回归、后续维护时的双端同步。每一环都要花人力。6.2 属性设计不让桥接传大对象桥接层的性能瓶颈往往不在单次传输速度而在频率和体积。你传一个很大的对象过去序列化、拷贝、解析的消耗会随复杂度上升。所以给鸿组件设计属性时我会遵守几个简单原则能传string、number、boolean就不传对象必须传复杂结构时用扁平字段拆开而不是塞一个嵌套对象数组足够长时分批传递不要一次性全塞事件回调的参数也尽量精简只传业务真正需要的字段。有一次我在实际项目里传了一个带三层嵌套的对象结果每次状态更新都卡将近一百毫秒去掉嵌套、拆成扁平字段之后卡顿直接消失。属性设计看起来是小问题但量大了一样能拖垮体验。6.3 最小Demo先行再上复杂度不管业务需求多复杂我建议第一步永远是做一个最小Demo。哪怕只是让一个原生ArkUI按钮出现在RN页面里也值得先跑通。最小Demo的价值在于把整条链路拆干净JS声明、桥接传输、原生创建、事件回调。这四个环节任何一个有问题最小Demo都能最快暴露出来。Demo通了再往组件里加真实业务颜色、禁用态、图标、复杂的点击逻辑。每加一个属性就在原生侧验证一次。这个方法帮我挡掉过很多次大工程返工。有一次扫码组件直接在真实业务里开发结果回调一直不触发查了整整两天才发现是桥接层版本问题。后来凡是新鸿组件我都先在最小Demo里把交互链验证完再交给业务接入效率高很多。最后分享一个小技巧给鸿组件的事件名加统一前缀比如onHmPress、onHmScanResult能有效避免和RN内置事件名冲突。我在项目里吃过一次亏自定义事件起名太通用结果热更新时被框架的事件覆盖点击后JS侧毫无反应。从那以后我的每个鸿组件命名都带前缀这个习惯一直留到现在。