引言

在之前的课程中，已经学习了使用 Tabs 构建页签实现页面切换。然而，在应用开发中还存在另一类常见场景——点击按钮跳转页面，例如点击登录按钮后从登录页跳转到应用首页。这类场景需要使用 Navigation 导航组件来实现。本节课将系统讲解 Navigation 的基础概念、核心组成与开发流程，并通过登录跳转首页的案例，演示完整页面跳转功能的实现方法。

核心内容

Navigation 导航基础介绍

导航的定义：导航是允许用户跨越、进入和退出应用不同内容片段的交互方式，典型场景为点击登录按钮后从登录页跳转到应用首页。

Navigation 组件定位：Navigation 是 HarmonyOS 提供的路由容器组件，一般作为应用首页的根容器，默认包含导航页。导航页结构由标题栏（内嵌菜单栏）、内容区、工具栏三部分组成；子页 NavDestination 可设置独立的标题栏和菜单栏，使用方式与 Navigation 一致。

自适应分栏能力：Navigation 天然支持自适应分栏布局能力，可根据设备屏幕尺寸自动切换单栏/分栏显示模式，无需开发者手动适配。

导航转场能力：Navigation 支持自定义页面切换转场动画，可使用系统默认转场、关闭转场、自定义转场或共享元素转场。

Navigation 路由核心组成

实现页面跳转需要四个核心元素：导航页根容器 Navigation、子页容器 NavDestination、路由表 RouterMap、路由栈 NavPathStack。

导航页 Navigation 与子页 NavDestination

• Navigation：整个路由导航的根视图容器，一般在应用入口文件 Index 中使用，负责承载导航结构。

• NavDestination：用于显示 Navigation 内容区的子页面根容器，一般作为跳转目标页使用，每个子页都用该组件作为根容器。

核心属性对比：

属性名称	Navigation 说明	NavDestination 说明
mode	设置页面显示模式	不支持
title	设置页面标题	设置页面标题
menus	设置页面右上角菜单	设置页面右上角菜单
toolbarConfiguration	设置工具栏内容	不支持
hideToolBar	设置是否隐藏工具栏	不支持
hideTitleBar	设置是否隐藏标题栏	设置是否隐藏标题栏

路由表 RouterMap

路由表用于存储跳转路径与对应视图组件的映射关系，是 Navigation 推荐使用的路由存储方式。触发跳转时，开发者只需传入目标页面名称，系统会自动完成模块加载、组件构建并完成跳转。

路由表核心配置项：

配置项	说明
name	跳转页面的唯一标识名称
pageSourceFile	跳转目标页相对 src 目录的相对路径
buildFunction	跳转目标页的入口函数名称，必须被 @Builder 装饰，函数名需要与页面内定义的入口函数完全一致
data	应用自定义字段，可通过接口 getConfigInRouteMap 读取

创建步骤：

1. 在 profile 目录下创建路由表配置文件（JSON 格式）。

2. 添加各个页面的配置信息（name、pageSourceFile、buildFunction、data）。

3. 在 module.json5 中引入该路由表文件即可完成配置。

路由表配置示例：

// profile/router_map.json
{
  "routerMap": [
    {
      "name": "LoginPage",
      "pageSourceFile": "pages/LoginPage",
      "buildFunction": "LoginPageBuilder",
      "data": {
        "description": "登录页面"
      }
    },
    {
      "name": "MainPage",
      "pageSourceFile": "pages/MainPage",
      "buildFunction": "MainPageBuilder",
      "data": {
        "description": "应用首页"
      }
    }
  ]
}

// module.json5 中引入路由表
{
  "module": {
    // ...
    "routerMap": "$profile:router_map"
  }
}

路由栈 NavPathStack

NavPathStack 是 Navigation 的路由管理器，需要创建实例后传入 Navigation 组件，提供一系列路由操作方法：

方法	说明
push	跳转新页面，将当前页面压入栈
pop	返回上一级页面，弹出当前页面
replace	替换当前页面为目标页面

登录跳转案例开发步骤

步骤 1：创建页面结构

登录页 LoginPage：使用 Navigation 作为根容器，通过 hideTitleBar 和 hideToolBar 隐藏标题栏和工具栏，在内容区放置登录表单。

// pages/LoginPage.ets
@Component
struct LoginPage {
  @State username: string = '';
  @State password: string = '';

  build() {
    Navigation() {
      Column() {
        Image($r('app.media.logo'))
          .width(100)
          .height(100)
          .margin({ top: 80 })
        Text('欢迎登录')
          .fontSize(28)
          .fontWeight(FontWeight.Bold)
          .margin({ top: 40 })
        TextInput({ placeholder: '请输入账号' })
          .width('80%')
          .margin({ top: 40 })
          .onChange((value) => { this.username = value; })
        TextInput({ placeholder: '请输入密码' })
          .width('80%')
          .margin({ top: 20 })
          .type(InputType.Password)
          .onChange((value) => { this.password = value; })
        Button('登录')
          .width('80%')
          .type(ButtonType.Capsule)
          .backgroundColor('#007dff')
          .fontColor(Color.White)
          .margin({ top: 40 })
          .onClick(() => {
            this.login();
          })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    .hideTitleBar(true)
    .hideToolBar(true)
  }
}

@Builder
export function LoginPageBuilder() {
  LoginPage()
}

首页 MainPage：使用 Navigation 作为根容器，隐藏标题栏，内部放置需要展示的内容（如 Tabs 页签）。

// pages/MainPage.ets
@Component
struct MainPage {
  build() {
    Navigation() {
      // 首页内容，如 Tabs 页签
      Tabs() {
        TabContent() {
          Text('首页内容')
        }
        .tabBar('首页')
        TabContent() {
          Text('我的内容')
        }
        .tabBar('我的')
      }
      .barPosition(BarPosition.End)
    }
    .hideTitleBar(true)
  }
}

@Builder
export function MainPageBuilder() {
  MainPage()
}

步骤 2：配置路由表

在 profile 目录下创建路由表文件，分别配置 LoginPage 和 MainPage 的路径、入口函数信息，在 module.json5 中引入路由表。

步骤 3：实现路由跳转

1. 在 LoginPage 中创建 NavPathStack 实例，将实例传入 Navigation 组件。

2. 给登录按钮绑定点击事件，在点击回调中调用 NavPathStack 的 pushPathByName 方法，传入目标页名称 MainPage 和跳转参数，即可完成跳转。

// pages/LoginPage.ets（添加路由跳转逻辑）
@Component
struct LoginPage {
  @State username: string = '';
  @State password: string = '';
  private navPathStack: NavPathStack = new NavPathStack();

  login() {
    // 登录验证逻辑
    this.navPathStack.pushPathByName('MainPage', { userId: '123456' });
  }

  build() {
    Navigation(this.navPathStack) {
      // ... 登录表单内容
    }
    .hideTitleBar(true)
    .hideToolBar(true)
  }
}

总结

本节课学习了 Navigation 导航组件的核心知识：

1. Navigation 组件定位：HarmonyOS 的路由容器组件，一般作为应用首页的根容器，天然支持自适应分栏布局，可根据设备尺寸自动切换单栏/分栏模式。

2. 导航页与子页：导航页由标题栏（内嵌菜单栏）、内容区、工具栏三部分组成；NavDestination 可设置独立的标题栏和菜单栏。两者均支持通过属性配置标题、菜单、隐藏控制等。

3. 路由核心组成：

   • Navigation：根视图容器。

   • NavDestination：子页面根容器。

   • RouterMap：路由表，存储路径与组件的映射关系，配置项包括 name、pageSourceFile、buildFunction（需 @Builder 装饰）、data。

   • NavPathStack：路由栈管理器，提供 push（跳转）、pop（返回）、replace（替换）等路由方法。

4. 登录跳转案例：三步实现——创建页面结构（Navigation + NavDestination）、配置路由表（profile 目录 + module.json5）、实现路由跳转（创建 NavPathStack 传入 Navigation，调用 pushPathByName）。