在鸿蒙应用开发中，页面路由导航是核心功能之一。Navigation 组件作为官方推荐的路由根视图容器，支持模块内 / 跨模块跳转，还能自动适配多端显示，提供流畅的转场体验。本文将基于实战笔记，拆解 Navigation 组件的使用步骤、配置细节和跳转逻辑，帮助开发者快速上手。

一、Navigation 组件核心介绍

1. 核心定位

Navigation 是路由导航的根容器，通常作为@Entry页面的根组件，负责管理页面跳转和转场效果。

2. 关键特性

• 支持三种显示模式：单栏（Stack）、分栏（Split）、自适应（Auto），自动适配多设备窗口大小。
• 适配 “一次开发，多端部署”，大屏设备自动切换分栏展示。
• 提供标题栏样式定制，支持隐藏 / 显示标题栏，实现标题与内容联动。
• 组件级路由能力，跳转耦合度低（注意：不适合大型项目的解耦开发）。

3. 适用场景

• 中小型应用的页面路由管理。
• 需适配手机、平板等多设备的应用。
• 追求简洁跳转逻辑和自然转场效果的场景。

二、Navigation 使用全步骤（含配置 + 代码）

第一步：初始化导航栈（NavPathStack）

导航栈是管理页面跳转的核心，需先定义全局导航栈实例，用于控制页面入栈 / 出栈。

// 通常在全局文件（如router/index.ets）中定义，方便多页面调用
import { NavPathStack } from '@ohos/router';

// 初始化导航栈
export const navPathStack: NavPathStack = new NavPathStack();

第二步：配置 module.json5 文件

需在配置文件中关联路由映射表，让应用识别跳转页面的路径。

总结

Navigation 组件是鸿蒙应用开发中简洁高效的路由解决方案，通过 “导航栈 + 路由映射表” 的组合，快速实现页面跳转和多端适配。本文梳理的五步流程（初始化导航栈→配置 module.json5→创建路由映射→编写目标页面→触发跳转），覆盖了从配置到实战的全场景，适合新手直接套用。

对于大型项目，若需更高的解耦能力，可结合鸿蒙的 ARouter 等框架扩展，但中小型项目使用 Navigation 组件足以满足需求。建议先通过本文案例实战练习，再根据项目复杂度灵活调整。

HarmonyOS赋能资源丰富度建设（第四期）-吴东林

https://developer.huawei.com/consumer/cn/training/classDetail/9fdeeb1a35d64d2fabad3948ae7aab72?type=1?ha_source=hmosclass&ha_sourceId=89000248

1. 找到src/main/module.json5，在module字段中添加outerMap配置：

   {
     "module": {
       "name": "entry",
       "type": "entry",
       "outerMap": "$profile:router_map", // 关联路由映射表
       "pages": "$profile:main_pages",
       // 其他配置（如abilities、deviceTypes等）
       "deviceTypes": ["phone", "tablet"] // 适配多设备
     }
   }

   第三步：创建路由映射表（router_map.json）

   在src/main/resources/base/profile目录下，新建router_map.json文件，配置跳转页面的名称、文件路径和构建函数。

   {
     "routerMap": [
       {
         "name": "BPage", // 页面标识（跳转时使用）
         "pageSourceFile": "src/main/ets/pages/BPage.ets", // 页面文件路径
         "buildFunction": "BBuilder" // 页面构建函数名称
       },
       {
         "name": "CPage",
         "pageSourceFile": "src/main/ets/pages/CPage.ets",
         "buildFunction": "CBuilder"
       },
       {
         "name": "DetailPage",
         "pageSourceFile": "src/main/ets/pages/DetailPage.ets",
         "buildFunction": "DetailBuilder"
       }
     ]
   }
   

   第四步：编写跳转页面（目标页面）

   目标页面需使用NavDestination作为根组件，并导出@Builder构建函数，供路由映射表调用。

   以DetailPage.ets为例：

   import { NavDestination } from '@ohos/router';
   
   // 目标页面组件
   @ComponentV2
   struct DetailPage {
     build() {
       NavDestination() { // 必须用NavDestination作为根组件
         Column() {
           Text("我是详情页面")
             .fontSize(20)
             .fontColor(Color.Black)
         }
         .width('100%')
         .height('100%')
         .backgroundColor(Color.Pink)
       }
       .hideTitleBar(true) // 隐藏页面标题栏（可选）
     }
   }
   
   // 导出构建函数（名称需与router_map.json中一致）
   @Builder
   export function DetailBuilder() {
     DetailPage()
   }

   第五步：实现页面跳转（主页面触发）

   在主页面（如 Index.ets）中，通过导航栈的pushPath方法触发跳转，主页面需用Navigation作为根容器。

   import { navPathStack } from '../router/index.ets'; // 导入全局导航栈
   
   @Entry
   @ComponentV2
   struct Index {
     build() {
       // 主页面根容器：Navigation，关联导航栈
       Navigation(navPathStack) {
         Column() {
           Text("路由到详情页面")
             .fontColor(Color.Blue)
             .fontSize(18)
             .onClick(() => {
               // 触发跳转：指定目标页面的name（与router_map.json一致）
               navPathStack.pushPath({ name: 'DetailPage' })
             })
         }
         .width('100%')
         .height('100%')
         .justifyContent(FlexAlign.Center)
       }
       .hideTitleBar(true) // 隐藏主页面标题栏（可选）
     }
   }

   三、关键注意事项

2. 页面结构要求：目标页面必须以NavDestination为根组件，且导出对应的@Builder构建函数，否则无法正常跳转。
3. 路由映射一致性：router_map.json中的name、pageSourceFile、buildFunction必须与实际页面文件名、构建函数名完全一致。
4. 导航栈全局共享：建议将navPathStack定义为全局变量，方便多页面调用（如返回、跳转传参等场景）。
5. 标题栏控制：通过hideTitleBar(true)隐藏标题栏，若需显示可配置标题栏样式（如title('页面标题')）。
6. 多设备适配：在module.json5的deviceTypes中配置支持的设备（如手机、平板），Navigation 会自动适配显示模式。
7. 跳转无响应：检查router_map.json路径是否正确（需在profile目录下）、配置字段是否拼写错误。
8. 页面空白：确认目标页面根组件是NavDestination，且已导出@Builder构建函数。
9. 多端显示异常：检查module.json5是否配置了对应设备类型，Navigation 需依赖设备信息自动切换显示模式。