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) {// 页面内容
}

路由跳转流程

1. 应用启动: EntryAbility 加载首页 Index
2. 页面跳转: 用户点击按钮，调用 pathStack.pushPathByName() 跳转
3. 参数传递: 跳转时可以传递参数，在目标页面的 onReady 回调中接收
4. 返回首页: 调用 pathStack.clear() 清空导航栈，返回首页

注意事项

1. 模块依赖: 确保在 oh-package.json5 中正确配置模块依赖关系
2. 路由名称: 路由名称必须与 router_map.json 中的 name 字段一致
3. 页面构建函数: 每个页面都需要提供对应的构建函数（如 PageOneBuilder）
4. 导航栈管理: 合理使用 clear() 方法，避免导航栈过深

总结

RouterNavigationDemo 项目展示了 HarmonyOS 中多模块页面路由跳转的完整实现方案，通过 NavPathStack 和 router_map.json 配置，实现了跨模块的页面导航功能。这种架构设计使得应用具有良好的模块化特性，便于维护和扩展。

项目地址