Navigation 组件导航的使用

前言：

通常在页面跳转中会用到@ohos.router页面路由和Navigation组件导航，当前推荐使用Navigation组件导航。原因是Navigation组件适用于模块内和跨模块的路由切换，具有组件级路由能力，可实现更流畅的转场效果，Navigation组件还可提供多种标题栏样式。在“一多开发”中，Navigation组件能自动适配窗口来显示大小。下面详细介绍Navigation组件。

Navigation组件

Navigation是路由导航的根视图容器，一般作为页面（@Entry）的根容器，包括单栏（Stack）、分栏（Split）和自适应（Auto）三种显示模式。它主要包含NavBar导航页和NavDestination子页。

NavBar由Titlebar标题栏和Navigation子组件内容区和Toolbar工具栏三部分组成。导航页可通过hideNavBar隐藏，导航页不在页面栈中。在API Version 9上，Navigation需要配合NavRouter组件实现页面路由。从API Version 10开始，更推荐使用NavPathStack实现页面路由。

页面显示模式

通过mode属性设置，默认为自适应模式。mode属性为NavigationMode.Auto。自适应模式下，当页面宽度大于等于一定520vp（API version 9及以前）；600vp（API version 10及以后）时，Navigation组件采用分栏模式，反之采用单栏模式。

标题栏模式

通过titleMode属性设置，有Mini和Full两种模式。

NavigationTitleMode.Mini	普通型，用于一级页面不需要突出标题的场景
NavigationTitleMode.Full	强调型，用于一级页面需要突出标题的场景

工具栏

通过toolbarConfiguration属性设置。位于Navigation底部。

路由

Navigation路由相关的操作都是基于页面栈NavPathStack提供的方法进行，每个Navigation都需要创建并传入一个NavPathStack对象，用于管理页面。主要涉及页面跳转、页面返回、页面替换、页面删除、参数获取、路由拦截等功能。

页面跳转

NavPathStack通过Push相关的接口去实现页面跳转的功能，主要分为以下三类:

一、普通跳转，通过页面的name去跳转，并可以携带param。

this.pageStack.pushPath({ name: "PageOne", param: "PageOne Param" })
this.pageStack.pushPathByName("PageOne", "PageOne Param")

二、带返回回调的跳转，跳转时添加onPop回调，能在页面出栈时获取返回信息，并进行处理。

this.pageStack.pushPathByName('PageOne', "PageOne Param", (i) => {
console.log(JSON.stringify(i))
  
});

三、带错误码的跳转，跳转结束会触发异步回调，返回错误码信息。

this.pageStack.pushDestinationByName('PageOne', "PageOne Param")
.catch((error: BusinessError) => {
  console.error(`Push destination failed, error code = ${error.code}, error.message = ${error.message}.`);
}).then(() => {
  console.info('Push destination succeed.');
});

页面返回

NavPathStack通过Pop相关接口去实现页面返回功能。

// 返回到上一页
this.pageStack.pop()
// 返回到上一个PageOne页面
this.pageStack.popToName("PageOne")
// 返回到索引为1的页面
this.pageStack.popToIndex(1)
// 返回到根首页（清除栈中所有页面）
this.pageStack.clear()

页面替换

NavPathStack通过Replace相关接口去实现页面替换功能。

// 将栈顶页面替换为PageOne
this.pageStack.replacePath({ name: "PageOne", param: "PageOne Param" })
this.pageStack.replacePathByName("PageOne", "PageOne Param")

页面删除

NavPathStack通过Remove相关接口去实现删除页面栈中特定页面的功能。

// 删除栈中name为PageOne的所有页面
this.pageStack.removeByName("PageOne")
// 删除指定索引的页面
this.pageStack.removeByIndexes([1,3,5])

参数获取

NavPathStack通过Get相关接口去获取页面的一些参数。

// 获取栈中所有页面name集合
this.pageStack.getAllPathName()
// 获取索引为1的页面参数
this.pageStack.getParamByIndex(1)
// 获取PageOne页面的参数
this.pageStack.getParamByName("PageOne")
// 获取PageOne页面的索引集合
this.pageStack.getIndexByName("PageOne")

路由拦截

NavPathStack提供了setInterception方法，用于设置Navigation页面跳转拦截回调。该方法需要传入一个NavigationInterception对象，该对象包含三个回调函数：

willShow	页面跳转前回调，允许操作栈，在当前跳转生效。
didShow	页面跳转后回调，在该回调中操作栈会在下一次跳转生效。
modeChange	Navigation单双栏显示状态发生变更时触发该回调。

可以在willShow回调中通过修改路由栈来实现路由拦截重定向的能力。

this.pageStack.setInterception({
  willShow: (from: NavDestinationContext | "navBar", to: NavDestinationContext | "navBar",
    operation: NavigationOperation, animated: boolean) => {
    if (typeof to === "string") {
      console.log("target page is navigation home page.");
      return;
    }
    // 将跳转到PageTwo的路由重定向到PageOne
    let target: NavDestinationContext = to as NavDestinationContext;
    if (target.pathInfo.name === 'PageTwo') {
      target.pathStack.pop();
      target.pathStack.pushPathByName('PageOne', null);
    }
  }
})

子页面

NavDestination是Navigation子页面的根容器，用于承载子页面的一些特殊属性以及生命周期等。

页面显示类型

属性mode为NavDestinationMode.STANDARD是标准类型，其生命周期随其在NavPathStack页面栈中的位置变化而改变。

属性mode为NavDestinationMode.DIALOG是弹窗类型，整个NavDestination默认透明显示。弹窗类型的NavDestination显示和消失时不会影响下层标准类型的NavDestination的显示和生命周期，两者可以同时显示。

页面的生命周期

Navigation作为路由容器，其生命周期承载在NavDestination组件上，以组件事件的形式开放。

生命周期大致可分为三类，自定义组件生命周期、通用组件生命周期和自有生命周期。aboutToAppear和aboutToDisappear是自定义组件的生命周期(NavDestination外层包含的自定义组件)，Onappear和OnDisappear是组件的通用生命周期。剩下的六个生命周期为NavDestination独有。

aboutToAppear：在创建自定义组件后，执行其build()函数之前执行（NavDestination创建之前），允许在该方法中改变状态变量，更改将在后续执行build()函数中生效。

onWillAppear：NavDestination创建后，挂载到组件树之前执行，在该方法中更改状态变量会在当前帧显示生效。

onAppear：通用生命周期事件，NavDestination组件挂载到组件树时执行。

onWillShow：NavDestination组件布局显示之前执行，此时页面不可见（应用切换到前台不会触发）。

onShown：NavDestination组件布局显示之后执行，此时页面已完成布局。

onWillHide：NavDestination组件触发隐藏之前执行（应用切换到后台不会触发）。

onHidden：NavDestination组件触发隐藏后执行（非栈顶页面push进栈，栈顶页面pop出栈或应用切换到后台）。

onWillDisappear：NavDestination组件即将销毁之前执行，如果有转场动画，会在动画前触发（栈顶页面pop出栈）。

onDisappear：通用生命周期事件，NavDestination组件从组件树上卸载销毁时执行。

aboutToDisappear：自定义组件析构销毁之前执行，不允许在该方法中改变状态变量。

页面监听和查询

为了方便组件跟页面解耦，在NavDestination子页面内部的自定义组件可以通过全局方法监听或查询到页面的一些状态信息。

页面监听

通过observer.on('navDestinationUpdate')提供的注册接口可以注册NavDestination生命周期变化的监听。

uiObserver.on('navDestinationUpdate', (info) => {
     console.info('NavDestination state update', JSON.stringify(info));
 });

页面信息查询

自定义组件提供queryNavDestinationInfo方法，可以在NavDestination内部查询到当前所属页面的信息，返回值为NavDestinationInfo，若查询不到则返回undefined。

 import { uiObserver } from '@kit.ArkUI';

 // NavDestination内的自定义组件
 @Component
 struct MyComponent {
   navDesInfo: uiObserver.NavDestinationInfo | undefined

   aboutToAppear(): void {
     this.navDesInfo = this.queryNavDestinationInfo();
   }

   build() {
       Column() {
         Text("所属页面Name: " + this.navDesInfo?.name)
       }.width('100%').height('100%')
   }
 }

页面转场

Navigation默认提供了页面切换的转场动画，通过页面栈操作时，会触发不同的转场效果（Dialog类型的页面默认无转场动画），Navigation也提供了关闭系统转场、自定义转场以及共享元素转场的能力。

关闭转场

1. 全局关闭

Navigation通过NavPathStack中提供的disableAnimation方法可以在当前Navigation中关闭或打开所有转场动画。

pageStack: NavPathStack = new NavPathStack()

aboutToAppear(): void {
  this.pageStack.disableAnimation(true)
}

2. 单次关闭

NavPathStack中提供的Push、Pop、Replace等接口中可以设置animated参数，默认为true表示有转场动画，需要单次关闭转场动画可以置为false，不影响下次转场动画。

pageStack: NavPathStack = new NavPathStack()

this.pageStack.pushPath({ name: "PageOne" }, false)
this.pageStack.pop(false)

共享元素转场

NavDestination之间切换时可以通过geometryTransition实现共享元素转场。配置了共享元素转场的页面同时需要关闭系统默认的转场动画。

1. 为需要实现共享元素转场的组件添加geometryTransition属性，id参数必须在两个NavDestination之间保持一致。

// 起始页配置共享元素id
NavDestination() {
Column() {
    // ...
    Image($r('app.media.startIcon'))
    .geometryTransition('sharedId')
    .width(100)
    .height(100)
}
}
.title('FromPage')

// 目的页配置共享元素id
NavDestination() {
Column() {
    // ...
    Image($r('app.media.startIcon'))
    .geometryTransition('sharedId')
    .width(200)
    .height(200)
}
}
.title('ToPage')

2. 将页面路由的操作，放到animateTo动画闭包中，配置对应的动画参数以及关闭系统默认的转场。

NavDestination() {
Column() {
    Button('跳转目的页')
    .width('80%')
    .height(40)
    .margin(20)
    .onClick(() => {
        this.getUIContext()?.animateTo({ duration: 1000 }, () => {
          this.pageStack.pushPath({ name: 'ToPage' }, false)
        })
    })
}
}
.title('FromPage')

跨包动态路由

通过静态import页面再进行路由跳转的方式会造成不同模块之间的依赖耦合，以及首页加载时间长等问题。

动态路由设计的初衷旨在解决多个模块（HAR/HSP）能够复用相同的业务逻辑，实现各业务模块间的解耦，同时支持路由功能的扩展与整合。

动态路由优势：1. 路由定义除了跳转的URL以外，可以丰富的配置扩展信息，如横竖屏默认模式，是否需要鉴权等等，做路由跳转时统一处理。2. 给每个路由页面设置一个名字，按照名称进行跳转而不是文件路径。3. 页面的加载可以使用动态import（按需加载），防止首个页面加载大量代码导致卡顿。

动态路由提供系统路由表和自定义路由表两种实现方式。系统路由表相对自定义路由表，使用更简单，只需要添加对应页面跳转配置项，即可实现页面跳转。自定义路由表使用起来更复杂，但是可以根据应用业务进行定制处理。

系统路由表

各业务模块（HSP/HAR）中需要独立配置route_map.json文件，在触发路由跳转时，应用只需要通过NavPathStack提供的路由方法，传入需要路由的页面配置名称，此时系统会自动完成路由模块的动态加载、页面组件构建，并完成路由跳转，从而实现了开发层面的模块解耦。其主要步骤如下：

1. 在跳转目标模块的配置文件module.json5添加路由表配置：

  {
    "module" : {
      "routerMap": "$profile:route_map"
    }
  }

2. 添加完路由配置文件地址后，需要在工程resources/base/profile中创建route_map.json文件。添加如下配置信息：

  {
    "routerMap": [
      {
        "name": "PageOne",   // 跳转页面名称
        "pageSourceFile": "src/main/ets/pages/PageOne.ets", // 跳转目标页在包内的路径，相对src目录的相对路径。
        "buildFunction": "PageOneBuilder", // 跳转目标页的入口函数名称，必须以@Builder修饰。
        "data": {
          "description" : "this is PageOne" 
        }  // 应用自定义字段。可以通过配置项读取接口getConfigInRouteMap获取。
      }
    ]
  }

3. 在跳转目标页面中，需要配置入口Builder函数，函数名称需要和route_map.json配置文件中的buildFunction保持一致，否则在编译时会报错。

  // 跳转页面入口函数
  @Builder
  export function PageOneBuilder() {
    PageOne()
  }

  @Component
  struct PageOne {
    pathStack: NavPathStack = new NavPathStack()

    build() {
      NavDestination() {
      }
      .title('PageOne')
      .onReady((context: NavDestinationContext) => {
         this.pathStack = context.pathStack
      })
    }
  }

4. 通过pushPathByName等路由接口进行页面跳转。(注意：此时Navigation中可以不用配置navDestination属性)。

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

    build() {
      Navigation(this.pageStack){
      }.onAppear(() => {
        this.pageStack.pushPathByName("PageOne", null, false);
      })
      .hideNavBar(true)
    }
  }

自定义路由表

关于自定义路由表可参考Navigation自定义动态路由 示例。

注：本文参考华为开发者文档编写。