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 配置，实现了跨模块的页面导航功能。这种架构设计使得应用具有良好的模块化特性，便于维护和扩展。