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

项目地址