HarmonyOS Navigation路由跳转的完整示例
HarmonyOS Navigation路由跳转的完整示例
项目概述
RouterNavigationDemo 是一个 HarmonyOS 应用示例项目，展示了如何在多模块架构中实现页面路由跳转。项目包含一个主模块（entry）和两个库模块（lib_harA 和 lib_hspA），演示了跨模块的页面导航功能。
项目结构
RouterNavigationDemo/
├── entry/ # 主模块
│ ├── src/main/
│ │ ├── ets/
│ │ │ ├── entryability/ # 应用入口能力
│ │ │ │ └── EntryAbility.ets
│ │ │ └── pages/ # 页面文件
│ │ │ ├── Index.ets # 首页
│ │ │ └── PageOne.ets # 页面一
│ │ └── resources/
│ │ └── base/profile/
│ │ ├── main_pages.json # 主页面配置
│ │ └── router_map.json # 路由映射配置
├── lib_harA/ # HAR 库模块
│ └── src/main/
│ ├── ets/pages/
│ │ └── HarAPageOne.ets # HAR 页面一
│ └── resources/base/profile/
│ └── router_map.json # HAR 路由映射
└── lib_hspA/ # HSP 共享模块└── src/main/├── ets/pages/│ └── HspAPageOne.ets # HSP 页面一└── resources/base/profile/├── main_pages.json # HSP 主页面配置└── router_map.json # HSP 路由映射
路由配置详解
1. 主模块 (entry) 配置
1.1 module.json5
{"module": {"name": "entry","type": "entry","mainElement": "EntryAbility","pages": "$profile:main_pages","routerMap": "$profile:router_map"}
}
1.2 main_pages.json
{"src": ["pages/Index"]
}
1.3 router_map.json
{"routerMap": [{"name": "EntryPageOne","pageSourceFile": "src/main/ets/pages/PageOne.ets","buildFunction": "PageOneBuilder","data": {"description": "this is PageOne"}}]
}
2. HAR 库模块 (lib_harA) 配置
2.1 module.json5
{"module": {"name": "lib_harA","type": "har","routerMap": "$profile:router_map"}
}
2.2 router_map.json
{"routerMap": [{"name": "HarAPageOne","pageSourceFile": "src/main/ets/pages/HarAPageOne.ets","buildFunction": "HarAPageOneBuilder","data": {"description": "this is HarAPageOne"}}]
}
3. HSP 共享模块 (lib_hspA) 配置
3.1 module.json5
{"module": {"name": "lib_hspA","type": "shared","pages": "$profile:main_pages","routerMap": "$profile:router_map"}
}
3.2 main_pages.json
{"src": ["pages/Index"]
}
3.3 router_map.json
{"routerMap": [{"name": "HspAPageOne","pageSourceFile": "src/main/ets/pages/HspAPageOne.ets","buildFunction": "HspAPageOneBuilder","data": {"description": "this is HspAPageOne"}}]
}
页面路由关系图
┌─────────────────┐│ Index ││ (首页) │└─────────┬───────┘│┌─────────┴───────┐│ │┌───────────┴──────┐ ┌───────┴──────────┐ ┌───────────┴──────┐│ EntryPageOne │ │ HarAPageOne │ │ HspAPageOne ││ (主模块页面) │ │ (HAR库页面) │ │ (HSP共享页面) │└─────────┬────────┘ └────────┬─────────┘ └─────────┬────────┘│ │ │└────────────────────┼──────────────────────┘│┌─────────────────┴─────────────────┐│ 返回首页 ││ (pathStack.clear()) │└───────────────────────────────────┘
路由跳转实现
1. 首页 (Index.ets)
首页包含三个按钮，分别跳转到不同的页面：
// 跳转到主模块页面
Button($r('app.string.entry_pageOne')).onClick(() => {this.pathStack.pushPathByName('EntryPageOne', '从首页到EntryPageOne');})// 跳转到HAR库页面
Button($r('app.string.harA_pageOne')).onClick(() => {this.pathStack.pushPathByName('HarAPageOne', '从首页到HarAPageOne');})// 跳转到HSP共享页面
Button($r('app.string.hspA_pageOne')).onClick(() => {this.pathStack.pushPathByName('HspAPageOne', '从首页到HspAPageOne');})
2. 主模块页面 (PageOne.ets)
// 返回首页
Button('toEntryIndex').onClick(() => {this.pathStack.clear();})// 跳转到HAR库页面
Button('to_HarA_PageOne').onClick(() => {this.pathStack.pushPathByName('HarAPageOne', '从EntryPageOne到HarAPageOne');})// 跳转到HSP共享页面
Button('to_HspA_PageOne').onClick(() => {this.pathStack.pushPathByName('HspAPageOne', '从EntryPageOne到HspAPageOne');})
3. HAR库页面 (HarAPageOne.ets)
// 返回首页
Button('toEntryIndex').onClick(() => {this.pathStack.clear();})// 跳转到主模块页面
Button('to_Entry_PageOne').onClick(() => {this.pathStack.pushPathByName('EntryPageOne', '从HarAPageOne到EntryPageOne');})// 跳转到HSP共享页面
Button('to_HspA_PageOne').onClick(() => {this.pathStack.pushPathByName('HspAPageOne', '从HarAPageOne到HspAPageOne');})
4. HSP共享页面 (HspAPageOne.ets)
// 返回首页
Button('toEntryIndex').onClick(() => {this.pathStack.clear();})// 跳转到主模块页面
Button('to_Entry_PageOne').onClick(() => {this.pathStack.pushPathByName('EntryPageOne', '从HspAPageOne到EntryPageOne');})// 跳转到HAR库页面
Button('to_HarA_PageOne').onClick(() => {this.pathStack.pushPathByName('HspAPageOne', '从HspAPageOne到HarAPageOne');})
关键API说明
1. NavPathStack
NavPathStack 是 HarmonyOS 提供的导航路径栈，用于管理页面导航状态：
pushPathByName(name: string, param?: Object): 通过页面名称推入新页面clear(): 清空导航栈，返回首页
2. NavDestination
每个页面都包装在 NavDestination 组件中，提供导航上下文：
NavDestination().onReady((context: NavDestinationContext) => {this.pathStack = context.pathStack;this.paramStr = context.pathInfo.param as string;})
3. Navigation
首页使用 Navigation 组件作为导航容器：
Navigation(this.pathStack) {// 页面内容
}路由跳转流程
- 应用启动:
EntryAbility加载首页Index - 页面跳转: 用户点击按钮，调用
pathStack.pushPathByName()跳转 - 参数传递: 跳转时可以传递参数，在目标页面的
onReady回调中接收 - 返回首页: 调用
pathStack.clear()清空导航栈，返回首页
注意事项
- 模块依赖: 确保在
oh-package.json5中正确配置模块依赖关系 - 路由名称: 路由名称必须与
router_map.json中的name字段一致 - 页面构建函数: 每个页面都需要提供对应的构建函数（如
PageOneBuilder） - 导航栈管理: 合理使用
clear()方法，避免导航栈过深
总结
RouterNavigationDemo 项目展示了 HarmonyOS 中多模块页面路由跳转的完整实现方案，通过 NavPathStack 和 router_map.json 配置，实现了跨模块的页面导航功能。这种架构设计使得应用具有良好的模块化特性，便于维护和扩展。