从 Router 到 Navigation：HarmonyOS 路由框架的全面升级与迁移指南

在本教程中，我们深入探讨了 Router 和 Navigation 在 HarmonyOS 中的用法差异及如何从 Router 切换到 Navigation 的方法。重点涵盖了页面跳转、转场动画、生命周期管理以及跨包路由的实现。

页面结构对比

Router 页面结构

每个页面需要使用 @Entry 注解。

页面需要在 main_page.json 中进行注册。

示例代码：

// main_page.json
{
  "src": [
    "pages/Index",
    "pages/pageOne",
    "pages/pageTwo"
  ]
}

Router 页面示例：

@Entry
@Component
struct Index {
  build() {
    Button('Navigate to PageOne')
      .onClick(() => {
        router.pushUrl({ url: 'pages/pageOne' });
      });
  }
}

Navigation 页面结构

基于组件化的设计。

需要一个 NavPathStack 对象来管理页面栈。

子页面通过 NavDestination 进行注册。

示例代码：

@Entry
@Component
struct Index {
  pathStack: NavPathStack = new NavPathStack();

  build() {
    Navigation(this.pathStack) {
      Button('Push PageOne')
        .onClick(() => this.pathStack.pushPathByName('pageOne'));
    }
    .title("Navigation");
  }
}

路由操作对比

生命周期管理

Router 生命周期

Router 页面依赖全局生命周期方法，主要包括：

aboutToAppear()

onPageShow()

aboutToDisappear()

onPageHide()

Navigation 生命周期

Navigation 生命周期基于 NavDestination 组件，提供了更多粒度的生命周期方法，如：

onWillAppear()

onAppear()

onWillDisappear()

onDisAppear()

动画支持

Router 转场动画

Router 提供系统预设和自定义动画，支持 sharedTransition 实现共享元素转场。

Navigation 转场动画

Navigation 内置转场动画机制，可通过 customNavContentTransition 自定义切换效果。同时支持通过 geometryTransition 属性实现共享元素转场。

跨包路由

Router 跨包路由

通过 @Entry 注解的 routeName 属性实现命名路由，并在主页面引入目标页面的路径。

示例代码：

import('library/src/main/ets/pages/Index');

router.pushNamedRoute({ name: 'myPage', params: { key: 'value' } });

Navigation 跨包路由

Navigation 内置支持跨包跳转，目标页面在子包中声明为 export 后，直接在 Navigation 中注册。

总结

Router 更适合简单的页面跳转需求，而 Navigation 提供了更丰富的栈操作、动画自定义和组件化管理能力。如果项目需要跨包跳转或复杂的页面管理，建议迁移至 Navigation 体系。