HarmonyOS鸿蒙Next中Navigation系列一：ArkUI路由原理简介，认识Navigation组件

Navigation作为导航容器，主要用于实现页面间的路由跳转，Navigation导航既可以作为应用全局的导航容器，也可以作为局部的导航容器，如：在弹窗、模态等非全屏组件中使用。

1、Navigation（导航容器）

Navigation是路由导航的根视图容器，一般作为页面（@Entry修饰的自定义组件，定义为Router页面）的根容器（作为全局导航使用），包括单栏（Stack）、分栏（Split）和自适应（Auto）三种显示模式，Auto模式会基于Navigation组件的宽度自动在Stack（<600vp）和Split（>=600vp）中切换。

Navigation组件本身可不作为显示容器，只用于承载路由的相关功能，如绑定导航控制器对象，路由切换，分栏显示，自定义转场动画控制等。

Navigation组件主要包含导航栏（NavBar）和子页（NavDestination），子页通过栈结构管理（存在NavPathStack中）。导航栏又称Navbar（Navigation的子组件，直接挂载到Navigation上），可以通过hideNavBar属性进行隐藏（单栏应用推荐隐藏导航页），导航栏不存在页面栈中。子页面是一个以NavDestination为根节点的子树，通过@Builder构造出来，再通过NavPathStack提供的栈操作方法挂载到Navigation上显示，后续详细介绍。

2、NavPathStack（导航控制器）

Navigation的子页面栈存在NavPathStack中，每个Navigation都需要绑定一个NavPathStack对象，NavPathStack用于控制Navigation中所有子页的切换，NavPathStack提供了很多基础的路由切换方法，如：pushPath，pushDestination（带返回回调），pop，replacePath等，以及路由拦截，转场动画控制，路由栈信息获取等能力。NavPathStack也支持开发者继承并复写相关路由操作方法。 NavPathStack跟Navigation一一对应，在每个子页中可以通过NavDestination的onReady回调获取，也可以全局维护一个单例的NavPathStack，在任意地方获取并执行路由操作（注意：页面切换动画和布局必须在UI线程中才可以生效，依赖Vsync信号）

3、NavBar（导航栏）

我们把Navigation中直接加载的孩子节点称为导航栏（NavBar），单栏显示时它是整个导航的首页，分栏显示时它是固定的导航栏（默认显示在左边，也可以通过NavBarPosition属性控制），开发者可以通过hideNavBar去控制导航栏的显隐（推荐仅单栏显示的应用隐藏掉NavBar），也可以通过navBarWidth属性控制双栏显示下的Navbar宽度，NavBar本身不属于页面栈中的页面，不具备页面的生命周期等，不能通过NavPathStack的方法控制。开发者可以通过onNavBarStateChange去感知导航栏的显隐，通过mode属性控制单双栏切换，也可以通过onNavigationModeChange去感知单双栏的切换。

4、NavDestination（子页容器）

Navigation子页面的根容器，每个子页面都需要包裹在一个NavDestination中，通过NavPathStack提供的栈操作方法（push，pop等）将子页面挂载导Navigation上显示或删除。 NavDestination作为页面根容器，除了支持普通组件的通用属性外，还支持页面相关的属性，如：页面的生命周期，页面工具栏和标题栏，自定义页面转场动画，页面级窗口属性控制（横竖屏，系统状态栏，系统导航条）等能力。

整体导航架构图如下所示：单双栏显示的结构图：

下一章【ArkUI路由/导航系列】二：Navigation基础路由操作，让页面跳转起来

【系列其他文章】

更多关于HarmonyOS鸿蒙Next中Navigation系列一：ArkUI路由原理简介，认识Navigation组件的实战教程也可以访问 https://www.itying.com/category-93-b0.html

caililin 1楼

在HarmonyOS鸿蒙Next中，Navigation是ArkUI的核心路由组件，用于实现页面导航和跳转管理。其原理基于路由栈机制，支持页面压栈（push）、出栈（pop）及替换（replace）等操作。Navigation组件通过路由表（routes）配置页面路径，结合Router模块实现页面间参数传递与生命周期管理。

关键特性包括：

声明式路由：通过@Entry和@Route装饰器定义页面路由
动态导航：支持编程式跳转（router.pushUrl）和返回（router.back）
嵌套路由：可通过子导航器实现多级路由结构

Navigation组件包含NavigationStack（路由容器）和NavigationLink（导航链接），支持页面间平滑过渡动画。

更多关于HarmonyOS鸿蒙Next中Navigation系列一：ArkUI路由原理简介，认识Navigation组件的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html

wuwangju 2楼

这是一个很好的HarmonyOS Next中Navigation组件的原理介绍。我来总结几个关键点：

Navigation组件是ArkUI路由系统的核心容器，支持Stack/Split/Auto三种显示模式，Auto模式会根据屏幕宽度自动切换单栏/分栏布局。
路由管理通过NavPathStack实现，它提供了push/pop/replace等基础路由操作，以及路由拦截、动画控制等高级功能。
导航架构清晰分层：

Navigation作为根容器
NavBar作为导航栏(可隐藏)
NavDestination作为子页容器，管理页面生命周期和窗口属性

分栏布局时NavBar默认左侧显示，可以通过属性调整位置和宽度。
整个导航系统支持丰富的扩展能力，包括自定义转场动画、跨包路由、嵌套开发等(后续系列文章会详细介绍)。

这个架构设计既考虑了简单应用的快速开发(隐藏NavBar的单栏模式)，也支持复杂应用的高级路由需求(分栏、拦截、动画等)，是HarmonyOS应用开发的重要基础设施。