HarmonyOS开发实战：小分享-ArkUI 导航与路由——router API 深入

前言

路由导航 是移动应用的核心能力，决定了用户如何在页面间流转。小分享 App 使用 @ohos.router 模块实现页面跳转。本篇深入讲解 pushUrl、replaceUrl、back、getParams 等 API。详细 API 可参考 HarmonyOS Router 官方文档。

一、router 核心 API

1.1 API 列表

API	作用	返回值
`router.pushUrl(options)`	入栈跳转	Promise
`router.replaceUrl(options)`	替换当前页	Promise
`router.back(options?)`	出栈返回	void
`router.clear()`	清空路由栈	void
`router.getLength()`	获取栈长度	number
`router.getState()`	获取当前栈状态	RouterState
`router.getParams()`	获取页面参数	Object

1.2 pushUrl 入栈跳转

typescript 复制代码

router.pushUrl({
  url: 'pages/TextEditPage',
  params: { type: 'text', title: '分享文字' }
})

1.3 replaceUrl 替换跳转

typescript 复制代码

router.replaceUrl({ url: 'pages/HomePage' })

1.4 back 返回

typescript 复制代码

router.back()                          // 返回上一页
router.back({ url: 'pages/HomePage' }) // 返回到指定页面

二、路由参数传递

2.1 发送参数

typescript 复制代码

router.pushUrl({
  url: 'pages/TemplateDetailPage',
  params: {
    templateId: 'ink-001',
    title: '水墨古风'
  }
})

2.2 接收参数

typescript 复制代码

aboutToAppear(): void {
  const params = router.getParams() as Record<string, string>
  this.templateId = params.templateId
  this.title = params.title
}

三、路由栈管理

3.1 路由栈特性

typescript 复制代码

router.getLength()  // 当前栈深度
router.getState()   // 当前页面状态
router.clear()      // 清空栈

3.2 避免栈溢出

typescript 复制代码

// 底部 Tab 切换用 replaceUrl
router.replaceUrl({ url: 'pages/HomePage' })

// 详情页跳转用 pushUrl
router.pushUrl({ url: 'pages/DetailPage' })

// 达到上限时清空
if (router.getLength() > 30) {
  router.clear()
  router.pushUrl({ url: 'pages/HomePage' })
}

四、小分享 App 路由策略

场景	API	原因
启动页→首页	`replaceUrl`	避免返回启动页
分类导航	`pushUrl`	保留返回入口
编辑页→预览	`pushUrl`	预览后可返回编辑
底部 Tab 切换	`replaceUrl`	避免栈膨胀
返回上一页	`back()`	标准返回

五、本文核心知识点

5.1 路由核心要点

pushUrl 入栈，replaceUrl 替换，back 返回
params 传递页面参数
getLength/getState 管理路由栈

5.2 实战开发要点

Tab 切换用 replaceUrl 避免栈溢出
页面参数用 getParams() 接收
路由栈深度超 30 时清空

附录：路由导航的完整实现细节

1. Router 核心 API 对比

API	作用	栈变化	适用场景
`router.pushUrl()`	入栈	新页入栈	列表→详情
`router.replaceUrl()`	替换	当前页出栈，新页入栈	Tab 切换
`router.back()`	返回	当前页出栈	返回上一页
`router.clear()`	清空	全部出栈	重启流程
`router.getLength()`	获取栈长度	无	栈检查
`router.getState()`	获取状态	无	调试
`router.getParams()`	获取参数	无	接收参数

2. 完整的路由跳转示例

typescript 复制代码

// 入栈跳转（保留返回入口）
router.pushUrl({
  url: 'pages/TextEditPage',
  params: { type: 'text' }
})

// 替换跳转（不保留返回）
router.replaceUrl({ url: 'pages/HomePage' })

// 返回上一页
router.back()

// 带参数返回
router.back({ url: 'pages/HomePage' })

3. 参数传递的完整实现

typescript 复制代码

// 发送方
router.pushUrl({
  url: 'pages/TemplateDetailPage',
  params: { templateId: 'ink-001', title: '水墨古风' }
})

// 接收方
aboutToAppear(): void {
  const params = router.getParams() as Record<string, string>
  this.templateId = params.templateId
  this.title = params.title
}

4. 路由栈管理

typescript 复制代码

// 检查栈深度
if (router.getLength() > 30) {
  router.clear()
  router.pushUrl({ url: 'pages/HomePage' })
}

5. 小分享 App 路由策略

场景	API	原因
启动页→首页	`replaceUrl`	避免返回启动页
分类导航	`pushUrl`	保留返回入口
Tab 切换	`replaceUrl`	避免栈膨胀
返回	`back()`	标准返回

6. 完整代码文件索引

文件路径	说明
所有页面文件	使用 router API

7. 总结

本文深入讲解了 HarmonyOS router 路由 API 的完整使用，涵盖 pushUrl、replaceUrl、back、参数传递和栈管理。

本文涉及的所有 API 索引

API	类别	用途
Column	布局容器	垂直排列子组件
Row	布局容器	水平排列子组件
Text	基础组件	显示文本
ForEach	渲染控制	循环渲染列表
@State	装饰器	组件内状态管理
@Builder	装饰器	封装可复用 UI 片段
router.pushUrl	路由	页面跳转
router.back	路由	返回上一页

总结

本文详细讲解了小分享 App 中对应页面的完整实现。核心知识点涵盖布局容器、组件封装、状态管理、路由跳转等关键技术。通过本文的学习，读者可以掌握 HarmonyOS ArkUI 声明式开发的核心技能，并能够独立实现类似的页面功能。

相关资源

HarmonyOS 官方文档 ：https://developer.huawei.com/consumer/cn/doc/
ArkTS 语法指南 ：ArkTS Introduction
状态管理指南 ：State Management
ArkUI 组件参考 ：ArkUI Components
路由 API ：Router API
开源鸿蒙跨平台社区 ：https://openharmonycrossplatform.csdn.net

6. 完整的路由跳转流程

typescript 复制代码

// 1. 定义路由路径
const pages: string[] = ['pages/HomePage', 'pages/DiscoverPage', '', 'pages/FavoritesPage', 'pages/ProfilePage'];

// 2. 执行跳转
router.replaceUrl({ url: 'pages/HomePage' });

// 3. 传递参数
router.pushUrl({ url: 'pages/TemplateDetailPage', params: { templateId: '001', title: '水墨古风' } });

// 4. 接收参数
aboutToAppear(): void { const params = router.getParams() as Record<string, string>; }

// 5. 返回上一页
router.back();

7. 路由参数传递详解

发起方	接收方
`router.pushUrl({ url: 'pages/Detail', params: { id: '1' } })`	`aboutToAppear() { const p = router.getParams(); }`
支持任意类型参数	需要类型断言 `as Record<string, string>`
参数自动序列化	接收方在 aboutToAppear 中获取

8. 路由栈深度管理

typescript 复制代码

// 获取当前栈深度
const depth = router.getLength();

// 栈溢出保护
if (depth > 30) {
  router.clear();
  router.pushUrl({ url: 'pages/HomePage' });
}

9. 小分享 App 路由策略

场景	路由 API	说明
启动页→首页	`replaceUrl`	销毁启动页
分类导航	`pushUrl`	保留返回入口
Tab 切换	`replaceUrl`	避免栈膨胀
编辑→预览	`pushUrl`	保留编辑状态
返回	`back()`	标准返回

10. 完整代码文件索引

文件路径	说明
所有页面	使用 router API

11. 本文涉及的所有 API

API	用途	文档链接
`router.pushUrl()`	入栈跳转	Router
`router.replaceUrl()`	替换跳转	Router
`router.back()`	返回	Router
`router.clear()`	清空栈	Router
`router.getLength()`	栈深度	Router
`router.getParams()`	获取参数	Router

12. 实现要点总结

路由导航的核心要点：

pushUrl 入栈：保留返回入口，适合详情页跳转
replaceUrl 替换：销毁当前页，适合 Tab 切换
back 返回：标准返回操作
参数传递：params 对象传递，getParams 接收
栈管理：getLength 检查栈深度，避免溢出

13. 总结

本文深入讲解了 HarmonyOS router 路由 API 的完整使用，涵盖 pushUrl、replaceUrl、back、参数传递和栈管理。