1# Navigation 2 3The **\<Navigation>** component typically functions as the root container of a page and displays the title bar, toolbar, and navigation bar based on the attribute settings. 4 5> **NOTE** 6> 7> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12Supported 13 14Since API version 9, it is recommended that this component be used together with the **[\<NavRouter>](ts-basic-components-navrouter.md)** component. 15 16 17## APIs 18 19Navigation() 20 21 22## Attributes 23 24In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 25 26| Name | Type | Description | 27| -------------- | ---------------------------------------- | ---------------------------------------- | 28| title | string \| [CustomBuilder](ts-types.md#custombuilder8)<sup>8+</sup> \| [NavigationCommonTitle](#navigationcommontitle)<sup>9+</sup> \| [NavigationCustomTitle](#navigationcustomtitle)<sup>9+</sup> | Page title. | 29| subTitle<sup>deprecated</sup> | string | Subtitle of the page. This attribute is deprecated since API version 9. You are advised to use **title** instead. | 30| menus | Array<[NavigationMenuItem](#navigationmenuitem)> \| [CustomBuilder](ts-types.md#custombuilder8)<sup>8+</sup> | Menu items in the upper right corner of the page. When the value type is Array\<[NavigationMenuItem](#navigationmenuitem)>, the menu shows a maximum of three icons in portrait mode and a maximum of five icons in landscape mode, plus excess icons (if any) under the automatically generated **More** icon. | 31| titleMode | [NavigationTitleMode](#navigationtitlemode) | Display mode of the page title bar.<br>Default value: **NavigationTitleMode.Free**| 32| toolBar | [object](#object) \| [CustomBuilder](ts-types.md#custombuilder8)<sup>8+</sup> | Content of the toolbar.<br>**items**: items on the toolbar. | 33| hideToolBar | boolean | Whether to hide the toolbar.<br>Default value: **false**<br>**true**: Hide the toolbar.<br>**false**: Display the toolbar.| 34| hideTitleBar | boolean | Whether to hide the title bar.<br>Default value: **false**<br>**true**: Hide the title bar.<br>**false**: Display the title bar.| 35| hideBackButton | boolean | Whether to hide the Back button.<br>Default value: **false**<br>**true**: Hide the Back button.<br>**false**: Display the Back button.<br>The Back button in the title bar of the **\<NavDestination>** component cannot be hidden.| 36| navBarWidth<sup>9+</sup> | [Length](ts-types.md#length) | Width of the navigation bar.<br>Default value: **200vp**| 37| navBarPosition<sup>9+</sup> | [NavBarPosition](#navbarposition) | Position of the navigation bar.<br>Default value: **NavBarPosition.Start**| 38| mode<sup>9+</sup> | [NavigationMode](#navigationmode) | Display mode of the navigation bar.<br>Default value: **NavigationMode.Auto**| 39| backButtonIcon<sup>9+</sup> | string \| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | Back button icon on the navigation bar. The Back button in the title bar of the **\<NavDestination>** component cannot be hidden.| 40| hideNavBar<sup>9+</sup> | boolean | Whether to hide the navigation bar. This attribute is valid only when **mode** is set to **NavigationMode.Split**.| 41 42 43## NavigationMenuItem 44 45| Name | Type | Mandatory| Description | 46| ------ | ----------------------- | ---- | ------------------------------ | 47| value | string | Yes | Text of a menu item. | 48| icon | string | No | Icon path of a menu item.| 49| action | () => void | No | Callback invoked when a menu item is selected. | 50 51## object 52 53| Name | Type | Mandatory| Description | 54| ------ | ----------------------- | ---- | ------------------------------ | 55| value | string | Yes | Text of an option on the toolbar. | 56| icon | string | No | Icon path of an option on the toolbar.| 57| action | () => void | No | Callback invoked when an option is selected. | 58 59## NavigationTitleMode 60 61| Name | Description | 62| ---- | ---------------------------------------- | 63| Free | When the content is a scrollable component, the main title shrinks as the content scrolls down (the subtitle fades out with its size remaining unchanged) and restores when the content scrolls up to the top.| 64| Mini | The title is fixed at mini mode. | 65| Full | The title is fixed at full mode. | 66 67## NavigationCommonTitle 68 69| Name | Type | Mandatory| Description | 70| ------ | --------- | ---- | -------- | 71| main | string | Yes| Main title.| 72| sub | string | Yes| Subtitle.| 73 74## NavigationCustomTitle 75 76| Name | Type | Mandatory| Description | 77| ------ | ----------------------- | ---- | ------------------------------ | 78| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes| Content of the title bar.| 79| height | [TitleHeight](#titleheight) \| [Length](ts-types.md#length) | Yes| Height of the title bar.| 80 81## NavBarPosition 82 83| Name| Description | 84| ---- | ---------------------------------------- | 85| Start | When two columns are displayed, the main column is at the start of the main axis.| 86| End | When two columns are displayed, the main column is at the end of the main axis. | 87 88## NavigationMode 89 90| Name| Description | 91| ---- | ---------------------------------------- | 92| Stack | The navigation bar and content area are displayed independently of each other, which are equivalent to two pages.| 93| Split | The navigation bar and content area are displayed in different columns.| 94| Auto | When the window width is greater than or equal to 520 vp, Split mode is used. Otherwise, the Stack mode is used.| 95 96## TitleHeight 97 98| Name| Description | 99| ---- | ---------------------------------------- | 100| MainOnly | Recommended height (56 vp) of the title bar when only the main title is available.| 101| MainWithSub | Recommended height (82 vp) of the title bar when both the main title and subtitle exist.| 102 103 104> **NOTE** 105> 106> Among the scrollable components, only **\<List>** is supported. 107 108 109## Events 110 111| Name | Description | 112| ---------------------------------------- | ---------------------------------------- | 113| onTitleModeChange(callback: (titleMode: NavigationTitleMode) => void) | Triggered when **titleMode** is set to **NavigationTitleMode.Free** and the title bar mode changes as content scrolls.| 114| onNavBarStateChange(callback: (isVisible: boolean) => void) | Triggered when the navigation bar visibility status changes. The value **true** means that the navigation bar is displayed, and **false** means the opposite.| 115 116 117## Example 118 119```ts 120// xxx.ets 121@Entry 122@Component 123struct NavigationExample { 124 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 125 @State currentIndex: number = 0 126 @State Build: Array<Object> = [ 127 { 128 text: 'add', 129 num: 0 130 }, 131 { 132 text: 'app', 133 num: 1 134 }, 135 { 136 text: 'collect', 137 num: 2 138 } 139 ] 140 141 @Builder NavigationTitle() { 142 Column() { 143 Text('Title') 144 .fontColor('#182431') 145 .fontSize(30) 146 .lineHeight(41) 147 .fontWeight(700) 148 Text('subtitle') 149 .fontColor('#182431') 150 .fontSize(14) 151 .lineHeight(19) 152 .opacity(0.4) 153 .margin({ top: 2, bottom: 20 }) 154 }.alignItems(HorizontalAlign.Start) 155 } 156 157 @Builder NavigationMenus() { 158 Row() { 159 Image('common/navigation_icon1.svg') 160 .width(24) 161 .height(24) 162 Image('common/navigation_icon1.svg') 163 .width(24) 164 .height(24) 165 .margin({ left: 24 }) 166 Image('common/navigation_icon2.svg') 167 .width(24) 168 .height(24) 169 .margin({ left: 24 }) 170 } 171 } 172 173 @Builder NavigationToolbar() { 174 Row() { 175 ForEach(this.Build, item => { 176 Column() { 177 Image(this.currentIndex == item.num ? 'common/public_icon_selected.svg' : 'common/public_icon.svg') 178 .width(24) 179 .height(24) 180 Text(item.text) 181 .fontColor(this.currentIndex == item.num ? '#007DFF' : '#182431') 182 .fontSize(10) 183 .lineHeight(14) 184 .fontWeight(500) 185 .margin({ top: 3 }) 186 }.width(104).height(56) 187 .onClick(() => { 188 this.currentIndex = item.num 189 }) 190 }) 191 }.margin({ left: 24 }) 192 } 193 194 build() { 195 Column() { 196 Navigation() { 197 TextInput({ placeholder: 'search...' }) 198 .width('90%') 199 .height(40) 200 .backgroundColor('#FFFFFF') 201 .margin({ top: 8 }) 202 203 List({ space: 12, initialIndex: 0 }) { 204 ForEach(this.arr, (item) => { 205 ListItem() { 206 Text('' + item) 207 .width('90%') 208 .height(72) 209 .backgroundColor('#FFFFFF') 210 .borderRadius(24) 211 .fontSize(16) 212 .fontWeight(500) 213 .textAlign(TextAlign.Center) 214 }.editable(true) 215 }, item => item) 216 } 217 .height(324) 218 .width('100%') 219 .margin({ top: 12, left: '10%' }) 220 } 221 .title(this.NavigationTitle) 222 .menus(this.NavigationMenus) 223 .titleMode(NavigationTitleMode.Full) 224 .toolBar(this.NavigationToolbar) 225 .hideTitleBar(false) 226 .hideToolBar(false) 227 .onTitleModeChange((titleModel: NavigationTitleMode) => { 228 console.info('titleMode' + titleModel) 229 }) 230 }.width('100%').height('100%').backgroundColor('#F1F3F5') 231 } 232} 233``` 234 235 236
