# Navigation Navigation组件一般作为Page页面的根容器，通过属性设置来展示页面的标题栏、工具栏、导航栏等。 > **说明：** > > 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 ## 子组件 可以包含子组件。从API Version 9开始，推荐与[NavRouter](ts-basic-components-navrouter.md)组件搭配使用。 ## 接口 **方法1：** Navigation() **方法2：** Navigation(pathInfos: NavPathStack)10+ 绑定路由栈到Navigation组件。 **参数：** | 参数名 | 参数类型 | 必填 | 参数描述 | | ------- | ----------------------------------- | ---- | ------------- | | pathInfos | [NavPathStack](#navpathstack10) | 否 | 路由栈信息。 | ## 属性 除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： | 名称 | 参数类型 | 描述 | | ----------------------------- | ---------------------------------------- | ---------------------------------------- | | title | [ResourceStr](ts-types.md#resourcestr)10+ \| [CustomBuilder](ts-types.md#custombuilder8)8+ \| [NavigationCommonTitle](#navigationcommontitle类型说明)9+ \| [NavigationCustomTitle](#navigationcustomtitle类型说明)9+ | 页面标题。
**说明：**
使用NavigationCustomTitle类型设置height高度时，titleMode属性不会生效。
字符串超长时，如果不设置副标题，先缩小再换行（2行）最后...截断。如果设置副标题，先缩小最后...截断。 | | subTitle(deprecated) | string | 页面副标题。不设置时不显示副标题。从API Version 9开始废弃，建议使用title代替。 | | menus | Array<[NavigationMenuItem](#navigationmenuitem类型说明)> \| [CustomBuilder](ts-types.md#custombuilder8)8+ | 页面右上角菜单。不设置时不显示菜单项。使用Array<[NavigationMenuItem](#navigationmenuitem类型说明)> 写法时，竖屏最多支持显示3个图标，横屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。 | | titleMode | [NavigationTitleMode](#navigationtitlemode枚举说明) | 页面标题栏显示模式。
默认值：NavigationTitleMode.Free | | toolBar(deprecated) | [object](#object类型说明) \| [CustomBuilder](ts-types.md#custombuilder8)8+ | 设置工具栏内容。不设置时不显示工具栏。
items: 工具栏所有项。
**说明：**
items均分底部工具栏，在每个均分内容区布局文本和图标，文本超长时，逐级缩小，缩小之后换行，最后...截断。
从API version 10开始，该接口不再维护，推荐使用toolbarConfiguration代替。 | | toolbarConfiguration10+ | Array<[ToolbarItem](#toolbaritem10类型说明)10+> \| [CustomBuilder](ts-types.md#custombuilder8)8+ | 设置工具栏内容。不设置时不显示工具栏。
**说明：**
使用Array<[ToolbarItem](#ToolbarItem类型说明)>写法设置的工具栏有如下特性：
工具栏所有选项均分底部工具栏，在每个均分内容区布局文本和图标。
文本超长时，若工具栏选项个数小于5个，优先拓展选项的宽度，最大宽度与屏幕等宽，其次逐级缩小，缩小之后换行，最后...截断。
竖屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。横屏下必须配合menus属性的Array<[NavigationMenuItem](#navigationmenuitem类型说明)>使用，底部工具栏会自动隐藏，同时底部工具栏所有选项移动至页面右上角菜单。
使用[CustomBuilder](ts-types.md#custombuilder8)写法为用户自定义工具栏选项，除均分底部工具栏外不具备以上功能。 | | hideToolBar | boolean | 隐藏工具栏。
默认值：false
true: 隐藏工具栏。
false: 显示工具栏。 | | hideTitleBar | boolean | 隐藏标题栏。
默认值：false
true: 隐藏标题栏。
false: 显示标题栏。 | | hideBackButton | boolean | 隐藏返回键。
默认值：false
true: 隐藏返回键。
false: 显示返回键。
不支持隐藏NavDestination组件标题栏中的返回图标。
**说明：**
返回键仅针对titleMode为NavigationTitleMode.Mini时才生效。 | | navBarWidth9+ | [Length](ts-types.md#length) | 导航栏宽度。
默认值：200
单位：vp
**说明：**
仅在Navigation组件分栏时生效。 | | navBarPosition9+ | [NavBarPosition](#navbarposition枚举说明) | 导航栏位置。
默认值：NavBarPosition.Start
**说明：**
仅在Navigation组件分栏时生效。 | | mode9+ | [NavigationMode](#navigationmode枚举说明) | 导航栏的显示模式。
默认值：NavigationMode.Auto
自适应：基于组件宽度自适应单栏和双栏。
API version 9之前断点在520vp切换显示模式。API version 10之后断点在600vp，minNavBarWidth(240vp) + minContentWidth (360vp)切换显示模式。 | | backButtonIcon9+ | string \| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | 设置导航栏返回图标。不支持隐藏NavDestination组件标题栏中的返回图标。 | | hideNavBar9+ | boolean | 是否显示导航栏（仅在mode为NavigationMode.Split时生效）。 | | navDestination10+ | builder: (name: string, param: unknown) => void | 创建NavDestination组件。
**说明：**
使用builder函数，基于name和param构造NavDestination组件。builder中允许在NavDestination组件外包含一层自定义组件， 但自定义组件不允许设置属性和事件，否则仅显示空白。 | | navBarWidthRange10+ | [[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)] | 导航栏最小和最大宽度。
默认值：最小默认值 240，最大默认值为组件宽度的40% ，且不大于 432。
单位：vp
规则：
开发者设置优先级 > 默认值
最小值优先级 > 最大值
navBar 优先级 > content优先级
开发者设置多个值冲突，以全局数值优先，局部最小值跟随容器大小。 | | minContentWidth10+ | [Dimension](ts-types.md#dimension10) | 导航栏内容区最小宽度。
默认值：360
单位：vp
规则：
开发者设置优先级 > 默认值
最小值优先级 > 最大值
navBar优先级 > content优先级
开发者设置多个值冲突，以全局数值优先，局部最小值跟随容器大小。
Auto模式断点计算：默认600vp，minNavBarWidth(240vp) + minContentWidth (360vp) | ## NavPathStack10+ Navigation路由栈。 ### push10+ push(info: NavPathInfo): void 将info指定的NavDestination页面信息入栈。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | info | [NavPathInfo](#navpathinfo10) | 是 | NavDestination页面的信息。 | ### pushName10+ pushName(name: string, param: unknown): void 将name指定的NavDestination页面信息入栈，传递的数据为param。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | name | string | 是 | NavDestination页面名称。 | | param | unknown | 是 | NavDestination页面详细参数。 | ### pop10+ pop(): NavPathInfo | undefined 弹出路由栈栈顶元素。 **返回值：** | 类型 | 说明 | | ------ | -------- | | NavPathInfo | 返回栈顶NavDestination页面的信息。 | | undefined | 当路由栈为空时返回undefined。 | ### popTo10+ popTo(name: string): number 回退路由栈到第一个名为name的NavDestination页面。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | name | string | 是 | NavDestination页面名称。 | **返回值：** | 类型 | 说明 | | ------ | -------- | | number | 如果栈中存在名为name的NavDestination页面，则返回第一个名为name的NavDestination页面的索引，否则返回-1。 | ### popToIndex10+ popToIndex(index: number): void 回退路由栈到index指定的NavDestination页面。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | index | number | 是 | NavDestination页面的位置索引。 | ### moveToTop10+ moveToTop(name: string): number 将第一个名为name的NavDestination页面移到栈顶。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | name | string | 是 | NavDestination页面名称。 | **返回值：** | 类型 | 说明 | | ------ | -------- | | number | 如果栈中存在名为name的NavDestination页面，则返回第一个名为name的NavDestination页面的当前索引，否则返回-1。 | ### moveIndexToTop10+ moveIndexToTop(index: number): void 将index指定的NavDestination页面移到栈顶。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | index | number | 是 | NavDestination页面的位置索引。 | ### clear10+ clear(): void 清除栈中所有页面。 ### getAllPathName10+ getAllPathName(): Array 获取栈中所有NavDestination页面的名称。 **返回值：** | 类型 | 说明 | | ------ | -------- | | Array | 返回栈中所有NavDestination页面的名称。 | ### getParamByIndex10+ getParamByIndex(index: number): unknown | undefined 获取index指定的NavDestination页面的参数信息。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | index | number | 是 | NavDestination页面的位置索引。 | **返回值：** | 类型 | 说明 | | ------ | -------- | | unknown | 返回对应NavDestination页面的参数信息。 | | undefined | 传入index无效时返回undefined。 | ### getParamByName10+ getParamByName(name: string): Array 获取全部名为name的NavDestination页面的参数信息。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | name | string | 是 | NavDestination页面名称。 | **返回值：** | 类型 | 说明 | | ------ | -------- | | Array | 返回全部名为name的NavDestination页面的参数信息。 | ### getIndexByName10+ getIndexByName(name: string): Array 获取全部名为name的NavDestination页面的位置索引。 **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | name | string | 是 | NavDestination页面名称。 | **返回值：** | 类型 | 说明 | | ------ | -------- | | Array | 返回全部名为name的NavDestination页面的位置索引。 | ### size10+ size(): number 获取栈大小。 **返回值：** | 类型 | 说明 | | ------ | -------- | | number | 返回栈大小。 | ## NavPathInfo10+ 路由页面信息。 ### constructor constructor(name: string, param: unknown) **参数：** | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | name | string | 是 | NavDestination页面名称。 | | param | unknown | 否 | NavDestination页面详细参数。 | ## NavigationMenuItem类型说明 | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | value | string | 是 | 菜单栏单个选项的显示文本。 | | icon | string | 否 | 菜单栏单个选项的图标资源路径。 | | action | () => void | 否 | 当前选项被选中的事件回调。 | ## object类型说明 | 名称 | 类型 | 必填 | 描述 | | ------ | ----------------------- | ---- | --------------- | | value | string | 是 | 工具栏单个选项的显示文本。 | | icon | string | 否 | 工具栏单个选项的图标资源路径。 | | action | () => void | 否 | 当前选项被选中的事件回调。 | ## ToolbarItem10+类型说明 | 名称 | 类型 | 必填 | 描述 | | ---------- | ------------------------------------------------- | ---- | ----------------------------------------------------------- | | value | ResourceStr | 是 | 工具栏单个选项的显示文本。 | | icon | ResourceStr | 否 | 工具栏单个选项的图标资源路径。 | | action | () => void | 否 | 当前选项被选中的事件回调。 | | status | [ToolbarItemStatus](#toolbaritemstatus10枚举说明) | 否 | 工具栏单个选项的状态。
默认值：ToolbarItemStatus.NORMAL | | activeIcon | ResourceStr | 否 | 工具栏单个选项处于ACTIVE态时的图标资源路径。 | ## ToolbarItemStatus10+枚举说明 | 名称 | 描述 | | -------- | ------------------------------------------------------------ | | NORMAL | 设置工具栏单个选项为NORMAL态，该选项显示默认样式，可以触发Hover，Press，Focus事件并显示对应的多态样式。 | | DISABLED | 设置工具栏单个选项为DISABLED态， 该选项显示DISABLED态样式，并且不可交互。 | | ACTIVE | 设置工具栏单个选项为ACTIVE态， 该选项通过点击事件可以将icon图标更新为activeIcon对应的图片资源。 | ## NavigationTitleMode枚举说明 | 名称 | 描述 | | ---- | ------------------------------------------------------------ | | Free | 当内容为可滚动组件时，标题随着内容向上滚动而缩小（子标题的大小不变、淡出）。向下滚动内容到顶时则恢复原样。
**说明：**
标题随着内容滚动大小联动的动效在title设置为ResourceStr和NavigationCommonTitle时生效，设置成其余自定义节点类型时字体样式无法变化，下拉时只影响标题栏偏移。 | | Mini | 固定为小标题模式。 | | Full | 固定为大标题模式。 | ## NavigationCommonTitle类型说明 | 名称 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | ------ | | main | string | 是 | 设置主标题。 | | sub | string | 是 | 设置副标题。 | ## NavigationCustomTitle类型说明 | 名称 | 类型 | 必填 | 描述 | | ------- | ---------------------------------------- | ---- | -------- | | builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 设置标题栏内容。 | | height | [TitleHeight](#titleheight枚举说明) \| [Length](ts-types.md#length) | 是 | 设置标题栏高度。 | ## NavBarPosition枚举说明 | 名称 | 描述 | | ----- | ---------------- | | Start | 双栏显示时，主列在主轴方向首部。 | | End | 双栏显示时，主列在主轴方向尾部。 | ## NavigationMode枚举说明 | 名称 | 描述 | | ----- | ---------------------------------------- | | Stack | 导航栏与内容区独立显示，相当于两个页面。 | | Split | 导航栏与内容区分两栏显示。 | | Auto | 窗口宽度>=520vp时，采用Split模式显示；窗口宽度<520vp时，采用Stack模式显示。 | ## TitleHeight枚举说明 | 名称 | 描述 | | ----------- | -------------------------- | | MainOnly | 只有主标题时标题栏的推荐高度（56vp）。 | | MainWithSub | 同时有主标题和副标题时标题栏的推荐高度（82vp）。 | > **说明：** > 目前可滚动组件只支持List。 ## 事件 | 名称 | 功能描述 | | ---------------------------------------- | ---------------------------------------- | | onTitleModeChange(callback: (titleMode: NavigationTitleMode) => void) | 当titleMode为NavigationTitleMode.Free时，随着可滚动组件的滑动标题栏模式发生变化时触发此回调。 | | onNavBarStateChange(callback: (isVisible: boolean) => void) | 导航栏显示状态切换时触发该回调。返回值isVisible为true时表示显示，为false时表示隐藏。 | ## 示例 ```ts // xxx.ets @Entry @Component struct NavigationExample { private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] @State currentIndex: number = 0 @State Build: Array = [ { text: 'add', num: 0 }, { text: 'app', num: 1 }, { text: 'collect', num: 2 } ] @Builder NavigationTitle() { Column() { Text('Title') .fontColor('#182431') .fontSize(30) .lineHeight(41) .fontWeight(700) Text('subtitle') .fontColor('#182431') .fontSize(14) .lineHeight(19) .opacity(0.4) .margin({ top: 2, bottom: 20 }) }.alignItems(HorizontalAlign.Start) } @Builder NavigationMenus() { Row() { Image('common/navigation_icon1.svg') .width(24) .height(24) Image('common/navigation_icon1.svg') .width(24) .height(24) .margin({ left: 24 }) Image('common/navigation_icon2.svg') .width(24) .height(24) .margin({ left: 24 }) } } @Builder NavigationToolbar() { Row() { ForEach(this.Build, item => { Column() { Image(this.currentIndex == item.num ? 'common/public_icon_selected.svg' : 'common/public_icon.svg') .width(24) .height(24) Text(item.text) .fontColor(this.currentIndex == item.num ? '#007DFF' : '#182431') .fontSize(10) .lineHeight(14) .fontWeight(500) .margin({ top: 3 }) }.width(104).height(56) .onClick(() => { this.currentIndex = item.num }) }) }.margin({ left: 24 }) } build() { Column() { Navigation() { TextInput({ placeholder: 'search...' }) .width('90%') .height(40) .backgroundColor('#FFFFFF') .margin({ top: 8 }) List({ space: 12, initialIndex: 0 }) { ForEach(this.arr, (item) => { ListItem() { Text('' + item) .width('90%') .height(72) .backgroundColor('#FFFFFF') .borderRadius(24) .fontSize(16) .fontWeight(500) .textAlign(TextAlign.Center) }.editable(true) }, item => item) } .height(324) .width('100%') .margin({ top: 12, left: '10%' }) } .title(this.NavigationTitle) .menus(this.NavigationMenus) .titleMode(NavigationTitleMode.Full) .toolBar(this.NavigationToolbar) .hideTitleBar(false) .hideToolBar(false) .onTitleModeChange((titleModel: NavigationTitleMode) => { console.info('titleMode' + titleModel) }) }.width('100%').height('100%').backgroundColor('#F1F3F5') } } ``` ![zh-cn_image_0000001192655288](figures/zh-cn_image_0000001192655288.gif)