HarmonyOS ArkTS 页面路由 (@ohos.router) 完整指南HarmonyOS ArkTS 页面路由

HarmonyOS ArkTS 页面路由 (@ohos.router) 完整指南

在 ArkTS/ArkUI 中，页面路由 是指如何在不同页面之间进行 跳转（Navigate） 、返回（Back） 、以及 传递数据（Params） 的能力。它是构建多页面应用基础。官方提供了 @ohos.router 模块用于页面路由管理，但需要注意：该模块 不再被推荐用于主导航架构（建议使用 Navigation）。华为开发者

一、什么是路由（Routing）

在应用开发里，路由就是定义页面之间如何跳转和传数据的机制。它负责：

按页面路径或 URL 启动另一个页面
在页面之间传递参数
支持返回栈行为

在 ArkTS 中，传统的 路由模块是 @ohos.router。华为开发者

二、官方态度：不推荐使用 Router

在官方最新指南中已经明确指出：

@ohos.router 不再作为主要导航机制推荐，未来导航将由 Navigation + NavPathStack 完全替代，后者具备更现代、更统一的栈控制能力。华为开发者

虽然 Router 仍然可用，但仅适合：

简单跳转场景
历史兼容代码维护
非栈式导航需求

三、Router 模块工作原理

@ohos.router 的设计借鉴了传统前端/移动开发路由思路：

通过 URL/路径识别目标页面
在跳转时可带 query 参数
跳转逻辑分为“启动新页面”和“返回上一页”两种基本行为华为开发者

常见的核心功能包括：

功能	路由行为
Push	打开一个新页面
Back	返回上一页
Replace	替换当前页面（部分框架支持）
Params	传递数据给目标页面

四、Router 基本用法示例

在 ArkTS 页面里引入 Router 并执行跳转：

 import router from '@ohos.router';
 
 @Entry
 @Component
 struct Index {
   onClickNext() {
     router.pushUrl({ url: 'pages/Second' });
   }
 
   build() {
     Column() {
       Button("下一页").onClick(() => this.onClickNext());
     }
   }
 }

🔹 解释：

router.pushUrl({ url: 'pages/Second' }) 会启动一个新页面 Second。
这个 URL 必须在项目的 main_pages.json（项目配置）中注册好页面路径。维基百科

五、路由参数传递

Router 支持在跳转时通过 URL query 传递参数。例如：

 router.pushUrl({ url: 'pages/Detail?userId=123&name=Alice' });

目标页面可以在初始化阶段解析 query 并读取参数。

Router 的参数机制通常是通过字符型 query 传递，不支持复杂对象结构。 如果需要复杂参数，推荐使用 Navigation 方案。华为开发者

六、返回与栈行为

Router 也支持页面返回操作：

 router.back();

这会触发当前页面返回到上一个页面。

Router 的返回行为是基于浏览器式堆栈，不够灵活，不支持像 Navigation 那样的栈插入/替换/深度控制。华为开发者

七、何时使用 Router，何时用 Navigation？

八、Router 与 Navigation 的本质区别

特性	Router (`@ohos.router`)	Navigation
路由模型	URL + query	栈 + 页面组件
参数传递方式	Query 字符串	对象参数
栈管理	简单	全栈 & 嵌套
复杂跳转	不支持	支持 push/pop/replace 等
响应式布局	依赖外部手段	内建 Adaptive 模式
推荐使用	❌	✅ 官方推荐华为开发者

🛠 九、Router 使用限制与注意点

必须在配置文件中注册所有页面路径 Router 使用的 URL 对应开发时的页面路径配置文件（如 main_pages.json）。否则跳转无效。维基百科
不支持对象参数直传 Router 只能传 query 数据，需要手工解析再映射成对象字段。
不支持栈深度控制 Router 仅支持 pushUrl/back，不支持 replace/popToRoot 等更细粒度操作。
Navigation 越来越被推荐 在官方 FAQ 中明确推荐使用 Navigation 替代 Router 作为主导航方案。华为开发者

十、总结

虽然 @ohos.router 仍然可用于 ArkTS 应用管理基本页面跳转，但它已经 不再是官方推荐的路由方案。现代 HarmonyOS 应用开发更倾向于使用：

Navigation + NavPathStack ➤ 更强的参数传递能力 ➤ 更灵活的栈控制 ➤ 更适合复杂页面场景 ➤ 官方推荐架构华为开发者

HarmonyOS ArkTS 页面路由 (@ohos.router) 完整指南