HarmonyOS 鸿蒙Next中Navigation的核心功能、使用模式、开发技巧及避坑指南：

一、核心定位与功能

组件角色

• 根容器：作为页面根布局，管理标题栏、工具栏、导航栏及内容区。
• 导航模式：支持三种显示模式：
  • Stack（单页面）：移动端主流模式，每次只显示一个页面。
  • Split（分栏）：大屏设备（如平板）分左右栏显示，左侧导航列表 + 右侧详情。
  • Auto（自适应）：设备宽度 >520vp 时自动切换为分栏模式，否则为单页。

与Router的关系

二、核心组件与结构

关键子组件

• NavDestination：定义内容页，需配置 title 和布局内容。
• NavRouter：导航项容器，必须包含两个子组件（如 Text + NavDestination），点击自动跳转至关联的 NavDestination。

路由栈管理

• NavPathStack：控制页面跳转逻辑，核心方法：
  • pushPathByName("PageName")：跳转至指定页面。
  • clear()：清空栈返回首页。
• 页面上下文传递：通过 NavDestinationContext 获取共享的 pathStack 实例。

三、路由配置方式

两种页面跳转实现

属性绑定

• 直接设置 navDestination 属性，需在 Builder 函数内包含 NavDestination 组件。

路由表配置（推荐）

步骤1

• 在 module.json5 声明路由表路径：

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

步骤2

• 在 resources/base/profile/ 创建 route_map.json：

{
  "routerMap": [
    {
      "name": "MainPage", // 页面名（支持中文）
      "pageSourceFile": "src/main/ets/pages/MainPage.ets",
      "buildFunction": "MainPageBuilder" // @Builder 入口函数
    }
  ]
}

注意：使用路由表时需移除 navDestination 属性，否则优先级冲突。

四、开发避坑指南

预览器限制

• 路由表配置的跳转在预览器中可能失败且无报错提示，需在本地模拟器测试。

NavRouter 子组件约束

• 子组件数必须为2，且第二个必须是 NavDestination，否则跳转失效。

路由传参陷阱

• Navigation 不支持直接传参，需结合 @ohos.router 的 params 传递对象（对象内禁含方法变量）。

五、高级特性

动态导航模式切换

.mode(NavigationMode.Auto) // 根据屏幕宽度自动切换布局

沉浸式标题栏

• 通过 titleMode 设置标题样式（Full/Mini/Free）。

共享元素动画

• 使用 geometryTransition 实现 NavDestination 间元素共享动画（Router 不支持）。

路由拦截

• 通过 setInterception 拦截跳转（如登录验证），Router 无此能力。

六、最佳实践总结

性能提示：

• 分栏模式（Split）适合平板/车机，单页模式（Stack）节省移动端内存；
• 使用 NavPathStack.removeByName() 清理无用页面栈，避免内存泄漏。

总结

Navigation 是鸿蒙 ArkUI 的强交互型导航容器，专注于同级页面的布局管理与视觉导航（如 Tab/分栏），需与 Router 协同实现完整路由能力。开发时优先采用路由表配置，严格遵循 NavRouter 子组件约束，并在模拟器中验证跳转逻辑，可高效构建自适应多端导航体系。