先说结论React Native应用要在鸿蒙系统上跑得顺路由这一层早晚得从“WebView式思维”切换到“原生Navigation思维”。NavigationBuilder恰恰是OpenHarmony社区为React Native鸿蒙化提供的关键衔接点它让JS侧能用接近ArkUI原生写法的方式声明页面、管理NavPathStack、完成跨页传参和转场控制。这篇文章我会从环境准备讲到核心API再给出一份可以直接抄的工程配置和踩坑清单。React Native以下简称RN在开源鸿蒙和商业鸿蒙上的适配已经不是“能不能跑”的阶段而是“跑得好不好”的阶段。有关心启动白屏的有问打断点不顺的也有不少人在问循环滚轮、图库调用这类基础组件能力。我的经验是业务组件适配大多靠社区包但路由是骨架骨架没搭对后面全难受。NavigationBuilder就是目前比较靠谱的一套骨架方案。这篇文章适合谁一是刚把RN工程迁移到鸿蒙、正在纠结页面跳转怎么做的同学二是已经在用但被白屏、参数丢失、返回栈混乱折磨的开发者三是对RN鸿蒙化架构感兴趣、想理解JS与ArkUI边界的人。如果你只是随手看一眼那记住一句话别再用JS侧堆栈模拟原生了把路由交给鸿蒙Navigation收益远比想象中大。1. 先搞清楚NavigationBuilder解决什么问题1.1 React Native在鸿蒙上是怎样跑起来的先理解RN鸿蒙化的基础架构。RN在Android上把JS线程跑在V8或Hermes里通过Bridge或者JSI与Java层通信在鸿蒙上社区的react-native-harmony也叫RNOH做了类似的事情把JS引擎对接到了ArkTS/ArkUI这一侧。JS代码仍然写业务逻辑渲染部分通过自定义组件映射到鸿蒙原生组件。这意味着你在JS里写View在鸿蒙上其实对应到了原生侧的RNCView你写Text对应到RNCText。页面容器也一样传统RN是JS自己维护Activity或Fragment栈但在鸿蒙上社区更推荐直接用ArkUI的Navigation容器因为那是鸿蒙亲儿子转场、生命周期、系统返回手势都原生支持。这里就引出了NavigationBuilder它在JS侧提供了一个声明式接口让你可以通过builder函数把一个RN组件“包装”成鸿蒙NavDestination的内容。也就是说你在JS里写一个页面但实际上这个页面是被鸿蒙Navigation统一管理的。1.2 为什么不用普通RN路由而要用NavigationBuilder很多从Android/iOS转过来的RN开发者习惯用react-navigation的StackNavigator管理页面栈。这套方案在双端确实成熟但在鸿蒙上会遇到几个实际问题第一react-navigation的stack在鸿蒙上如果走纯JS实现页面切换只是内容“看起来换了”但系统返回手势、转场动画、内存回收都没有跟鸿蒙原生对齐体验很“套壳”。第二鸿蒙的Navigation有NavPathStack这个统一的路由栈页面生命周期和组件状态天然受系统管理JS侧如果另起炉灶等于和系统能力割裂。第三鸿蒙系统级返回、应用级返回、跨设备迁移这些能力都是围绕原生Navigation设计的JS侧不用它将来扩展就很吃力。所以NavigationBuilder不是“又一个路由库”而是JS与ArkUI导航能力对齐的桥梁。它在JS侧负责声明页面内容在原生侧由Navigation统一调度页面栈是原生栈不是JS模拟栈。2. 开发环境准备与工程接入2.1 初始化React Native鸿蒙工程前面铺垫了这么多原理现在讲落地。首先要有一个能跑的RN鸿蒙工程。社区推荐的脚手架是react-native-oh/react-native-harmony它提供了库源码、模板工程和配套的cli。我以实际项目为例大致流程是这样# 使用社区cli初始化工程会根据你的RN版本生成对应的arkts工程目录 npx react-native-oh/react-native-harmonylatest初始化后会生成一个包含harmony子目录的RN工程。这个harmony目录就是鸿蒙原生工程里面能直接用DevEco Studio打开。注意初始化时它会校验你的Node、JDK、ohpm环境提前装好DevEco Studio和ohpm会省掉很多麻烦。工程初始化完先做一次最小验证把应用跑到鸿蒙模拟器或真机上确认RN的红色错误框和Hello World都能正常展示。这一步过了再碰路由否则后面出了问题很难分清是环境问题还是路由问题。2.2 安装并接入harmonynavigation依赖包这里我要说明一下NavigationBuilder对应社区包是react-native-oh-tpl/react-native-harmonynavigation它把ArkUI的Navigation能力封装成RN组件同时暴露了NavigationBuilder相关接口。安装方式npm install react-native-oh-tpl/react-native-harmonynavigation cd harmony ohpm install安装完后需要在鸿蒙工程的entry/src/main/ets/pages/Index.ets里做原生侧配置把Navigation作为根容器组件Navigation() { // 这里放首页内容通常是一个RN宿主组件 RNNavigationBuilderPage() } .navDestination(this.pageMap)pageMap是关键它定义了路由名与页面构建函数的映射关系。NavigationBuilder在JS侧通过builder函数创建NavDestination内容原生侧拿到builder结果后渲染到对应页面。理解这一点后后面配置路由表就顺了。2.3 鸿蒙侧路由表配置RN鸿蒙化的工程里路由表不是一个JS文件那么简单它涉及main_pages.json和module.json5里的配置。我踩过最大的坑是JS侧注册的路由名和原生侧路由表对不上跳转时直接白屏而且原生日志只给一个不痛不痒的warning。建议按这个顺序检查在entry/src/main/resources/base/profile/main_pages.json里注册“入口页面”这个入口本身必须存在否则应用启动就挂了。在module.json5的abilities里确认routerMap配置正确把NavigationBuilder组件所属的PageAbility加进去。在鸿蒙工程里维护一个PageRoutes.ets统一导出所有builder函数方便后续排查。如果你嫌麻烦直接把所有页面都丢给NavigationBuilder管理入口页也走它这样路由表只有一个来源不容易错。3. NavigationBuilder核心API与路由构建实战3.1 核心概念NavPathStack、Navigation、NavDestination在鸿蒙ArkUI里Navigation是导航容器NavPathStack是路由栈对象NavDestination是具体页面内容。它们的关系可以简单理解为Navigation是一个大抽屉NavPathStack是抽屉里的文件目录NavDestination是每份文件本身。NavigationBuilder在RN侧把这套模型搬了过来。JS侧创建页面时不再直接返回一个普通组件而是通过builder函数声明这个页面的NavDestination配置包括页面名称、页面内容、转场动画、是否支持系统返回等。示例import { NavigationBuilder, NavPathStack } from react-native-oh-tpl/react-native-harmonynavigation; export function buildHomePage(stack: NavPathStack) { return NavigationBuilder() .name(Home) .onBackPressed(() { // 返回拦截逻辑返回true表示消费掉返回事件 return false; }) .build((ctx) HomeScreen navigation{ctx} /); }这里要理解NavigationBuilder()返回的是一个链式配置对象不是直接返回JSX。它做的事情是“描述一个页面”最终由系统决定什么时候渲染、怎么渲染。这也是它和react-navigation最大的差异你在React Navigation里创建的是screen组件的映射但在这个方案里你创建的是原生导航目的地的描述。3.2 NavigationBuilder页面构建与路由跳转页面构建好之后跳转通过NavPathStack来操作。我项目里的一个做法是在根组件里创建一个全局的NavPathStack实例然后通过Context或者全局变量传给每一个页面。示例const stack new NavPathStack(); // 在某个按钮事件中 stack.pushPathByName(DetailPage, { id: 42, title: 测试 }); // 返回上一页 stack.pop(); // 返回首页 stack.popToName(Home); // 清除所有页面 stack.clear();有同学会问为什么不直接在组件里useNavigation()拿导航实例在RN鸿蒙环境里因为页面渲染时机和原生栈不完全同步全局维护一个stack对象反而更稳尤其在事件回调里比如网络请求成功后跳转不会遇到“navigation不在屏幕前”的警告。push的时候可以传任意可序列化的参数。注意参数不是通过JS对象的引用传递的而是会复制到原生侧再回传。所以不要把函数、Date对象、循环引用的对象塞进去否则会丢东西或者报错。3.3 跨页面传参与返回结果跨页传参是路由使用频率最高的能力之一。NavigationBuilder的方案里参数在push时传入在目标页面通过ctx.pathInfo.param拿到。例如stack.pushPathByName(DetailPage, { goodsId: sku_10086, from: home_banner, ts: Date.now(), });在DetailPage里export function buildDetailPage(stack: NavPathStack) { return NavigationBuilder() .name(DetailPage) .build((ctx) { const params ctx.pathInfo.param as { goodsId: string; from?: string }; return DetailScreen goodsId{params.goodsId} /; }); }这里有个细节和Web路由不同参数是在“构建页面”时读取的如果页面已经在栈中你再次push同名页面会新建一个实例而不是复用旧实例。想要复用栈里的页面用pushPathByName前先popToName或者用replacePathByName替换当前页。需要返回结果给上一个页面时我建议在目标页pop前把结果存到全局Store比如Zustand或Redux中然后上一页在onWillAppear或onDidAppear生命周期里读取。NavigationBuilder虽然暴露了生命周期钩子但JS侧拿返回值没有原生那么顺手全局状态反而更简单可靠。3.4 自定义转场动画与Tab页签场景默认的跳转动画是鸿蒙系统标准的页面转场多数业务场景够了。但如果你要做营销活动页、半模态弹窗、仿iOS的Modal效果可以用mode和transition配置NavigationBuilder() .name(StorePopup) .mode(NavigationMode.Modal) // 以模态方式展示 .transition({ type: TransitionType.Push, duration: 300, curve: Curve.EaseInOut, }) .build((ctx) StorePopup /);有几种常见的组合可以自由拼页面详情mode默认压栈式跳转支付弹窗mode Modal从底部弹出全屏广告mode Dialog透明背景浮层Tab场景稍微特殊一点。NavigationBuilder管的是“全屏页面栈”而Tab切换属于页面内组件切换。我的实践是分两类路由一类是Tab容器自身作为Navigation的根页面另一类是Tab里的子页面继续用builder声明。Tab容器内部再放ArkUI的Tabs组件或者在JS侧用自定义TabBar都不冲突。关键在于一个被NavDestination包裹的页面里可以继续嵌套任意RN组件和容器NavigationBuilder不会限制子页面内部的导航方式。4. 与常见RN路由方案对比与选型建议4.1 对比React NavigationReact Navigation是目前RN社区最常用的路由方案在Android/iOS上表现都不错。但在鸿蒙适配中它遇到了一个天然瓶颈React Navigation的StackNavigator高度依赖原生栈实现在鸿蒙侧要么自己桥接UINavigationController对应物即ArkUI的Navigation要么退化为JS模拟栈。JS模拟栈在纯RN双端时代够用但在鸿蒙上会很别扭。因为系统返回手势、后台回收、转场动画这些都是由鸿蒙弹栈控制的JS模拟栈很难拦截到底层事件。NavigationBuilder直接建立在ArkUI Navigation上等于把JS页面的生命周期和系统导航能力绑定这一点是React Navigation短期难以替代的。不过也要承认React Navigation生态成熟深链配置、State持久化、tab嵌套都有现成方案。如果你团队对鸿蒙体验要求不高只求快速上线React Navigation也不是不能用。但只要是做纯血鸿蒙版本尽量别把宝押在JS栈模拟上。4.2 对比react-native-navigation或原生桥接react-native-navigationWix版在iOS/Android上以原生页面栈为卖点但在鸿蒙上并没有官方支持。你想用的话只能自己写桥接层把RN页面封装成鸿蒙组件再手动管理ArkUI Navigation。这个工程量大到足够劝退。另一种常见做法是“原生页面RN混编”鸿蒙侧用Navigation管理原生页面某些页面内部再加载RN容器。这是可行的很多大型App也确实这么做。但NavigationBuilder的作用是“纯RN页面也要走原生Navigation”如果你打算混编这个包对你有用如果你打算原生壳只放一个全屏RN那路由完全在RN内部其实不需要NavigationBuilder。我的建议是优先明确团队的页面容器策略。如果80%的界面是RN实现那么全量使用NavigationBuilder整体统一如果只有少数H5/RN页面嵌入那就分开管理不要混用两套栈不然返回手势和页面栈会打架。4.3 什么场景建议选NavigationBuilder从实际项目角度我认为这几类场景比较适合从零开始做RN鸿蒙版没有历史包袱可以直接把路由架构设计成NavigationBuilder。现有RN工程要做鸿蒙适配页面层级清晰愿意花时间改造路由。项目对系统返回手势、交互动画、多任务切换体验有较高要求。团队未来可能深入混编开发需要一套能从RN平滑过渡到ArkUI的导航架构。反之如果团队只是验证RN在鸿蒙上能否跑通先别上这套浪费成本。先跑Hello World再跑业务模块最后才轮到路由架构优化。5. 常见问题排查与避坑5.1 启动白屏的问题白屏是我被问得最多的问题而且多数不是路由本身的锅而是初始化顺序的问题。我遇到过的情况大致有三种第一种是NavigationBuilder构建页面时RN的根组件还没挂载好。解决方案是等原生侧onLoad事件触发后再执行页面构建不要直接在Index.ets里同步调用builder。第二种是路由名对不上。之前在2.3里提到的路由表配置如果JS侧注册的name和原生侧期望的名字不一致系统会找不到页面表现就是白屏加一个warning日志。建议给每个页面写一个常量enumJS端和ArkTS端共用一份命名源避免手滑拼错。第三种是鸿蒙模拟器开硬件加速时的渲染问题。这种白屏比较随机切真机或关掉模拟器的部分硬件加速选项通常能解决。5.2 构建失败与so库找不到RN鸿蒙化工程在DevEco Studio里构建时经常碰到“so库找不到”或者“签名不一致”的问题。很多情况下是因为初始化工程后没有执行ohpm安装或者原生依赖和JS依赖版本不匹配。我的经验是包管理器版本必须锁死尤其是react-native-harmony、react-native-oh-tpl/react-native-harmonynavigation和react-native三者之间的版本。社区一般会在发布页写明兼容版本升级时不要单方面升级某一方。构建前先清理cd harmony rm -rf .hvigor .cxx build ohpm install再重新在DevEco Studio里Sync基本能解决90%的构建问题。5.3 路由参数序列化异常跨页传参如果出现参数丢失或类型不对先确认是否使用了可序列化数据类型。NavigationBuilder的路由参数要经过桥接层传递基本类型、字符串、简单对象都没问题但像Uint8Array、BigInt、嵌套太深的对象、带自定义原型链的对象都可能出问题。另外参数名不要用undefined做value。桥接层对undefined的处理比较粗某些版本序列化后直接丢字段到了目标页面变成null。我习惯在push前做一个参数清洗function sanitizeParams(params: Recordstring, any) { const result: Recordstring, any {}; for (const key of Object.keys(params)) { if (params[key] ! undefined) { result[key] params[key]; } } return result; }5.4 性能优化建议NavigationBuilder把一个RN页面包装成NavDestination时每次页面出现都可能触发一次RN组件的重新挂载或可见性变化。性能上我有几个建议第一列表页和详情页之间跳转不要在页面build函数里做高开销计算把数据预取放在进入页面前或全局Store中。第二对于不需要动画的页面把转场动画时长缩短或直接关闭能显著减少掉帧。第三关注onWillDisappear钩子及时取消定时器、销毁地图实例或视频播放器避免页面隐藏后仍然消耗性能。配置示例.onWillDisappear(() { // 取消当前页面的异步任务 cancelPendingRequests(); // 暂停视频播放等 player?.pause(); })6. 最后说点实在的我在实际项目中体会到NavigationBuilder这类方案最容易被低估的地方不是API本身而是它强制你改变对“页面”的认知。以前写RN路由潜意识里觉得页面是JS组件路由是JS字典换成NavigationBuilder之后页面先是一个原生导航目的地然后才是RN组件容器。这个思维转换过来后面处理返回手势、转场、内存回收都顺了。如果你刚上手我建议先做一个最小Demo一个Home页、一个Detail页、一个Modal弹窗页把push、pop、传参、返回这四件事跑通然后才往业务里铺开。路由层值得多花时间因为它出错时往往不报红而是悄无声息地白屏或栈错乱排查成本特别高。最后再分享一个小技巧在开发阶段给NavPathStack加一层日志代理push、pop、replace都打一条带时间戳的日志出了问题回看日志就能定位是JS侧调用问题还是原生侧渲染问题。这个习惯帮我省过好几个下午。
React Native鸿蒙化路由：NavigationBuilder让JS页面享受原生Navigation体验
先说结论React Native应用要在鸿蒙系统上跑得顺路由这一层早晚得从“WebView式思维”切换到“原生Navigation思维”。NavigationBuilder恰恰是OpenHarmony社区为React Native鸿蒙化提供的关键衔接点它让JS侧能用接近ArkUI原生写法的方式声明页面、管理NavPathStack、完成跨页传参和转场控制。这篇文章我会从环境准备讲到核心API再给出一份可以直接抄的工程配置和踩坑清单。React Native以下简称RN在开源鸿蒙和商业鸿蒙上的适配已经不是“能不能跑”的阶段而是“跑得好不好”的阶段。有关心启动白屏的有问打断点不顺的也有不少人在问循环滚轮、图库调用这类基础组件能力。我的经验是业务组件适配大多靠社区包但路由是骨架骨架没搭对后面全难受。NavigationBuilder就是目前比较靠谱的一套骨架方案。这篇文章适合谁一是刚把RN工程迁移到鸿蒙、正在纠结页面跳转怎么做的同学二是已经在用但被白屏、参数丢失、返回栈混乱折磨的开发者三是对RN鸿蒙化架构感兴趣、想理解JS与ArkUI边界的人。如果你只是随手看一眼那记住一句话别再用JS侧堆栈模拟原生了把路由交给鸿蒙Navigation收益远比想象中大。1. 先搞清楚NavigationBuilder解决什么问题1.1 React Native在鸿蒙上是怎样跑起来的先理解RN鸿蒙化的基础架构。RN在Android上把JS线程跑在V8或Hermes里通过Bridge或者JSI与Java层通信在鸿蒙上社区的react-native-harmony也叫RNOH做了类似的事情把JS引擎对接到了ArkTS/ArkUI这一侧。JS代码仍然写业务逻辑渲染部分通过自定义组件映射到鸿蒙原生组件。这意味着你在JS里写View在鸿蒙上其实对应到了原生侧的RNCView你写Text对应到RNCText。页面容器也一样传统RN是JS自己维护Activity或Fragment栈但在鸿蒙上社区更推荐直接用ArkUI的Navigation容器因为那是鸿蒙亲儿子转场、生命周期、系统返回手势都原生支持。这里就引出了NavigationBuilder它在JS侧提供了一个声明式接口让你可以通过builder函数把一个RN组件“包装”成鸿蒙NavDestination的内容。也就是说你在JS里写一个页面但实际上这个页面是被鸿蒙Navigation统一管理的。1.2 为什么不用普通RN路由而要用NavigationBuilder很多从Android/iOS转过来的RN开发者习惯用react-navigation的StackNavigator管理页面栈。这套方案在双端确实成熟但在鸿蒙上会遇到几个实际问题第一react-navigation的stack在鸿蒙上如果走纯JS实现页面切换只是内容“看起来换了”但系统返回手势、转场动画、内存回收都没有跟鸿蒙原生对齐体验很“套壳”。第二鸿蒙的Navigation有NavPathStack这个统一的路由栈页面生命周期和组件状态天然受系统管理JS侧如果另起炉灶等于和系统能力割裂。第三鸿蒙系统级返回、应用级返回、跨设备迁移这些能力都是围绕原生Navigation设计的JS侧不用它将来扩展就很吃力。所以NavigationBuilder不是“又一个路由库”而是JS与ArkUI导航能力对齐的桥梁。它在JS侧负责声明页面内容在原生侧由Navigation统一调度页面栈是原生栈不是JS模拟栈。2. 开发环境准备与工程接入2.1 初始化React Native鸿蒙工程前面铺垫了这么多原理现在讲落地。首先要有一个能跑的RN鸿蒙工程。社区推荐的脚手架是react-native-oh/react-native-harmony它提供了库源码、模板工程和配套的cli。我以实际项目为例大致流程是这样# 使用社区cli初始化工程会根据你的RN版本生成对应的arkts工程目录 npx react-native-oh/react-native-harmonylatest初始化后会生成一个包含harmony子目录的RN工程。这个harmony目录就是鸿蒙原生工程里面能直接用DevEco Studio打开。注意初始化时它会校验你的Node、JDK、ohpm环境提前装好DevEco Studio和ohpm会省掉很多麻烦。工程初始化完先做一次最小验证把应用跑到鸿蒙模拟器或真机上确认RN的红色错误框和Hello World都能正常展示。这一步过了再碰路由否则后面出了问题很难分清是环境问题还是路由问题。2.2 安装并接入harmonynavigation依赖包这里我要说明一下NavigationBuilder对应社区包是react-native-oh-tpl/react-native-harmonynavigation它把ArkUI的Navigation能力封装成RN组件同时暴露了NavigationBuilder相关接口。安装方式npm install react-native-oh-tpl/react-native-harmonynavigation cd harmony ohpm install安装完后需要在鸿蒙工程的entry/src/main/ets/pages/Index.ets里做原生侧配置把Navigation作为根容器组件Navigation() { // 这里放首页内容通常是一个RN宿主组件 RNNavigationBuilderPage() } .navDestination(this.pageMap)pageMap是关键它定义了路由名与页面构建函数的映射关系。NavigationBuilder在JS侧通过builder函数创建NavDestination内容原生侧拿到builder结果后渲染到对应页面。理解这一点后后面配置路由表就顺了。2.3 鸿蒙侧路由表配置RN鸿蒙化的工程里路由表不是一个JS文件那么简单它涉及main_pages.json和module.json5里的配置。我踩过最大的坑是JS侧注册的路由名和原生侧路由表对不上跳转时直接白屏而且原生日志只给一个不痛不痒的warning。建议按这个顺序检查在entry/src/main/resources/base/profile/main_pages.json里注册“入口页面”这个入口本身必须存在否则应用启动就挂了。在module.json5的abilities里确认routerMap配置正确把NavigationBuilder组件所属的PageAbility加进去。在鸿蒙工程里维护一个PageRoutes.ets统一导出所有builder函数方便后续排查。如果你嫌麻烦直接把所有页面都丢给NavigationBuilder管理入口页也走它这样路由表只有一个来源不容易错。3. NavigationBuilder核心API与路由构建实战3.1 核心概念NavPathStack、Navigation、NavDestination在鸿蒙ArkUI里Navigation是导航容器NavPathStack是路由栈对象NavDestination是具体页面内容。它们的关系可以简单理解为Navigation是一个大抽屉NavPathStack是抽屉里的文件目录NavDestination是每份文件本身。NavigationBuilder在RN侧把这套模型搬了过来。JS侧创建页面时不再直接返回一个普通组件而是通过builder函数声明这个页面的NavDestination配置包括页面名称、页面内容、转场动画、是否支持系统返回等。示例import { NavigationBuilder, NavPathStack } from react-native-oh-tpl/react-native-harmonynavigation; export function buildHomePage(stack: NavPathStack) { return NavigationBuilder() .name(Home) .onBackPressed(() { // 返回拦截逻辑返回true表示消费掉返回事件 return false; }) .build((ctx) HomeScreen navigation{ctx} /); }这里要理解NavigationBuilder()返回的是一个链式配置对象不是直接返回JSX。它做的事情是“描述一个页面”最终由系统决定什么时候渲染、怎么渲染。这也是它和react-navigation最大的差异你在React Navigation里创建的是screen组件的映射但在这个方案里你创建的是原生导航目的地的描述。3.2 NavigationBuilder页面构建与路由跳转页面构建好之后跳转通过NavPathStack来操作。我项目里的一个做法是在根组件里创建一个全局的NavPathStack实例然后通过Context或者全局变量传给每一个页面。示例const stack new NavPathStack(); // 在某个按钮事件中 stack.pushPathByName(DetailPage, { id: 42, title: 测试 }); // 返回上一页 stack.pop(); // 返回首页 stack.popToName(Home); // 清除所有页面 stack.clear();有同学会问为什么不直接在组件里useNavigation()拿导航实例在RN鸿蒙环境里因为页面渲染时机和原生栈不完全同步全局维护一个stack对象反而更稳尤其在事件回调里比如网络请求成功后跳转不会遇到“navigation不在屏幕前”的警告。push的时候可以传任意可序列化的参数。注意参数不是通过JS对象的引用传递的而是会复制到原生侧再回传。所以不要把函数、Date对象、循环引用的对象塞进去否则会丢东西或者报错。3.3 跨页面传参与返回结果跨页传参是路由使用频率最高的能力之一。NavigationBuilder的方案里参数在push时传入在目标页面通过ctx.pathInfo.param拿到。例如stack.pushPathByName(DetailPage, { goodsId: sku_10086, from: home_banner, ts: Date.now(), });在DetailPage里export function buildDetailPage(stack: NavPathStack) { return NavigationBuilder() .name(DetailPage) .build((ctx) { const params ctx.pathInfo.param as { goodsId: string; from?: string }; return DetailScreen goodsId{params.goodsId} /; }); }这里有个细节和Web路由不同参数是在“构建页面”时读取的如果页面已经在栈中你再次push同名页面会新建一个实例而不是复用旧实例。想要复用栈里的页面用pushPathByName前先popToName或者用replacePathByName替换当前页。需要返回结果给上一个页面时我建议在目标页pop前把结果存到全局Store比如Zustand或Redux中然后上一页在onWillAppear或onDidAppear生命周期里读取。NavigationBuilder虽然暴露了生命周期钩子但JS侧拿返回值没有原生那么顺手全局状态反而更简单可靠。3.4 自定义转场动画与Tab页签场景默认的跳转动画是鸿蒙系统标准的页面转场多数业务场景够了。但如果你要做营销活动页、半模态弹窗、仿iOS的Modal效果可以用mode和transition配置NavigationBuilder() .name(StorePopup) .mode(NavigationMode.Modal) // 以模态方式展示 .transition({ type: TransitionType.Push, duration: 300, curve: Curve.EaseInOut, }) .build((ctx) StorePopup /);有几种常见的组合可以自由拼页面详情mode默认压栈式跳转支付弹窗mode Modal从底部弹出全屏广告mode Dialog透明背景浮层Tab场景稍微特殊一点。NavigationBuilder管的是“全屏页面栈”而Tab切换属于页面内组件切换。我的实践是分两类路由一类是Tab容器自身作为Navigation的根页面另一类是Tab里的子页面继续用builder声明。Tab容器内部再放ArkUI的Tabs组件或者在JS侧用自定义TabBar都不冲突。关键在于一个被NavDestination包裹的页面里可以继续嵌套任意RN组件和容器NavigationBuilder不会限制子页面内部的导航方式。4. 与常见RN路由方案对比与选型建议4.1 对比React NavigationReact Navigation是目前RN社区最常用的路由方案在Android/iOS上表现都不错。但在鸿蒙适配中它遇到了一个天然瓶颈React Navigation的StackNavigator高度依赖原生栈实现在鸿蒙侧要么自己桥接UINavigationController对应物即ArkUI的Navigation要么退化为JS模拟栈。JS模拟栈在纯RN双端时代够用但在鸿蒙上会很别扭。因为系统返回手势、后台回收、转场动画这些都是由鸿蒙弹栈控制的JS模拟栈很难拦截到底层事件。NavigationBuilder直接建立在ArkUI Navigation上等于把JS页面的生命周期和系统导航能力绑定这一点是React Navigation短期难以替代的。不过也要承认React Navigation生态成熟深链配置、State持久化、tab嵌套都有现成方案。如果你团队对鸿蒙体验要求不高只求快速上线React Navigation也不是不能用。但只要是做纯血鸿蒙版本尽量别把宝押在JS栈模拟上。4.2 对比react-native-navigation或原生桥接react-native-navigationWix版在iOS/Android上以原生页面栈为卖点但在鸿蒙上并没有官方支持。你想用的话只能自己写桥接层把RN页面封装成鸿蒙组件再手动管理ArkUI Navigation。这个工程量大到足够劝退。另一种常见做法是“原生页面RN混编”鸿蒙侧用Navigation管理原生页面某些页面内部再加载RN容器。这是可行的很多大型App也确实这么做。但NavigationBuilder的作用是“纯RN页面也要走原生Navigation”如果你打算混编这个包对你有用如果你打算原生壳只放一个全屏RN那路由完全在RN内部其实不需要NavigationBuilder。我的建议是优先明确团队的页面容器策略。如果80%的界面是RN实现那么全量使用NavigationBuilder整体统一如果只有少数H5/RN页面嵌入那就分开管理不要混用两套栈不然返回手势和页面栈会打架。4.3 什么场景建议选NavigationBuilder从实际项目角度我认为这几类场景比较适合从零开始做RN鸿蒙版没有历史包袱可以直接把路由架构设计成NavigationBuilder。现有RN工程要做鸿蒙适配页面层级清晰愿意花时间改造路由。项目对系统返回手势、交互动画、多任务切换体验有较高要求。团队未来可能深入混编开发需要一套能从RN平滑过渡到ArkUI的导航架构。反之如果团队只是验证RN在鸿蒙上能否跑通先别上这套浪费成本。先跑Hello World再跑业务模块最后才轮到路由架构优化。5. 常见问题排查与避坑5.1 启动白屏的问题白屏是我被问得最多的问题而且多数不是路由本身的锅而是初始化顺序的问题。我遇到过的情况大致有三种第一种是NavigationBuilder构建页面时RN的根组件还没挂载好。解决方案是等原生侧onLoad事件触发后再执行页面构建不要直接在Index.ets里同步调用builder。第二种是路由名对不上。之前在2.3里提到的路由表配置如果JS侧注册的name和原生侧期望的名字不一致系统会找不到页面表现就是白屏加一个warning日志。建议给每个页面写一个常量enumJS端和ArkTS端共用一份命名源避免手滑拼错。第三种是鸿蒙模拟器开硬件加速时的渲染问题。这种白屏比较随机切真机或关掉模拟器的部分硬件加速选项通常能解决。5.2 构建失败与so库找不到RN鸿蒙化工程在DevEco Studio里构建时经常碰到“so库找不到”或者“签名不一致”的问题。很多情况下是因为初始化工程后没有执行ohpm安装或者原生依赖和JS依赖版本不匹配。我的经验是包管理器版本必须锁死尤其是react-native-harmony、react-native-oh-tpl/react-native-harmonynavigation和react-native三者之间的版本。社区一般会在发布页写明兼容版本升级时不要单方面升级某一方。构建前先清理cd harmony rm -rf .hvigor .cxx build ohpm install再重新在DevEco Studio里Sync基本能解决90%的构建问题。5.3 路由参数序列化异常跨页传参如果出现参数丢失或类型不对先确认是否使用了可序列化数据类型。NavigationBuilder的路由参数要经过桥接层传递基本类型、字符串、简单对象都没问题但像Uint8Array、BigInt、嵌套太深的对象、带自定义原型链的对象都可能出问题。另外参数名不要用undefined做value。桥接层对undefined的处理比较粗某些版本序列化后直接丢字段到了目标页面变成null。我习惯在push前做一个参数清洗function sanitizeParams(params: Recordstring, any) { const result: Recordstring, any {}; for (const key of Object.keys(params)) { if (params[key] ! undefined) { result[key] params[key]; } } return result; }5.4 性能优化建议NavigationBuilder把一个RN页面包装成NavDestination时每次页面出现都可能触发一次RN组件的重新挂载或可见性变化。性能上我有几个建议第一列表页和详情页之间跳转不要在页面build函数里做高开销计算把数据预取放在进入页面前或全局Store中。第二对于不需要动画的页面把转场动画时长缩短或直接关闭能显著减少掉帧。第三关注onWillDisappear钩子及时取消定时器、销毁地图实例或视频播放器避免页面隐藏后仍然消耗性能。配置示例.onWillDisappear(() { // 取消当前页面的异步任务 cancelPendingRequests(); // 暂停视频播放等 player?.pause(); })6. 最后说点实在的我在实际项目中体会到NavigationBuilder这类方案最容易被低估的地方不是API本身而是它强制你改变对“页面”的认知。以前写RN路由潜意识里觉得页面是JS组件路由是JS字典换成NavigationBuilder之后页面先是一个原生导航目的地然后才是RN组件容器。这个思维转换过来后面处理返回手势、转场、内存回收都顺了。如果你刚上手我建议先做一个最小Demo一个Home页、一个Detail页、一个Modal弹窗页把push、pop、传参、返回这四件事跑通然后才往业务里铺开。路由层值得多花时间因为它出错时往往不报红而是悄无声息地白屏或栈错乱排查成本特别高。最后再分享一个小技巧在开发阶段给NavPathStack加一层日志代理push、pop、replace都打一条带时间戳的日志出了问题回看日志就能定位是JS侧调用问题还是原生侧渲染问题。这个习惯帮我省过好几个下午。
