HarmonyOS NEXT 应用开发实战(六、组件导航Navigation利用详解) ...

在鸿蒙应用开发中，Navigation 组件是实现界面间导航的重要工具。本文将介绍怎样利用 Navigation 组件实现页面跳转及参数传递，确保你能轻松构建具有良好用户体验的应用。
  当前HarmonyOS支持两套路由机制（Navigation和Router），Navigation作为后续长期演进及推荐的路由选择方案，其与Router比较有不少优势。发起后续直接利用Navigation作为内部的路由方案。
Navigation介绍

Navigation组件通常作为页面的根容器，支持单页面、分栏和自适应三种表现模式。开发者可以利用Navigation组件提供的属性来设置页面的标题栏、工具栏、导航栏等。
Navigation和Router能力对标

Router路由的页面是一个@Entry修饰的Component，每一个页面都需要在main_page.json中声明。而基于Navigation的路由页面分为导航页和子页，导航页又叫Navbar，是Navigation包含的子组件，子页是NavDestination包含的子组件。
业务场景NavigationRouter一多能力支持，Auto模式自适应单栏跟双栏表现不支持跳转指定页面pushPath & pushDestinationpushUrl & pushNameRoute跳转HSP中页面支持支持跳转HAR中页面支持支持跳转传参支持支持获取指定页面参数支持不支持传参类型传参为对象形式传参为对象形式，对象中暂不支持方法变量跳转结果回调支持支持跳转单例页面不支持支持页面返回支持支持页面返回传参支持支持返回指定路由支持支持页面返回弹窗支持，通过路由拦截实现showAlertBeforeBackPage路由更换replacePath & replacePathByNamereplaceUrl & replaceNameRoute路由栈清算clearclear清算指定路由removeByIndexes & removeByName不支持转场动画支持支持自定义转场动画支持支持，动画类型受限屏蔽转场动画支持全局和单次支持 设置pageTransition方法duration为0geometryTransition共享元素动画支持（NavDestination之间共享）不支持页面生命周期监听UIObserver.on('navDestinationUpdate')UIObserver.on('routerPageUpdate')获取页面栈对象支持不支持路由拦截支持通过setInercption做路由拦截不支持路由栈信息查询支持getState() & getLength()路由栈move操作moveToTop & moveIndexToTop不支持沉浸式页面支持不支持，需通过window配置设置页面标题栏（titlebar）和工具栏（toolbar）支持不支持模态嵌套路由支持不支持 Navigation简单示例

主页面（首页面）示例：

2. @Entry
3. @Component
4. struct NavigationExample {
5.   build() {
6.     Column() {
7.       Navigation() {
8.         // 中间主区域
9.       }
10.       .title("主标题") // 页面标题
11.       .mode(NavigationMode.Auto) // 显示模式：Auto（自适应）、Stack（单页显示）、Split（分栏显示）、Full（强调型标题栏）、Mini（普通型标题栏）
12.       .menus([
13.         // 顶部菜单栏
14.       ])
15.       .toolBar({items: [
16.         // 底部工具栏
17.       ]})
18.     }
19.     .height('100%')
20.     .width('100%')
21.     .backgroundColor('#F1F3F5')
22.   }
23. }

复制代码

1. // index.ets
2. @Entry
3. @Component
4. struct Index {
5.   pathStack: NavPathStack = new NavPathStack()
7.   build() {
8.     Navigation(this.pathStack) {
9.       Column() {
10.         Button('Push PageOne', { stateEffect: true, type: ButtonType.Capsule })
11.           .width('80%')
12.           .height(40)
13.           .margin(20)
14.           .onClick(() => {
15.             this.pathStack.pushPathByName('pageOne', null)
16.           })
17.       }.width('100%').height('100%')
18.     }
19.     .title("Navigation")
20.   }
21. }

复制代码

 子页示例：

1. // PageOne.ets
3. @Builder
4. export function PageOneBuilder() {
5.   PageOne()
6. }
8. @Component
9. export struct PageOne {
10.   pathStack: NavPathStack = new NavPathStack()
12.   build() {
13.     NavDestination() {
14.       Column() {
15.         Button('回到首页', { stateEffect: true, type: ButtonType.Capsule })
16.           .width('80%')
17.           .height(40)
18.           .margin(20)
19.           .onClick(() => {
20.             this.pathStack.clear()
21.           })
22.       }.width('100%').height('100%')
23.     }.title('PageOne')
24.     .onReady((context: NavDestinationContext) => {
25.       this.pathStack = context.pathStack
26.     })
27.   }
28. }

复制代码

注意：每个子页也需要配置到系统配置文件route_map.json中（参考 系统路由配置 ）：

1. // 工程配置文件module.json5中配置 {"routerMap": "$profile:route_map"}
2. // route_map.json
3. {
4.   "routerMap": [
5.     {
6.       "name": "pageOne",
7.       "pageSourceFile": "src/main/ets/pages/PageOne.ets",
8.       "buildFunction": "PageOneBuilder",
9.       "data": {
10.         "description": "this is pageOne"
11.       }
12.     }
13.   ]
14. }

复制代码

NavRouter介绍

NavRouter是Navigation组件中的特别子组件，通常用于与Navigation组件共同利用，它默认提供了点击响应处理，不需要开发者自定义点击事件逻辑。NavRouter组件只有两个子组件，其中第二个子组件必须是NavDestination。而NavDestination则是Navigation组件中的特别子组件，用于表现内容页的内容。当开发者点击NavRouter组件时，会跳转到对应的NavDestination内容区。

1.   Navigation() {
2.     TextInput({ placeholder: '请输入...' })
3.       .width('90%')
4.       .height(40)
5.       .backgroundColor('#ffffff')
7.     List({ space: 12 }) {
8.       ForEach(this.arr, item => {
9.         ListItem() {
10.           NavRouter() {
11.             Text("NavRouter" + item)
12.               .width('100%')
13.               .height(72)
14.               .backgroundColor(Color.White)
15.               .borderRadius(36)
16.               .fontSize(16)
17.               .fontWeight(500)
18.               .textAlign(TextAlign.Center)
19.             NavDestination() {
20.               Text(`NavDestinationContent${item}`)
21.             }
22.             .title(`NavDestinationTitle${item}`)
23.           }
24.         }
25.       })
26.     }
27.   }
28.   .title('主标题')
29.   .mode(NavigationMode.Stack)//导航模式
30.   .titleMode(NavigationTitleMode.Mini)//标题模式
31.   .menus([  //设置菜单
32.     { value: "", icon: './../../../resources/base/media/icon.png', action: () => {
33.     } },
34.     { value: "", icon: './../../../resources/base/media/icon.png', action: () => {
35.     } }
36.   ])
37.   .toolBar({ items: [  //设置工具栏
38.     { value: 'func', icon: './../../../resources/base/media/icon.png', action: () => {
39.     } },
40.     { value: 'func', icon: './../../../resources/base/media/icon.png', action: () => {
41.     } }
42.   ] })

复制代码

在鸿蒙开发中，NavRouter 和直接利用 this.pageStack.pushDestinationByName 来实现页面跳转的确可以达到相似的结果，但它们在计划理念和利用场景上有一些区别。以下是这两者之间的一些关键点和它们各自的用途：
1. NavRouter 的用途

• 封装与简化：NavRouter 是一个封装了导航逻辑的组件，专注于处理页面间的跳转和路由管理。它提供了一个更简洁的接口以实现页面跳转，可以让开发者更轻易进行组件化开发，从而提高代码的可读性和可维护性。
  
• 动态路由：在 NavRouter 中，可以方便地将导航逻辑和目标页面的内容结合在一起。通过 NavRouter，不必手动管理目标页面的具体情况，可以直接利用组件的声明式来定义导航内容。
  

2. this.pageStack.pushDestinationByName

• 底层控制：利用 this.pageStack.pushDestinationByName 更靠近底层的 API，得当需要更细粒度控制的情况。它通常适用于需要直接处理路由堆栈的场所。
  
• 灵活性：虽然提供了更多的灵活性，但相应的也要求开发者自行管理跳转的状态、参数传递等，代码可能相对繁琐，尤其是在处理复杂的导航场景时。
  

3. 何时利用 NavRouter

• 如果你的应用需要在多个组件之间频繁进行导航，并且希望维护清楚的结构和可读性，利用 NavRouter 是一个不错的选择。
  
• 对于简单的情况，如果你的跳转逻辑不复杂，且需要直接控制页面堆栈的举动，利用 this.pageStack.pushDestinationByName 也完全可以。
  

总结而言，虽然两者都可以实现页面跳转，但 NavRouter 提供了更高层次的抽象，更得当构建组件化的、可维护的导航结构，而 this.pageStack.pushDestinationByName 更得当需要底层控制的场景。选择利用哪一种方式，主要依赖于具体的开发需求和代码结构计划。简言之，NavRouter 有点儿类似于折叠结果，所有内容已经拿到了，不需要再跳转到其他页面去哀求，只需睁开表现即可。则利用NavRouter 可以完成在一个页面里实现想要的结果。
Navigation利用步调

一、基本利用

将Navigation 组件作为底子页面的根容器，它可以或许管理整个页面的结构和导航。定义NavPathStack 实例，反面需要用它实现路由跳转和传参。Navigation通过页面栈对象 NavPathStack 提供的方法来操作页面，需要创建一个栈对象并传入Navigation中。
以下是一个基本的 Navigation 组件结构示例：

1. import { getZhiHuNews } from '../../common/api/zhihu';
2. import { BaseResponse,ErrorResp } from '../../common/bean/ApiTypes';
3. import { Log } from '../../utils/logutil'
6. @Component
7. export default struct ZhiHu{
8.   @State message: string = 'Hello World';
9.   private arr: number[] = [1, 2, 3];
11.   //重要，定义NavPathStack 实例，后面需要用它实现路由跳转和传参
12.   pageStack: NavPathStack = new NavPathStack()
14.   // 组件生命周期
15.   aboutToAppear() {
16.     Log.info('ZhiHu aboutToAppear');
18.     getZhiHuNews("20241017").then((res) => {
19.       Log.debug(res.data.message)
20.       Log.debug("request","res.data.code:%{public}d",res.data.code)
21.     }).catch((err:BaseResponse<ErrorResp>) => {
22.       Log.debug("request","err.data.code:%d",err.data.code)
23.       Log.debug("request",err.data.message)
24.     });
25.     let list: number[] = []
26.     for (let i = 1; i <= 10; i++) {
27.       list.push(i);
28.     }
29.   }
31.   // 组件生命周期
32.   aboutToDisappear() {
33.     Log.info('ZhiHu aboutToDisappear');
34.   }
36.   build() {
37.     Navigation(this.pageStack){
38.       Row() {
39.         Column({ space: 0 }) {
40.           // 标题栏
41.           Text("日报")
42.             .size({ width: '100%', height: 50 })
43.             .backgroundColor("#28bff1")
44.             .fontColor("#ffffff")
45.             .textAlign(TextAlign.Center)
46.             .fontSize("18fp")
48.           // 内容项
49.             Swiper(this.swiperController) {
50.               LazyForEach(this.data, (item: string) => {
51.                 Stack({ alignContent: Alignment.Center }) {
52.                   Text(item.toString())
53.                     .width('100%')
54.                     .height(160)
55.                     .backgroundColor(0xAFEEEE)
56.                     .textAlign(TextAlign.Center)
57.                     .fontSize(30)
58.                     .zIndex(1)
59.                     .onClick(() => {
60.                       //this.pageStack.pushPathByName("PageOne", item)
61.                       this.pageStack.pushDestinationByName("PageOne", { id:"9773231" }).catch((e:Error)=>{
62.                         // 跳转失败，会返回错误码及错误信息
63.                         console.log(`catch exception: ${JSON.stringify(e)}`)
64.                       }).then(()=>{
65.                         // 跳转成功
66.                       });
67.                     })
69.                   // 显示轮播图标题
70.                   Text("特立独行的猫哥")
71.                     .padding(5)
72.                     .margin({ top:60 })
73.                     .width('100%').height(50)
74.                     .textAlign(TextAlign.Center)
75.                     .maxLines(2)
76.                     .textOverflow({overflow:TextOverflow.Clip})
77.                     .fontSize(20)
78.                     .fontColor(Color.White)
79.                     .opacity(100) // 设置标题的透明度 不透明度设为100%，表示完全不透明
80.                     .backgroundColor('#808080AA') // 背景颜色设为透明
81.                     .zIndex(2)
83.                 }
84.               }, (item: string) => item)
85.             }
86.             .cachedCount(2)
87.             .index(1)
88.             .autoPlay(true)
89.             .interval(4000)
90.             .loop(true)
91.             .indicatorInteractive(true)
92.             .duration(1000)
93.             .itemSpace(0)
94.             .curve(Curve.Linear)
95.             .onChange((index: number) => {
96.               console.info(index.toString())
97.             })
98.             .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => {
99.               console.info("index: " + index)
100.               console.info("current offset: " + extraInfo.currentOffset)
101.             })
102.             .height(160) // 设置高度
104.           List({ space: 12 }) {
105.             ForEach(this.arr, (item:string) => {
106.               ListItem() {
107.                 NavRouter() {
108.                   Text("NavRouter" + item)
109.                     .width("100%")
110.                     .height(72)
111.                     .backgroundColor('#FFFFFF')
112.                     .borderRadius(24)
113.                     .fontSize(16)
114.                     .fontWeight(500)
115.                     .textAlign(TextAlign.Center)
116.                   NavDestination() {
117.                     Text("NavDestinationContent" + item)
118.                   }
119.                   .title("NavDestinationTitle" + item)
120.                 }
121.               }
122.             }, (item:string) => item)
123.           }
125.         }.size({ width: '100%', height: '100%' })
126.       }
127.     }
128.     .mode(NavigationMode.Stack)
129.     .width('100%').height('100%')
131.   }
132. }

复制代码

注意：主页面利用  Navigation 组件作为根容器。而待跳转的子页面（目标页面），则是利用NavDestination作为根容器。
二、配置系统路由表

在进行页面跳转之前，需要在目次src/main/resources/base/profile中，创建文件route_map.json，手动注册跳转的页面。内容示例：

1. {
2.   "routerMap": [
3.     {
4.       "name": "PageOne",
5.       "pageSourceFile": "src/main/ets/pages/zhihu/detail/Detail.ets",
6.       "buildFunction": "DetailPageBuilder",
7.       "data": {
8.         "description": "this is Page Detail"
9.       }
10.     }
11.   ]
12. }

复制代码

上面这个配置其实是系统路由表，从API version 12版本开始，Navigation支持系统跨模块的路由表方案，团体计划是将路由表方案下沉到系统中管理，即在需要路由的各个业务模块（HSP/HAR）中独立配置router_map.json文件，在触发路由跳转时，应用只需要通过NavPactStack进行路由跳转，此时系统会自动完成路由模块的动态加载、组件构建，并完成路由跳转功能，从而实现了开发层面的模块解耦。 
在这个示例中，name 定义了路由名称，pageSourceFile 指向页面的具体实现文件，buildFunction 则指定了构建函数。开发者需确保这些字段的正确性和一致性，以便系统能正确辨认和加载目标页面。
路由表的基本概念

在新的计划中，每个业务模块（HSP / HAR）都可以独立配置 router_map.json 文件。当应用触发路由跳转时，利用 NavPathStack 内置的接口，系统将自动处理模块的动态加载和组件构建，从而实现路由跳转功能。
鸿蒙的系统路由表方案为应用开发提供了更加灵活和高效的路由管理方式。通过将路由表下沉到模块层，系统支持模块的独立配置和动态加载，不光实现了开发层面的模块解耦，也大大简化了开发流程。对于正在进行鸿蒙应用开发来说，掌握这一机制将显著提升开发服从和应用性能。
配置路由表注意事项

• 注册正确：确保 name 和 buildFunction 与要跳转的页面一致。
  
• 参数获取：在目标页面中，开发者可以利用 this.pageStack.getParamByName 方法获取传递的参数。
  

路由模块解耦的优势

• 独立性：每个业务模块可独立管理自己的路由信息，减少各模块间的相互依赖，提高开发服从。
  
• 动态加载：通过系统自动处理模块的加载和组件构建，提升了应用的性能和响应速度。
  
• 代码可维护性：在日后的维护中，开发者只需关注自身模块的路由配置和实现，对于系统的团体架构影响较小。
  

路由跳转的实现

利用 NavPathStack 进行路由跳转时，只需调用相应的方法并传递参数，系统会自动实验动态装载和跳转。例如：

1. this.pageStack.pushDestinationByName("DetailPage", { id: "9773231" })
2.   .catch((error) => {
3.     console.error(`路由跳转失败: ${JSON.stringify(error)}`);
4.   })
5.   .then(() => {
6.     console.log("路由跳转成功");
7.   });

复制代码

在上述代码中，调用 pushDestinationByName 方法完成页面跳转，同时也可以传递须要的参数。其他一些操作还有：

1. @Entry
2. @Component
3. struct Index {
4.   pathStack: NavPathStack = new NavPathStack()
6.   build() {
7.     // 设置NavPathStack并传入Navigation
8.     Navigation(this.pathStack) {
9.         ...
10.     }.width('100%').height('100%')
11.   }
12.   .title("Navigation")
13. }
15. // push page
16. this.pathStack.pushPath({ name: 'pageOne' })
18. // pop page
19. this.pathStack.pop()
20. this.pathStack.popToIndex(1)
21. this.pathStack.popToName('pageOne')
23. // replace page
24. this.pathStack.replacePath({ name: 'pageOne' })
26. // clear all page
27. this.pathStack.clear()
29. // 获取页面栈大小
30. let size = this.pathStack.size()
32. // 删除栈中name为PageOne的所有页面
33. this.pathStack.removeByName("pageOne")
35. // 删除指定索引的页面
36. this.pathStack.removeByIndexes([1,3,5])
38. // 获取栈中所有页面name集合
39. this.pathStack.getAllPathName()
41. // 获取索引为1的页面参数
42. this.pathStack.getParamByIndex(1)
44. // 获取PageOne页面的参数
45. this.pathStack.getParamByName("pageOne")
47. // 获取PageOne页面的索引集合
48. this.pathStack.getIndexByName("pageOne")
49. ...

复制代码

目标页面的实现

下面是目标页面 DetailPage 的一个简单示例：

1. import { Log } from '../../../utils/logutil';
3. @Builder
4. export function DetailPageBuilder() {
5.   DetailPage()
6. }
8. @Component
9. export default struct DetailPage {
10.   @State message: string = 'Hello World';
11.   pageStack: NavPathStack = new NavPathStack();
12.   private pathInfo: NavPathInfo | null = null;
14.   // 组件生命周期
15.   aboutToAppear() {
16.     Log.info('Detail aboutToAppear');
17.   }
19.   // 组件生命周期
20.   aboutToDisappear() {
21.     Log.info('Detail aboutToDisappear');
22.   }
24.   build() {
25.     NavDestination() {
26.       Column({ space: 0 }) {
27.         Text("内容").width('100%').height('100%').textAlign(TextAlign.Center).fontSize("25fp")
28.       }
29.     }
30.     .title("日报详情")
31.     .width('100%')
32.     .height('100%')
33.     .onReady(ctx => {
34.       this.pageStack = ctx.pathStack;
35.       const params = this.pageStack.getParamByName("PageOne");
36.       Log.info('接收到的参数:', params);
37.     });
38.   }
39. }

复制代码

组件生命周期与传递参数获取

在 DetailPage 的 onReady 方法中，开发者可以获取到传递的参数。这里利用 this.pageStack.getParamByName("ageOne") 获取指定页面的参数。这样可以灵活应对数据的传递和利用。
在导航页面中传递参数：
利用 this.pageStack.pushDestinationByName 方法跳转到目标页面，并传递参数。例如：

1. this.pageStack.pushDestinationByName("TargetPage", { id: "12345", name: "示例数据" })
2.   .catch((error) => {
3.     console.error(`路由跳转失败: ${JSON.stringify(error)}`);
4.   });

复制代码

1. import { Log } from '../../../utils/logutil';
3. @Builder
4. export function TargetPageBuilder() {
5.   TargetPage();
6. }
8. @Component
9. export default struct TargetPage {
10.   @State message: string = 'Hello from Target Page';
11.   pageStack: NavPathStack = new NavPathStack();
12.   private pathInfo: NavPathInfo | null = null;
14.   // 组件生命周期方法，页面即将出现
15.   aboutToAppear() {
16.     Log.info('TargetPage aboutToAppear');
17.   }
19.   // 组件生命周期方法，页面即将消失
20.   aboutToDisappear() {
21.     Log.info('TargetPage aboutToDisappear');
22.   }
24.   build() {
25.     NavDestination() {
26.       Column({ space: 0 }) {
27.         Text("内容").width('100%').height('100%').textAlign(TextAlign.Center).fontSize("25fp");
28.       }
29.     }
30.     .title("目标页面")
31.     .width('100%')
32.     .height('100%')
33.     .onReady(ctx => {
34.       this.pageStack = ctx.pathStack; // 获取当前的路径栈
35.       const params = this.pageStack.getParamByName("TargetPage"); // 获取传递的参数
36.       Log.info('接收到的参数:', params);
38.       // 例如，如果传递的数据为 { id: "12345", name: "示例数据" }
39.       if (params) {
40.         const id = params.id; // 获取具体的参数值
41.         const name = params.name;
42.         Log.info(`获取到的 ID: ${id}, 名称: ${name}`);
43.       }
44.     });
45.   }
46. }

复制代码

总结

通过利用 Navigation 组件及其相关接口，开发者可以方便地实现页面间的跳转和数据传递，从而构建丰富且流畅的用户界面。将页面逻辑与导航结构精密结合，可以极大提升应用的可维护性和用户体验。希望本篇文章能帮助到您在鸿蒙应用开发中的导航实现。
写在最后

最后，推荐下笔者的业余开源app影视项目“爱影家”，推荐分享给与我一样喜欢免费观影的朋友。【注：该项目仅限于学习研究利用！请勿用于其他用途！】
开源地址:爱影家app开源项目介绍及源码

1. https://gitee.com/yyz116/imovie

复制代码