docs_zh/zh-cn/application-dev/ui/arkts-navigation-architecture.md-代码预览-docs_zh:基于 OpenHarmony 的开发者文档项目 - AtomGit

H-xinweiNavigation DOC Optimization, review modify

86c6a889创建于 2025年12月4日历史提交

导航组件（Navigation）主要用于实现NavDestination页面间的跳转，支持在不同NavDestination间传递参数，提供灵活的跳转栈操作，从而更便捷地实现对不同页面的访问和复用。Navigation组件结构较为复杂，包含几个关键概念：

Navigation：导航根视图容器，所有的导航页面都被此容器包裹，提供分栏显示的能力，一般用作全局的根容器。
NavDestination：子页面容器，导航的所有页面路由操作均是针对NavDestination的操作，主要包含：
- 标题栏：包括返回按钮、标题和菜单，系统提供默认风格，同时支持自定义。
- 内容区：NavDestination的子组件，内容由开发者自定义。
- 工具栏：位于NavDestination底部，系统提供默认风格，同时支持自定义。
NavBar：导航栏，也称为主页面，主要包含：
- 标题栏：位于NavBar顶部，包括标题与菜单栏，系统提供默认风格，同时支持自定义。
- 内容区：位于NavBar中心区域，内容由开发者自定义。
- 工具栏：位于NavBar底部，系统提供默认风格，同时支持自定义。
NavPathStack：导航控制器，用于管理NavDestination页面栈，其封装了各种控制页面跳转的接口，支持继承后重写，需与Navigation绑定使用。

图1 Navigation总体架构图

NavigationArchitectureDiagram

此外Navigation提供两种布局模式：单栏模式、分栏模式，不同模式下的结构如下。

单栏模式：

当Navigation容器宽度小于600vp时，建议使用单栏模式。此模式下发生路由跳转时，整个页面都会被替换。

图2 单栏布局示意图
分栏模式：

当Navigation容器宽度大于600vp时，建议使用分栏模式。此模式下Navigation分为左右两部分，左侧为导航栏（NavBar）右侧为子页面（NavDestination），发生路由跳转时，只有右边子页会被替换。

图3 分栏布局示意图

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

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

Navigation组件主要包含导航栏（NavBar）和子页（NavDestination），子页通过栈结构管理，存在NavPathStack中。导航栏又称Navbar，作为Navigation的子组件，直接挂载到Navigation上，可以通过hideNavBar属性进行隐藏（单栏应用推荐隐藏导航页），导航栏不存在页面栈中。

子页面是一个以NavDestination为根节点的子树，通过@Builder构造出来，再通过NavPathStack提供的栈操作方法挂载到Navigation上显示，详见Navigation子页面。

NavDestination（子页面容器）

Navigation子页面的根容器，每个子页面都需要包裹在一个NavDestination中，通过NavPathStack提供的栈操作方法（push、pop等）将子页面挂载到Navigation上显示或删除。

NavDestination作为页面根容器，除了支持普通组件的通用属性外，还支持页面相关的属性，如：页面的生命周期，页面工具栏、标题栏与菜单栏，自定义页面转场动画，页面级窗口属性控制（横竖屏、系统状态栏、系统导航条）等能力。

Navigation中直接加载的孩子节点称为导航栏（NavBar），单栏显示时它是整个导航的首页，分栏显示时它是固定的导航栏。分栏显示时默认显示在左边，也可以通过navBarPosition属性控制。

开发者可以通过hideNavBar控制导航栏的显隐，也可以通过navBarWidth属性控制双栏显示下的Navbar宽度，NavBar本身不属于页面栈中的页面，不具备页面的生命周期等，不能通过NavPathStack的方法控制。开发者可以通过onNavBarStateChange去感知导航栏的显隐，通过mode属性控制单双栏切换，也可以通过onNavigationModeChange去感知单双栏的切换。

NavBar的内容区可以通过两种方式指定：

方式一：直接指定Navigation的子节点。

    Navigation(this.stack) {
      Stack({ alignContent: Alignment.Center }) {
        // ...
      }
      .width('100%')
      .height('100%')
    }
    .width('100%')
    .height('100%')
    .title('Navigation')

NavigationExample.ets

方式二：从API version 20开始，使用主页类型NavDestination将某个NavDestination直接指定为导航栏内容，此方法需要配置路由表，配置方式请参考路由表。

NavPathStack（导航控制器）

Navigation的子页面栈存在NavPathStack中，每个Navigation都需要绑定一个NavPathStack对象，NavPathStack用于控制Navigation中所有子页的切换。NavPathStack提供了很多基础的路由切换方法，如：pushPath、pop、replacePath等，以及路由拦截、转场动画控制、路由栈信息获取等能力。

NavPathStack也支持开发者继承并复写相关路由操作方法。NavPathStack跟Navigation一一对应，在每个子页中可以通过NavDestination的onReady回调获取，也可以全局维护一个单例的NavPathStack，在任意地方获取并执行路由操作（注意：页面切换动画和布局必须在UI线程中才可以生效，依赖Vsync信号）。

标题栏、工具栏与菜单栏

设置标题栏模式

标题栏在界面顶部，用于呈现界面名称和操作入口，Navigation组件通过title属性设置标题内容，通过titleMode属性设置标题栏模式。

说明：

Navigation未设置title属性时，即使将hideBackButton设置为false，返回按钮也不会展示。

Mini模式：

普通型标题栏，用于一级页面不需要突出标题的场景。

图4 Mini模式标题栏
```
Navigation() {
  // ...
}
.titleMode(NavigationTitleMode.Mini)
```
TitleModeMini.ets
Full模式：

强调型标题栏，用于一级页面需要突出标题的场景。

图5 Full模式标题栏
```
Navigation() {
  // ...
}
.titleMode(NavigationTitleMode.Full)
```
TitleModeFull.ets

设置菜单栏

菜单栏位于Navigation组件的右上角，开发者可以通过menus属性进行设置。menus支持Array<NavigationMenuItem>和CustomBuilder两种参数类型。使用Array<NavigationMenuItem>类型时，竖屏最多支持显示3个图标，横屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。

图6 设置了3个图标的菜单栏

菜单栏2

let toolTmp: NavigationMenuItem  = {
  'value': 'func',
  'icon': 'ets/pages/navigation/template1/image/ic_public_add.svg',
  'action': () => {}
};
// ...
      Navigation(this.navPathStack) {
        // ...
      }
      .menus([toolTmp, toolTmp, toolTmp])

MenusThreeImage.ets

图片也可以引用resources中的资源。

let toolTmp: NavigationMenuItem  = {
  'value': 'func',
  'icon': 'resources/base/media/ic_public_add.svg',
  'action': () => {}
};
// ...
      Navigation(this.navPathStack) {
        // ...
      }
      .menus([toolTmp, toolTmp, toolTmp])

MenusThreeResource.ets

图7 设置了4个图标的菜单栏

菜单栏

竖屏状态下菜单栏，最多支持显示3个按钮，当按钮超过3个时，多余的按钮会被折叠。

let toolTmp: NavigationMenuItem  = {
  'value': 'func',
  'icon': 'ets/pages/navigation/template1/image/ic_public_add.svg',
  'action': () => {}
};
// ...
      Navigation(this.navPathStack) {
        // ...
      }
      // 竖屏最多支持显示3个图标，多余的图标会被放入自动生成的更多图标
      .menus([toolTmp, toolTmp, toolTmp, toolTmp])

MenusFour.ets

设置工具栏

工具栏位于Navigation组件的底部，开发者可以通过toolbarConfiguration属性进行设置。

图8 工具栏

free3

let toolTmp: ToolbarItem = {
  'value': 'func',
  'icon': 'ets/pages/navigation/template1/image/ic_public_highlights.svg',
  'action': () => {}
};
let toolBar: ToolbarItem[] = [toolTmp,toolTmp,toolTmp];
// ...
      Navigation(this.navPathStack) {
        // ...
      }
      .toolbarConfiguration(toolBar)

ToolBar.ets

Navigation基础架构介绍

Navigation（导航容器）