HarmonyOS 页面路由：Router API

适用版本HarmonyOS 6.1API 12及以上验证环境Pura 90 Pro 模拟器HarmonyOS 6.1.1API 24关键概念router.pushUrl、router.replaceUrl、router.back、路由栈、参数传递前言HarmonyOS 的页面路由基于栈模型pushUrl入栈保留历史replaceUrl替换栈顶back出栈返回。本文覆盖路由注册、跳转、参数传递和返回值共享的完整用法。一、注册页面在entry/src/main/resources/base/profile/main_pages.json中声明所有页面{ src: [ pages/Index, pages/DetailPage, pages/ProfilePage ] }二、基本跳转import router from ohos.router // pushUrl入栈保留当前页可以 back 回来 router.pushUrl({ url: pages/DetailPage }) // replaceUrl替换栈顶当前页不保留无法 back 回来 router.replaceUrl({ url: pages/DetailPage }) // back返回上一页 router.back() // back 到指定页面url 为目标页路径 router.back({ url: pages/Index })三、带参数跳转// 发送参数源页面 router.pushUrl({ url: pages/DetailPage, params: { userId: 42, title: 商品详情, tags: [热门, 推荐] } })// 接收参数目标页面的 aboutToAppear 生命周期 aboutToAppear(): void { const p router.getParams() if (p ! null p ! undefined) { const params p as Recordstring, string this.userId parseInt(params[userId] || 0) this.title params[title] || } }四、路由栈管理// 获取当前路由栈深度 const depth router.getLength() // number // 获取当前页面状态 const state router.getState() // state.index → 栈中位置1 栈底 // state.name → 页面名称如 DetailPage // state.path → 页面路径如 pages/DetailPage // 清空路由栈返回首页 router.clear()五、返回值传递推荐用 Provide/Consume 或 AppStorageRouter 的back()不支持直接传参推荐用共享状态// 方案1AppStorage全局键值存储 // 详情页写入 AppStorage.SetOrCreate(selectedId, 42) router.back() // 列表页读取生命周期 onPageShow 中 onPageShow(): void { const id AppStorage.Getnumber(selectedId) if (id ! undefined) { this.selectedId id AppStorage.Delete(selectedId) } } // 方案2Provide/Consume 共享见 article26六、路由模式pushUrl 第二参数// 默认Standard允许多个相同页面实例 router.pushUrl({ url: pages/DetailPage }, router.RouterMode.Standard) // Single同一 URL 只允许一个实例防重复入栈 router.pushUrl({ url: pages/DetailPage }, router.RouterMode.Single)模拟器运行截图初始状态API 演示选项卡pushUrl 跳转后点击「pushUrl跳转到详情页」后路由栈深度增加 1当前路由变为Index注意本演示将 Index 自身入栈模拟跳转效果实际项目应跳转到DetailPage。实测结果操作路由栈深度变化当前页面初始1IndexpushUrl1 2IndexpushUrl 再次1 3Indexback()-1 2IndexreplaceUrl不变 2Indexclear()→ 1Index常见问题QpushUrl和Navigation组件有什么区别Arouter.pushUrl适合简单页面跳转使用场景广泛HarmonyOS 2.0 起支持Navigation组件HarmonyOS 4.0 引入类似 iOSUINavigationController内置标题栏、返回按钮、转场动画更适合复杂导航结构Q如何防止用户快速点击导致重复入栈A使用RouterMode.Single或在跳转前加防抖let isNavigating false function safePush(url: string): void { if (isNavigating) { return } isNavigating true router.pushUrl({ url }, () { isNavigating false }) }Q如何实现“返回到任意页面“不是上一页A使用router.back({ url: pages/HomePage })直接跳回指定页面会出栈中间所有页面。也可以用router.clear()清空栈后再pushUrl。上一篇数据持久化Preferences第三批21-30 篇完结。涵盖 TaskPool 并发、Sendable 数据共享、文本输入、布局系统、状态管理、跨组件通信、动画、HTTP、持久化、路由十大主题均经模拟器验证并附截图。