【HarmonyOS】ArkUI - 页面路由

一、概念

页面路由是指在应用程序中实现不同页面之间的跳转和数据传递。

案例：第一次使用某个购物应用，打开时肯定会是一个登录页，在登录成功以后，会跳转到首页，然后可能会去搜索，就会进入到搜索列表页，接着呢如果搜索到某一个感兴趣的商品A，点击，就会进入到商品A的详情页，到现在为止已经访问了好多不同的页面，并且在它们之间完成了跳转，那我之前访问过的页面都去哪里了？是不是全部被销毁了？其实并没有，我们在页面跳转之间访问过的所有页面，都会被 HarmonyOS 保存到页面栈的空间当中。页面栈顾名思义就是保存页面的栈结构空间，栈结构是先进后出，所以呢，我们最早访问的登录页就被压到了栈的最底层，而当前正在访问的商品A的详情页就在栈顶。也就是说，谁在栈顶，当前显示的就是谁的页面。那么 HarmonyOS 为啥要把这些访问过的页面保存起来，而不是直接销毁掉呢？放在这里不占用内存吗？这其实是我们的页面功能需要去用到这些历史页面。一般商品详情页都会有返回按钮，当点击返回按钮，应该返回到之前访问过的搜索列表页，有了页面栈，想要实现这个功能就非常简单了。只需要在点击返回时，把栈顶的这个页面移除，这样一来，紧挨着栈顶的搜索列表页就成为了新的栈顶页面，现在显示的就是搜索列表页，从而也就实现了返回的效果。如果现在想做页面跳转，过程就相反，比如在搜索列表页点击商品B，只需要把商品B的详情页创建出来，然后压入栈里，现在栈顶就是商品B的详情页，从而实现了跳转效果。简单来讲，如果想实现创建页面，就压入栈；如果想实现返回，就把栈顶页面弹出栈，即可。

页面栈的最大容量：

页面栈的最大容量上限为 32 个页面。就是说如果我们不断的去访问新的页面，往栈里压入页面，可能就会达到上限，这时候再想访问这个页面，再想往里面去压栈，就会报错，这时候就不得不去调用 router.clear() 方法去清空页面栈，就会把历史页面干掉，释放内存。但是，一旦把历史页面干掉，再想返回前一个页面就访问不了了。所以 router.clear() 要慎重使用。我们在开发的过程中一定要想办法控制页面栈里的页面数量，不要让它达到上限，而不是说等达到上限去清空。
怎么去控制页面栈里的页面数量呢？就要使用页面栈不同的跳转行为模式。Router 有两种页面跳转模式：
- router.pushUrl()：目标页不会替换当前页，而是压入页面栈。比如当前在商品A的详情页，如果点击商品B的图片，就需要压入栈，就需要创建一个商品B的页面，把商品B的详情页压入栈顶，这时候，原有的商品A的详情页不会被移除，而是压到栈的内部，成为一个历史页面，因此点返回按钮，用 router.back() 就会返回到历史页面商品A的详情页。但是，这种实现方式会导致栈里的页面会越来越多。
- router.replaceUrl()：目标页替换当前页，当前页会被销毁并释放资源。也就是说从商品A的详情页跳转到商品B的详情页，这时候商品A的详情页就变成了历史页，会直接被销毁，而不是在栈内保存。这样一来，内存就节省出来，但是如果想从商品B的详情页返回到商品A的详情页，就返回不了了。
何时使用 router.pushUrl()，何时又使用 router.replaceUrl() 呢？

举个例子，比如说，我们的登录页，只有在第一次打开的时候才需要，只要不退出，就不用再登录。所以登录页基本上就访问一次，而且也不需要返回，登录页保存在历史页面栈里没有任何意义，所以在登录成功以后，跳转到首页时，就可以使用 router.replaceUrl() 把登录页销毁；如果我们从首页跳转到搜索列表页，如果这时候点返回，返回到首页，所以我们的首页应该在页面栈里保存，作为一个历史页面，就要用 router.pushUrl()。
如果商品A的详情页和商品B的详情页来回切换，如果用到 router.pushUrl()，会导致页面栈的容量一会儿就满了，就要用到页面实例模式，Router 有两种页面实例模式：
- Standard：标准实例模式，每次跳转都会新建一个目标页并压入栈顶。默认就是这种模式。
- Single：单实例模式，顾名思义，每一个页面只会存在一份，如果目标页已经在栈中，则离栈顶最近的同Url页面会被移动到栈顶并重新加载。

结合合适的跳转模式（router.pushUrl()、router.replaceUrl()）和实例模式（Standard、Single），就能够控制页面栈里的页面数量，避免达到上限。

二、Router API 用法

首先要导入 HarmonyOS 提供的 Router 模块：
```
import router from '@ohos.router';
```
然后利用 router 实现跳转、返回等操作：
```
router.pushUrl({url: 'pages/PageA',params: { id: 1 }},router.RouterMode.Single,err => {if (err) {console.log('路由失败。')}}
)
```
- RouterOptions
  - url：目标页面路径
  - params：传递的参数（可选）
- RouterMode
  - Standard：标准实例模式
  - Single：单实例模式
- 异常响应回调函数
  - 错误码 100001：内部错误，可能是渲染失败
  - 错误码 100002：路由地址错误
  - 错误码 100003：路由栈中页面超过32
目标页获取传递过来的参数
```
params: any = router.getParams()
```
目标页返回上一页
```
router.back()
```

目标页返回指定页，并携带参数

router.back({url: 'pages/Index',params: { id: 10 }
})

三、示例

代码目录结构

|____src
| |____main
| | |____resources
| | | | |____profile
| | | | | |____main_pages.json
| | | | |____media
| | | | | |____back.png
| | |____ets
| | | |____components
| | | | |____CommonComponents.ets
| | | |____pages
| | | | |____PageD.ets
| | | | |____PageC.ets
| | | | |____PageB.ets
| | | | |____PageA.ets
| | | | |____Index.ets

main_pages.json

{"src": ["pages/Index","pages/PageA","pages/PageB","pages/PageC","pages/PageD"]
}

CommonComponents.ets

import router from '@ohos.router'@Component
export struct Header {@State params: any = router.getParams()build() {Row({ space: 5 }) {Image($r('app.media.back')).width(30).onClick(() => {// 返回前的警告router.showAlertBeforeBackPage({message: 'Show Alert Before Back Page'})// 返回上一页router.back()})if (this.params) {Text(`Params id: ${this.params.id}`).fontSize(28).fontWeight(FontWeight.Bold)}}.width('98%').height(30)}
}

Index.ets

import router from '@ohos.router'class RouterInfo {// 页面路径url: string// 页面标题title: stringconstructor(url: string, title: string) {this.url = urlthis.title = title}
}@Entry
@Component
struct Index {@State message: string = '页面列表'private routers: RouterInfo[] = [new RouterInfo('pages/PageA', 'A页面'),new RouterInfo('pages/PageB', 'B页面'),new RouterInfo('pages/PageC', 'C页面'),new RouterInfo('pages/PageD', 'D页面')]build() {Column() {Text(this.message).fontSize(50).fontWeight(FontWeight.Bold).height(80)List({ space: 15 }) {ForEach(this.routers,(router, index) => {ListItem() {this.RouterItem(router, index + 1)}})}.layoutWeight(1).alignListItem(ListItemAlign.Center).width('100%')}.width('100%').height('100%')}@BuilderRouterItem(r: RouterInfo, i: number) {Row() {Text(i + '. ').fontSize(20).fontColor(Color.White)Text(r.title).fontSize(20).fontColor(Color.White)}.width('90%').padding(12).backgroundColor('#38F').borderRadius(20).shadow({ radius: 6, color: '#4F000000', offsetX: 2, offsetY: 2 }).onClick(() => {// router 跳转router.pushUrl({url: r.url,params: { id: i }},router.RouterMode.Single,err => {if (err) {console.log(`路由失败，errCode: ${err.code} errMsg: ${err.message}`)}})})}
}

PageA.ets

import { Header } from '../components/CommonComponents'@Entry
@Component
struct PageA {@State message: string = 'Page A'build() {Column() {Header()Row() {Column() {Text(this.message).fontSize(50).fontWeight(FontWeight.Bold)}.width('100%')}.height('100%')}.width('100%')}
}

运行效果

请添加图片描述

四、总结

页面栈的最大容量上限为 32 个页面，使用 router.clear() 方法可以清空页面栈，释放内存。
Router 有两种页面跳转模式，分别是：
- router.pushUrl()：目标页不会替换当前页，而是压入页面栈，因此可以用 router.back() 返回当前页。
- router.replaceUrl()：目标页会替换当前页，当前页会被销毁并释放资源，无法返回当前页。
Router 有两种页面实例模式，分别是：
- Standard：标准实例模式，每次调整都会新建一个目标并压入栈顶。默认就是这种模式。
- Single：单实例模式，如果目标页已经在栈中，则离栈顶最近的同 url 页面会被移动到栈顶并重新加载。
router 的使用步骤：
1. 导入 router 模块
2. 使用 router 的 API