前言页面跳转是移动应用最基础的能力之一。HarmonyOS 提供了kit.ArkUI中的router模块来实现页面导航其中router.pushUrl是最核心的跳转 API——它向页面栈中压入一个目标页用户可以按返回键回到上一页。本文以「猫猫大作战」中从主菜单跳转到排行榜详情页为场景讲解router.pushUrl的路由规则、参数传递、返回栈管理、以及回调处理。同时为后续第 82 篇 Navigation 新路由体系埋下对比伏笔。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–78 篇。本篇是阶段三第 79 篇。一、router.pushUrl 基本用法1.1 接口签名import { router } from kit.ArkUI; router.pushUrl(options: RouterOptions): Promisevoid; router.pushUrl(options: RouterOptions, callback: AsyncCallbackvoid): void;1.2 RouterOptions 参数interface RouterOptions { url: string; // 目标页面路径 params?: Object; // 传递的参数 modal?: boolean; // 是否模态半透明背景 forResult?: boolean; // 是否需要返回结果API 23 recovery?: string; // 恢复策略API 21 }字段必填说明url✅目标页面路径须在 main_pages.json 中注册params❌传递给目标页面的参数modal❌是否以模态方式打开背景半透明forResult❌是否需要从目标页返回结果recovery❌应用恢复时的页面恢复策略1.3 基础跳转示例import { router } from kit.ArkUI; import { BusinessError } from kit.BasicServicesKit; Entry Component struct Index { build() { Column() { Button( 查看排行榜) .onClick(() { // 跳转到排行榜页面 router.pushUrl({ url: pages/Leaderboard, params: { fromPage: main_menu, highScore: this.highScore } }).catch((err: BusinessError) { console.error(跳转失败: ${err.message}); }); }) } } }二、页面参数传递2.1 发送方通过 params 传参// Index.ets — 传递参数 router.pushUrl({ url: pages/Leaderboard, params: { fromPage: main_menu, highScore: this.highScore, playerName: 猫猫侠, gameDate: 2026-07-24 } });2.2 接收方router.getParams 取参// Leaderboard.ets — 接收参数 Entry Component struct Leaderboard { State fromPage: string ; State highScore: number 0; State playerName: string ; State gameDate: string ; aboutToAppear() { const params router.getParams() as Recordstring, Object; this.fromPage params?.[fromPage] as string ?? ; this.highScore params?.[highScore] as number ?? 0; this.playerName params?.[playerName] as string ?? ; this.gameDate params?.[gameDate] as string ?? ; } build() { Column() { Text(来自: ${this.fromPage}) Text(最高分: ${this.highScore}) Text(玩家: ${this.playerName}) Text(日期: ${this.gameDate}) } } }2.3 参数类型建议参数类型是否支持示例string✅hellonumber✅99999boolean✅trueObject✅{ name: 猫猫侠, level: 5 }Array✅[1, 2, 3]Function❌不支持序列化Class 实例⚠️建议序列化为 JSON注意params 中的数据会被序列化传递Function、Symbol、Date 等非序列化类型会被丢失。三、页面返回栈管理3.1 返回栈机制初始状态[Index] pushUrl(Leaderboard) → [Index, Leaderboard] ↑ 当前页 pushUrl(PlayerDetail) → [Index, Leaderboard, PlayerDetail] ↑ 当前页 按返回键 → [Index, Leaderboard] ↑ 当前页Leaderboard.onPageShow 触发 按返回键 → [Index] ↑ 当前页Index.onPageShow 触发3.2 router.back 返回// Leaderboard.ets — 返回到 Index Button(返回) .onClick(() { router.back(); // 弹出栈顶回到上一个页面 })3.3 返回到指定页面// 返回到指定路径的页面跳过多层 router.back({ url: pages/Index });3.4 带结果返回API 23// Index.ets — 跳转时标记 forResult router.pushUrl({ url: pages/Leaderboard, params: { fromPage: main_menu }, forResult: true }); // Leaderboard.ets — 返回时带数据 Button(选择并返回) .onClick(() { router.back({ url: pages/Index, params: { selectedScore: 88888, selectedPlayer: 猫猫侠 } }); })四、模态跳转4.1 模态页面// 以模态方式打开设置页面半透明背景 router.pushUrl({ url: pages/Settings, modal: true });模态页面的特点特性普通跳转模态跳转背景完全替换保留上一页背景半透明返回方式返回键/back()返回键/back()动画页面堆叠底部弹出式动画适用场景普通页面跳转设置、弹窗、选项五、错误处理5.1 常见错误码router.pushUrl({ url: pages/Leaderboard }) .catch((err: BusinessError) { switch (err.code) { case 100001: console.error(页面不存在未在 main_pages.json 中注册); break; case 100002: console.error(页面栈已满); break; case 100003: console.error(跳转被拦截); break; default: console.error(未知错误: ${err.code} ${err.message}); } });错误码含义解决方案100001目标页面不存在检查 main_pages.json 注册100002页面栈超限使用 replaceUrl 或清理栈100003路由被拦截检查是否设置了路由拦截其他系统错误捕获异常并重试5.2 防止重复跳转// 使用标志位防止按钮连点导致的重复跳转 State navigating: boolean false; goToLeaderboard() { if (this.navigating) return; this.navigating true; router.pushUrl({ url: pages/Leaderboard }) .then(() { this.navigating false; }) .catch(() { this.navigating false; }); }六、router.pushUrl 与生命周期6.1 跳转时的生命周期时序跳转前Index当前页面 ↓ router.pushUrl(pages/Leaderboard) ↓ Leaderboard.aboutToAppear() ← 目标页准备 Index.onPageHide() ← 原页隐藏 Leaderboard.build() ← 目标页渲染 Leaderboard.onDidBuild() ← 目标页渲染完成 Leaderboard.onPageShow() ← 目标页可见 ↓ 用户看到 Leaderboard 页面6.2 返回时的生命周期时序返回前Leaderboard当前页面 ↓ router.back() ↓ Leaderboard.aboutToDisappear() ← 目标页销毁 Index.onPageShow() ← 原页重新可见 Leaderboard 组件销毁 ← 从页面栈移除七、router.pushUrl vs Navigation.pushPath对比维度router.pushUrlNavigation.pushPath引入方式import { router } from kit.ArkUINavPathStack 实例方法页面注册main_pages.json需 navDestination Builder 注册参数类型params: Objectparam: Object返回结果forResult参数原生支持结果回调拦截能力无setInterception支持分栏模式不支持支持 Split 分栏官方推荐旧方案推荐方案新从 API 12 开始官方推荐使用 Navigation 方案。但理解 router 是理解 Navigation 的基础且老项目可能仍在大量使用 router。八、常见踩坑8.1 坑一路径前没有加 pages/// 错误路径不完整 router.pushUrl({ url: Leaderboard }); // ✅ 正确完整路径 router.pushUrl({ url: pages/Leaderboard });8.2 坑二页面栈溢出// 连续 pushUrl 导致页面栈溢出 for (let i 0; i 100; i) { router.pushUrl({ url: pages/Detail }); } // 页面栈默认容量约 32 层超出会报错 100002九、总结router.pushUrl是 HarmonyOS 经典的路由跳转 API通过 URL 路径 params 参数实现页面间导航和通信。虽然官方已推荐使用 Navigation 替代但理解 router 的页面栈管理、生命周期时序和参数传递机制仍然是掌握 HarmonyOS 路由体系的基础。核心要点pushUrl向页面栈压入新页面back()弹出页面params传递页面参数接收方通过router.getParams()获取路径必须与main_pages.json注册一致不含.ets扩展模态跳转modal: true支持半透明背景推荐用forResult实现返回结果传递API 23注意防重复跳转和页面栈溢出下一篇预告第 80 篇将深入router.replaceUrl— 无回退栈的页面替换导航。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源router API 官方参考页面路由与生命周期router 到 Navigation 迁移BusinessError 错误码参考Navigation 新路由架构开源鸿蒙跨平台社区第 78 篇main_pages 路由表第 80 篇router.replaceUrl 替换导航