1# Navigation 2 3The **Navigation** component is the root view container for navigation. It typically functions as the root container of a page and includes a title bar, content area, and toolbar. The content area switches between the home page content (child components of **Navigation**) and non-home page content (child components of [NavDestination](ts-basic-components-navdestination.md)) through routing. 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> - Since API version 11, this component supports the safe area attribute by default, with the default attribute value being **expandSafeArea([SafeAreaType.SYSTEM, SafeAreaType.KEYBOARD, SafeAreaType.CUTOUT], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])**. You can override this attribute to change the default behavior. In earlier versions, you need to use the [expandSafeArea](ts-universal-attributes-expand-safe-area.md) attribute to implement the safe area feature. 10> 11> - When [NavBar](#navbar12) is nested within a **Navigation** component, the lifecycle of the inner **Navigation** component does not synchronize with the outer **Navigation** component or the lifecycle of a [modal](ts-universal-attributes-modal-transition.md). 12> 13> - If no main title or subtitle is set for **Navigation** and there is no back button, the title bar is not displayed. 14 15 16## Child Components 17 18Supported 19 20Since API version 9, it is recommended that this component be used together with the [NavRouter](ts-basic-components-navrouter.md) component. 21 22Since API version 10, it is recommended that this component be used together with the [NavPathStack](#navpathstack10) component and **navDestination** attribute for page routing. 23 24## APIs 25 26### Navigation 27 28Navigation() 29 30**Atomic service API**: This API can be used in atomic services since API version 11. 31 32**System capability**: SystemCapability.ArkUI.ArkUI.Full 33 34### Navigation<sup>10+</sup> 35 36Navigation(pathInfos: NavPathStack) 37 38Binds a navigation stack to the **Navigation** component. 39 40**Atomic service API**: This API can be used in atomic services since API version 11. 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44**Parameters** 45 46| Name | Type | Mandatory | Description | 47| --------- | ------------------------------- | ---- | ------ | 48| pathInfos | [NavPathStack](#navpathstack10) | Yes | Information about the navigation stack.| 49 50## Attributes 51 52In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 53 54### title 55 56title(value: ResourceStr | CustomBuilder | NavigationCommonTitle | NavigationCustomTitle, options?: NavigationTitleOptions) 57 58Sets the page title. 59 60**Atomic service API**: This API can be used in atomic services since API version 11. 61 62**System capability**: SystemCapability.ArkUI.ArkUI.Full 63 64**Parameters** 65 66| Name | Type | Mandatory| Description | 67| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 68| value | [ResourceStr](ts-types.md#resourcestr)<sup>10+</sup> \| [CustomBuilder](ts-types.md#custombuilder8) \| [NavigationCommonTitle](#navigationcommontitle9)<sup>9+</sup> \| [NavigationCustomTitle](#navigationcustomtitle9)<sup>9+</sup> | Yes | Page title. When the NavigationCustomTitle type is used to set the height, [titleMode](#titlemode) does not take effect. When the title string is too long: (1) If no subtitle is set, the string is scaled down, wrapped in two lines, and then clipped. (2) If a subtitle is set, the subtitle is scaled down and then clipped.| 69| options | [NavigationTitleOptions](#navigationtitleoptions11)<sup>11+</sup> | No | Title bar options. | 70 71### subTitle<sup>(deprecated)</sup> 72 73subTitle(value: string) 74 75Sets the page subtitle. 76 77This API is deprecated since API version 9. You are advised to use [title](#title) instead. 78 79**System capability**: SystemCapability.ArkUI.ArkUI.Full 80 81**Parameters** 82 83| Name| Type | Mandatory| Description | 84| ------ | ------ | ---- | ------------ | 85| value | string | Yes | Page subtitle.| 86 87### menus 88 89menus(value: Array<NavigationMenuItem> | CustomBuilder) 90 91> **NOTE** 92> 93> The following are not allowed: modify the icon size through the **fontSize** attribute of the **SymbolGlyphModifier** object, change the animation effects through the **effectStrategy** attribute, or change the type of animation effects through the **symbolEffect** attribute. 94 95 96Sets the menu items in the upper right corner of the page. If this attribute is not set, no menu item is displayed. 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, with excess icons (if any) placed under the automatically generated **More** icon. 97 98**Atomic service API**: This API can be used in atomic services since API version 11. 99 100**System capability**: SystemCapability.ArkUI.ArkUI.Full 101 102**Parameters** 103 104| Name| Type | Mandatory| Description | 105| ------ | ------------------------------------------------------------ | ---- | ---------------- | 106| value | Array<[NavigationMenuItem](#navigationmenuitem)> \| [CustomBuilder](ts-types.md#custombuilder8) | Yes | Menu items in the upper right corner of the page.| 107 108### titleMode 109 110titleMode(value: NavigationTitleMode) 111 112Sets the display mode of the page title bar. 113 114**Atomic service API**: This API can be used in atomic services since API version 11. 115 116**System capability**: SystemCapability.ArkUI.ArkUI.Full 117 118**Parameters** 119 120| Name| Type | Mandatory| Description | 121| ------ | --------------------------------------------------- | ---- | --------------------------------------------------------- | 122| value | [NavigationTitleMode](#navigationtitlemode) | Yes | Display mode of the page title bar.<br>Default value: **NavigationTitleMode.Free**| 123 124### toolBar<sup>(deprecated)</sup> 125 126toolBar(value: object | CustomBuilder) 127 128Sets the content of the toolbar. If this attribute is not set, no toolbar is displayed. Toolbar items are evenly distributed on the bottom toolbar, with text and icons evenly spaced in each content area. If any item contains overlong text and there are fewer than five items, the toolbar will reduce the text size progressively, wrap the text over two lines if necessary, and then clip the text to fit. 129 130This API is deprecated since API version 10. You are advised to use [toolbarConfiguration](#toolbarconfiguration10) instead. 131 132**System capability**: SystemCapability.ArkUI.ArkUI.Full 133 134**Parameters** 135 136| Name| Type | Mandatory| Description | 137| ------ | ------------------------------------------------------------ | ---- | ------------ | 138| value | object \| [CustomBuilder](ts-types.md#custombuilder8) | Yes | Content of the toolbar.| 139 140**object** 141 142| Name | Type | Mandatory | Description | 143| ------ | ------------- | ---- | --------------- | 144| value | string | Yes | Text of the toolbar item. | 145| icon | string | No | Icon path of the toolbar item.| 146| action | () => void | No | Callback invoked when the menu item is selected. | 147 148### toolbarConfiguration<sup>10+</sup> 149 150toolbarConfiguration(value: Array<ToolbarItem> | CustomBuilder, options?: NavigationToolbarOptions) 151 152> **NOTE** 153> 154> The following are not allowed: modify the icon size through the **fontSize** attribute of the **SymbolGlyphModifier** object, change the animation effects through the **effectStrategy** attribute, or change the type of animation effects through the **symbolEffect** attribute. 155 156 157Sets the content of the toolbar. If this attribute is not set, no toolbar is displayed. 158 159**Atomic service API**: This API can be used in atomic services since API version 11. 160 161**System capability**: SystemCapability.ArkUI.ArkUI.Full 162 163**Parameters** 164 165| Name | Type | Mandatory| Description | 166| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 167| value | Array<[ToolbarItem](#toolbaritem10)> \| [CustomBuilder](ts-types.md#custombuilder8) | Yes | Content of the toolbar. When configured with Array<[ToolbarItem](#toolbaritem10)>, the toolbar follows the rules below:<br>Toolbar items are evenly distributed on the bottom toolbar, with text and icons evenly spaced in each content area.<br>- If any item contains overlong text and there are fewer than five items, the toolbar will: 1. Increase the item width to accommodate the text until the toolbar spans the screen width; 2. Reduce the text size progressively; 3. Wrap the text over two lines; 4. Clip the text.<br>In portrait mode, the toolbar shows a maximum of five icons, with any additional icons placed under an automatically generated **More** icon. In landscape mode, the behavior of the toolbar is determined by the display mode: (1) If the display mode is [Split](#navigationmode9), the toolbar follows the same rules as in portrait mode. (2) If the display mode is [Stack](#navigationmode9), the toolbar must be used together with Array<[NavigationMenuItem](#navigationmenuitem)> of the **menus** attribute; in this configuration, the bottom toolbar is automatically hidden, and all items on the toolbar are relocated to the menu in the upper right corner of the screen.<br>When configured with [CustomBuilder](ts-types.md#custombuilder8), the toolbar does not follow the above rules, except for evenly distributing items at the bottom of the toolbar.| 168| options | [NavigationToolbarOptions](#navigationtoolbaroptions11)<sup>11+</sup> | No | Toolbar options. | 169 170### hideToolBar 171 172hideToolBar(value: boolean) 173 174Specifies whether to hide the toolbar. 175 176**Atomic service API**: This API can be used in atomic services since API version 11. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Parameters** 181 182| Name| Type | Mandatory| Description | 183| ------ | ------- | ---- | ------------------------------------------------------------ | 184| value | boolean | Yes | Whether to hide the toolbar.<br>Default value: **false**<br>**true**: Hide the toolbar.<br>**false**: Show the toolbar.| 185 186### hideToolBar<sup>13+</sup> 187 188hideToolBar(hide: boolean, animated: boolean) 189 190Sets whether to hide the toolbar and whether to animate the visibility change. 191 192**Atomic service API**: This API can be used in atomic services since API version 13. 193 194**System capability**: SystemCapability.ArkUI.ArkUI.Full 195 196**Parameters** 197 198| Name| Type | Mandatory| Description | 199| ------ | ------- | ---- | ------------------------------------------------------------ | 200| hide | boolean | Yes | Whether to hide the toolbar.<br>Default value: **false**<br>**true**: Hide the toolbar.<br>**false**: Show the toolbar.| 201| animated | boolean | Yes | Whether to animate the visibility change.<br>Default value: **false**<br>**true**: Animate the visibility change.<br>**false**: Do not animate the visibility change.| 202 203### hideTitleBar 204 205hideTitleBar(value: boolean) 206 207Specifies whether to hide the title bar. 208 209**Atomic service API**: This API can be used in atomic services since API version 11. 210 211**System capability**: SystemCapability.ArkUI.ArkUI.Full 212 213**Parameters** 214 215| Name| Type | Mandatory| Description | 216| ------ | ------- | ---- | ------------------------------------------------------------ | 217| value | boolean | Yes | Whether to hide the title bar.<br>Default value: **false**<br>**true**: Hide the title bar.<br>**false**: Show the title bar.| 218 219### hideTitleBar<sup>13+</sup> 220 221hideTitleBar(hide: boolean, animated: boolean) 222 223Sets whether to hide the title bar and whether to animate the visibility change. 224 225**Atomic service API**: This API can be used in atomic services since API version 13. 226 227**System capability**: SystemCapability.ArkUI.ArkUI.Full 228 229**Parameters** 230 231| Name| Type | Mandatory| Description | 232| ------ | ------- | ---- | ------------------------------------------------------------ | 233| hide | boolean | Yes | Whether to hide the title bar.<br>Default value: **false**<br>**true**: Hide the title bar.<br>**false**: Show the title bar.| 234| animated | boolean | Yes | Whether to animate the visibility change.<br>Default value: **false**<br>**true**: Animate the visibility change.<br>**false**: Do not animate the visibility change.| 235 236### hideBackButton 237 238hideBackButton(value: boolean) 239 240Sets whether to hide the back button in the title bar. The back button is available only when [titleMode](#titlemode) is set to **NavigationTitleMode.Mini**. 241 242**Atomic service API**: This API can be used in atomic services since API version 11. 243 244**System capability**: SystemCapability.ArkUI.ArkUI.Full 245 246**Parameters** 247 248| Name| Type | Mandatory| Description | 249| ------ | ------- | ---- | ------------------------------------------------------------ | 250| value | boolean | Yes | Whether to hide the back button in the title bar.<br>Default value: **false**<br>**true**: Hide the back button.<br>**false**: Show the back button.| 251 252### navBarWidth<sup>9+</sup> 253 254navBarWidth(value: Length) 255 256Sets the width of the navigation bar. This attribute takes effect only when the **Navigation** component is split. 257 258**Atomic service API**: This API can be used in atomic services since API version 11. 259 260**System capability**: SystemCapability.ArkUI.ArkUI.Full 261 262**Parameters** 263 264| Name| Type | Mandatory| Description | 265| ------ | ---------------------------- | ---- | ----------------------------------------- | 266| value | [Length](ts-types.md#length) | Yes | Width of the navigation bar.<br>Default value: **240**<br>Unit: vp<br>**undefined**: No action is taken, and the navigation bar width remains consistent with the default value.| 267 268### navBarPosition<sup>9+</sup> 269 270navBarPosition(value: NavBarPosition) 271 272Sets the position of the navigation bar. This attribute takes effect only when the **Navigation** component is split. 273 274**Atomic service API**: This API can be used in atomic services since API version 11. 275 276**System capability**: SystemCapability.ArkUI.ArkUI.Full 277 278**Parameters** 279 280| Name| Type | Mandatory| Description | 281| ------ | ------------------------------------------ | ---- | --------------------------------------------- | 282| value | [NavBarPosition](#navbarposition9) | Yes | Position of the navigation bar.<br>Default value: **NavBarPosition.Start**| 283 284### mode<sup>9+</sup> 285 286mode(value: NavigationMode) 287 288Sets the display mode of the page title bar. 289 290**Atomic service API**: This API can be used in atomic services since API version 11. 291 292**System capability**: SystemCapability.ArkUI.ArkUI.Full 293 294**Parameters** 295 296| Name| Type | Mandatory| Description | 297| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 298| value | [NavigationMode](#navigationmode9) | Yes | Display mode of the navigation bar.<br>Default value: **NavigationMode.Auto**<br>At the default settings, the component adapts to a single column or two columns based on the component width.| 299 300### backButtonIcon<sup>9+</sup> 301 302backButtonIcon(value: string | PixelMap | Resource | SymbolGlyphModifier) 303 304> **NOTE** 305> 306> The following are not allowed: modify the icon size through the **fontSize** attribute of the **SymbolGlyphModifier** object, change the animation effects through the **effectStrategy** attribute, or change the type of animation effects through the **symbolEffect** attribute. 307 308 309Sets the icon of the back button in the title bar. 310 311**Atomic service API**: This API can be used in atomic services since API version 11. 312 313**System capability**: SystemCapability.ArkUI.ArkUI.Full 314 315**Parameters** 316 317| Name| Type | Mandatory| Description | 318| ------ | ------------------------------------------------------------ | ---- | -------------------- | 319| value | string \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) \| [SymbolGlyphModifier<sup>12+</sup>](ts-universal-attributes-attribute-modifier.md) | Yes | Icon of the back button in the title bar.| 320 321### hideNavBar<sup>9+</sup> 322 323hideNavBar(value: boolean) 324 325Specifies whether to hide the navigation bar. If this parameter is set to **true**, the navigation bar, including the title bar, content area, and toolbar, is hidden. In this case, if the navigation destination page is in the navigation stack, it is moved to the top of the stack and displayed. Otherwise, a blank page is displayed. 326 327From API version 9 to API version 10, this attribute takes effect only in dual-column mode. Since API version 11, this attribute takes effect in single-column, dual-column, and auto modes. 328 329**Atomic service API**: This API can be used in atomic services since API version 11. 330 331**System capability**: SystemCapability.ArkUI.ArkUI.Full 332 333**Parameters** 334 335| Name| Type | Mandatory| Description | 336| ------ | ------- | ---- | ---------------------------------- | 337| value | boolean | Yes | Whether to hide the navigation bar.<br>Default value: **false**<br>**true**: Hide the navigation bar.<br>**false**: Show the navigation bar.| 338 339### navDestination<sup>10+</sup> 340 341navDestination(builder: (name: string, param: unknown) => void) 342 343Builder for a **NavDestination** component. The **builder** function is used, with the **name** and **param** parameters passed in. The **builder** can have only one root node. In the builder, a layer of custom components can be included outside the **NavDestination** component. However, no attributes or events can be set for the custom components. Otherwise, only blank components are displayed. 344 345**Atomic service API**: This API can be used in atomic services since API version 11. 346 347**System capability**: SystemCapability.ArkUI.ArkUI.Full 348 349**Parameters** 350 351| Name | Type | Mandatory| Description | 352| ------- | -------------------------------------- | ---- | ------------------------ | 353| builder | (name: string, param: unknown) => void | Yes | Builder for a **NavDestination** component. **name**: name of the navigation destination page. **param**: detailed parameters of the navigation destination page.| 354 355### navBarWidthRange<sup>10+</sup> 356 357navBarWidthRange(value: [Dimension, Dimension]) 358 359Sets the minimum and maximum widths of the navigation bar (effective in dual-column mode). 360 361For details about the priority rules, see **NOTE** below. 362 363**Atomic service API**: This API can be used in atomic services since API version 11. 364 365**System capability**: SystemCapability.ArkUI.ArkUI.Full 366 367**Parameters** 368 369| Name | Type | Mandatory| Description | 370| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 371| value | [[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)] | Yes | Minimum and maximum widths of the navigation bar.<br>Default value: 240 for the minimum value; 40% of the component width (not greater than 432) for the maximum value; if either of the widths is not set, the default value is used for that width.<br>Unit: vp| 372 373### minContentWidth<sup>10+</sup> 374 375minContentWidth(value: Dimension) 376 377Sets the minimum width of the navigation bar content area (effective in dual-column mode). 378 379For details about the priority rules, see **NOTE** below. 380 381**Atomic service API**: This API can be used in atomic services since API version 11. 382 383**System capability**: SystemCapability.ArkUI.ArkUI.Full 384 385**Parameters** 386 387| Name | Type | Mandatory| Description | 388| ------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 389| value | [Dimension](ts-types.md#dimension10) | Yes | Minimum width of the navigation bar content area.<br>Default value: **360**<br>Unit: vp<br>**undefined**: No action is taken, and the minimum width of the navigation bar remains consistent with the default value.<br>Breakpoint calculation in Auto mode: default 600 vp = minNavBarWidth (240 vp) + minContentWidth (360 vp)| 390 391> **NOTE** 392> 393> 1. If only **navBarWidth** is set, no divider in the **Navigation** component can be dragged. 394> 395> 2. **navBarWidthRange** specifies the range within which the divider can be dragged. If it is not set, the default value is used. The dragging of the divider is subject to both **navBarWidthRange** and **minContentWidth**. 396> 397> 3. If the size of the **Navigation** component decreases, it carries out the following steps in sequence:<br>a. Scale down the content area. If **minContentWidth** is not set, the content area can be scaled down to 0. Otherwise, the content area can be scaled down to as small as the value specified by **minContentWidth**.b. Scale down the navigation bar until its width reaches the value defined by **navBarRange**.c. Clip the displayed content. 398 399### ignoreLayoutSafeArea<sup>12+</sup> 400 401ignoreLayoutSafeArea(types?: Array<LayoutSafeAreaType>, edges?: Array<LayoutSafeAreaEdge>) 402 403Ignores the layout safe area by allowing the component to extend into the non-safe areas of the screen. 404 405**Atomic service API**: This API can be used in atomic services since API version 12. 406 407**System capability**: SystemCapability.ArkUI.ArkUI.Full 408 409**Parameters** 410 411| Name| Type | Mandatory| Description | 412| ------ | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 413| types | Array <[LayoutSafeAreaType](ts-types.md#layoutsafeareatype12)> | No | Types of non-safe areas to extend into.<br>Default value:<br>[LayoutSafeAreaType.SYSTEM] | 414| edges | Array <[LayoutSafeAreaEdge](ts-types.md#layoutsafeareaedge12)> | No | Edges for expanding the safe area.<br> Default value:<br>[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]| 415 416> **NOTE** 417> 418> After **LayoutSafeArea** is set: 419> When **LayoutSafeAreaType.SYSTEM** is set, the component can extend into the non-safe area if its boundaries overlap with it. For example, if the device's status bar is 100 high, the component can extend into the non-safe area only when there is an absolute vertical offset between 0 and 100. 420> 421> If the component extends into the non-safe area, events triggered within that area (such as click events) might be intercepted by the system. This allows the system to prioritize responses to system components such as the status bar. 422 423### systemBarStyle<sup>12+</sup> 424 425systemBarStyle(style: Optional<SystemBarStyle>) 426 427Sets the style of the system status bar when the home page of the **Navigation** component is displayed. 428 429**Atomic service API**: This API can be used in atomic services since API version 12. 430 431**System capability**: SystemCapability.ArkUI.ArkUI.Full 432 433**Parameters** 434 435| Name| Type | Mandatory| Description | 436| ------ | -------------- | ---- | ------------------ | 437| style | [Optional](ts-universal-attributes-custom-property.md#optional12)<[SystemBarStyle](#systembarstyle12)> | Yes | Style of the system status bar.| 438 439> **Instructions** 440> 441> 1. Avoid using the **systemBarStyle** attribute in conjunction with the status bar style APIs in the **Window** module, such as [setWindowSystemBarProperties](../js-apis-window.md#setwindowsystembarproperties9). 442> 2. When you first set the **systemBarStyle** attribute for a **Navigation** or **NavDestination** component, the current status bar style is saved for potential future restoration. 443> 3. The status bar style is determined by the home page of the **Navigation** component (if there are no **NavDestination** pages on the navigation stack) or the top **NavDestination** page on the navigation stack. 444> 4. If the home page or any top **NavDestination** page has a valid **systemBarStyle** set, that style will be used. If no style is set, and there is a previously saved style available, the saved style will be used. If no style has been set or saved, no changes will be made. 445> 5. In [Split](#navigationmode9) mode, if there is no **NavDestination** in the content area, the settings of the **Navigation** home page will apply. Otherwise, the settings of the top **NavDestination** page on the navigation stack will apply. 446> 6. The **systemBarStyle** attribute is effective only for the main page of the main window. 447> 7. The set style will only take effect if the **Navigation** component spans the entire page. If it does not, and there is a previously saved style available, the saved style will be used instead. 448> 8. When different styles are set for pages, the new style takes effect at the start of the page transition. 449> 9. The status bar style set by **Navigation** or **NavDestination** does not apply in non-fullscreen windows. 450 451### recoverable<sup>14+</sup> 452 453recoverable(recoverable: Optional<boolean>) 454 455Sets whether the **Navigation** component is recoverable. If set to recoverable, when the application process exits unexpectedly and restarts, the **Navigation** component will be automatically recreated, and the navigation stack will be restored to the state at the time of the unexpected exit. 456 457**System capability**: SystemCapability.ArkUI.ArkUI.Full 458 459**Parameters** 460 461| Name| Type | Mandatory| Description | 462| ------ | -------------- | ---- | ------------------ | 463| recoverable | [Optional](ts-universal-attributes-custom-property.md#optional12)<boolean> | Yes | Whether the **Navigation** component is recoverable. By default, it is not recoverable.<br>Default value: **false**<br>**true**: The **Navigation** component is recoverable.<br>**false**: The **Navigation** component is not recoverable.| 464 465> **Instructions** 466> 467> 1. For this API to work properly, you must first set the [id](ts-universal-attributes-component-id.md#id) attribute of the **Navigation** component. 468> 2. This API must be used together with the [recoverable](./ts-basic-components-navdestination.md#recoverable14) API of **NavDestination**. 469> 3. Non-serializable information, such as non-serializable parameters and custom **onPop**, is discarded and cannot be restored during the recovery process. 470 471### enableDragBar<sup>14+</sup> 472 473enableDragBar(isEnabled: Optional<boolean>) 474 475Sets whether to display a drag bar in split-column scenarios. 476 477**Atomic service API**: This API can be used in atomic services since API version 14. 478 479**System capability**: SystemCapability.ArkUI.ArkUI.Full 480 481**Parameters** 482 483| Name| Type | Mandatory| Description | 484| ------ | -------------- | ---- | ------------------ | 485| isEnabled | [Optional](ts-universal-attributes-custom-property.md#optional12)<boolean> | Yes | Whether to enable the drag bar. By default, there is no drag bar.<br>Default value: **false**<br>**true**: Enable the drag bar.<br>**false**: Disable the drag bar.| 486 487### enableModeChangeAnimation<sup>15+</sup> 488 489enableModeChangeAnimation(isEnabled: Optional<boolean>) 490 491Sets whether to enable the animation for switching between single and double column modes. 492 493**Atomic service API**: This API can be used in atomic services since API version 15. 494 495**System capability**: SystemCapability.ArkUI.ArkUI.Full 496 497**Parameters** 498 499| Name| Type | Mandatory| Description | 500| ------ | -------------- | ---- | ------------------ | 501| isEnabled | [Optional](ts-universal-attributes-custom-property.md#optional12)<boolean> | Yes | Whether to enable the animation for switching between single and double column modes.<br>Default value: **true**<br>**true**: Enable the animation for switching between single and double column modes.<br>**false**: Disable the animation for switching between single and double column modes.| 502 503## Events 504 505### onTitleModeChange 506 507onTitleModeChange(callback: (titleMode: NavigationTitleMode) => void) 508 509Triggered when [titleMode](#titlemode) is set to **NavigationTitleMode.Free** and the title bar mode changes as content scrolls. 510 511**Atomic service API**: This API can be used in atomic services since API version 11. 512 513**System capability**: SystemCapability.ArkUI.ArkUI.Full 514 515**Parameters** 516 517| Name | Type | Mandatory| Description | 518| --------- | --------------------------------------------------- | ---- | ---------- | 519| titleMode | [NavigationTitleMode](#navigationtitlemode) | Yes | Title mode.| 520 521### onNavBarStateChange<sup>9+</sup> 522 523onNavBarStateChange(callback: (isVisible: boolean) => void) 524 525Triggered when the navigation bar visibility status changes. 526 527**Atomic service API**: This API can be used in atomic services since API version 11. 528 529**System capability**: SystemCapability.ArkUI.ArkUI.Full 530 531**Parameters** 532 533| Name | Type | Mandatory| Description | 534| --------- | ------- | ---- | ---------------------------------------------- | 535| isVisible | boolean | Yes | Whether the navigation bar is visible. The value **true** means that the navigation bar is visible, and **false** means the opposite.| 536 537### onNavigationModeChange<sup>11+</sup> 538 539onNavigationModeChange(callback: (mode: NavigationMode) => void) 540 541Triggered when the **Navigation** component is displayed for the first time or its display mode switches between single-column and dual-column. 542 543**Atomic service API**: This API can be used in atomic services since API version 11. 544 545**System capability**: SystemCapability.ArkUI.ArkUI.Full 546 547**Parameters** 548 549| Name | Type | Mandatory| Description | 550| --------- | ------- | ---- | ---------------------------------------------- | 551| mode | [NavigationMode](#navigationmode9) | Yes | **NavigationMode.Split**: The component is displayed in two columns.<br>**NavigationMode.Stack**: The component is displayed in a single column.| 552 553### customNavContentTransition<sup>11+</sup> 554 555customNavContentTransition(delegate:(from: NavContentInfo, to: NavContentInfo, operation: NavigationOperation) => NavigationAnimatedTransition | undefined) 556 557Callback of the custom transition animation. 558 559**Atomic service API**: This API can be used in atomic services since API version 12. 560 561**System capability**: SystemCapability.ArkUI.ArkUI.Full 562 563**Parameters** 564 565| Name | Type | Mandatory| Description | 566| --------- | ----------------------------------------------------- | ---- | ----------------------- | 567| from | [NavContentInfo](#navcontentinfo11) | Yes | Destination page to exit.| 568| to | [NavContentInfo](#navcontentinfo11) | Yes | Destination page to enter.| 569| operation | [NavigationOperation](#navigationoperation11) | Yes | Transition type. | 570 571**Return value** 572 573| Type | Description | 574| ------------------------------------------------------------ | ------------------------------------------------------------ | 575| [NavigationAnimatedTransition](#navigationanimatedtransition11) \| undefined | Custom transition animation agreement.<br>**undefined**: The default transition effect is executed.| 576 577## NavPathStack<sup>10+</sup> 578 579Implements a navigation stack, which allows for inheritance since API version 12. You can add new properties and methods in derived classes, or you can override the methods of the base **NavPathStack** class. Objects of the derived class can be used in place of objects of the base **NavPathStack** class. For details, see [Example 10](#example-10-defining-a-derived-class-of-navpathstack). 580 581> **NOTE** 582> 583> 1. When multiple page stack operations are triggered in succession, the intermediate states are bypassed, and only the final result of the stack operations is rendered.<br> 584> For example, if a Page1 is popped and then immediately pushed back, the system considers that the states before and after these operations are identical, leading to no actual change in the stack. To ensure that a new instance of Page1 is pushed onto the stack despite the consecutive operations, use the **NEW_INSTANCE** mode. 585> 586> 2. Avoid relying on lifecycle event listeners as a means to manage the navigation stack. 587 588### constructor 589 590constructor() 591 592**Atomic service API**: This API can be used in atomic services since API version 11. 593 594**System capability**: SystemCapability.ArkUI.ArkUI.Full 595 596### pushPath<sup>10+</sup> 597 598pushPath(info: NavPathInfo, animated?: boolean): void 599 600Pushes the navigation destination page specified by **info** onto the navigation stack. 601 602**Atomic service API**: This API can be used in atomic services since API version 11. 603 604**System capability**: SystemCapability.ArkUI.ArkUI.Full 605 606**Parameters** 607 608| Name | Type | Mandatory | Description | 609| ---- | ----------------------------- | ---- | -------------------- | 610| info | [NavPathInfo](#navpathinfo10) | Yes | Information about the navigation destination page.| 611| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 612 613### pushPath<sup>12+</sup> 614 615pushPath(info: NavPathInfo, options?: NavigationOptions): void 616 617Pushes the navigation destination page specified by **info** onto the navigation stack. Depending on the [LaunchMode](#launchmode12) specified in the **options** parameter, different behaviors will be triggered. 618 619**Atomic service API**: This API can be used in atomic services since API version 12. 620 621**System capability**: SystemCapability.ArkUI.ArkUI.Full 622 623**Parameters** 624 625| Name | Type | Mandatory | Description | 626| ---- | ----------------------------- | ---- | -------------------- | 627| info | [NavPathInfo](#navpathinfo10) | Yes | Information about the navigation destination page.| 628| options | [NavigationOptions](#navigationoptions12) | No | Navigation options.| 629 630### pushPathByName<sup>10+</sup> 631 632pushPathByName(name: string, param: unknown, animated?: boolean): void 633 634Pushes the navigation destination page specified by **name**, with the data specified by **param**, to the navigation stack. 635 636**Atomic service API**: This API can be used in atomic services since API version 11. 637 638**System capability**: SystemCapability.ArkUI.ArkUI.Full 639 640**Parameters** 641 642| Name | Type | Mandatory | Description | 643| ----- | ------- | ---- | --------------------- | 644| name | string | Yes | Name of the navigation destination page. | 645| param | unknown | Yes | Detailed parameters of the navigation destination page.| 646| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 647 648### pushPathByName<sup>11+</sup> 649 650pushPathByName(name: string, param: Object, onPop: Callback\<PopInfo>, animated?: boolean): void 651 652Pushes the navigation destination page specified by **name**, with the data specified by **param**, to the navigation stack. This API uses the **onPop** callback to receive the result returned when the page is popped out of the stack. 653 654**Atomic service API**: This API can be used in atomic services since API version 12. 655 656**System capability**: SystemCapability.ArkUI.ArkUI.Full 657 658**Parameters** 659 660| Name| Type| Mandatory| Description| 661|------|------|------|------| 662| name | string | Yes | Name of the navigation destination page. | 663| param | Object | Yes | Detailed parameters of the navigation destination page.| 664| onPop | Callback\<[PopInfo](#popinfo11)> | Yes| Callback used to receive the result. It is invoked only after the **result** parameter is set in **pop**.| 665| animated | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 666 667### pushDestination<sup>11+</sup> 668 669pushDestination(info: NavPathInfo, animated?: boolean): Promise<void> 670 671Pushes the navigation destination page specified by **info** onto the navigation stack. This API uses a promise to return the result. 672 673**Atomic service API**: This API can be used in atomic services since API version 12. 674 675**System capability**: SystemCapability.ArkUI.ArkUI.Full 676 677**Parameters** 678 679| Name | Type | Mandatory | Description | 680| ---- | ----------------------------- | ---- | -------------------- | 681| info | [NavPathInfo](#navpathinfo10) | Yes | Information about the navigation destination page.| 682| animated | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 683 684**Return value** 685 686| Type | Description | 687| ------------------- | --------- | 688| Promise<void> | Promise used to return the result.| 689 690**Error codes** 691 692For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Router Error Codes](../errorcode-router.md). 693 694| ID | Error Message| 695| --------- | ------- | 696| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 697| 100001 | Internal error.| 698| 100005 | Builder function not registered. | 699| 100006 | NavDestination not found.| 700 701### pushDestination<sup>12+</sup> 702 703pushDestination(info: NavPathInfo, options?: NavigationOptions): Promise<void> 704 705Pushes the navigation destination page specified by **info** onto the navigation stack. This API uses a promise to return the result. Depending on the [LaunchMode](#launchmode12) specified in the **options** parameter, different behaviors will be triggered. 706 707**Atomic service API**: This API can be used in atomic services since API version 12. 708 709**System capability**: SystemCapability.ArkUI.ArkUI.Full 710 711**Parameters** 712 713| Name | Type | Mandatory | Description | 714| ---- | ----------------------------- | ---- | -------------------- | 715| info | [NavPathInfo](#navpathinfo10) | Yes | Information about the navigation destination page.| 716| options | [NavigationOptions](#navigationoptions12) | No | Navigation options.| 717 718**Return value** 719 720| Type | Description | 721| ------------------- | --------- | 722| Promise<void> | Promise used to return the result.| 723 724**Error codes** 725 726For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Router Error Codes](../errorcode-router.md). 727 728| ID | Error Message| 729| --------- | ------- | 730| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 731| 100001 | Internal error.| 732| 100005 | Builder function not registered. | 733| 100006 | NavDestination not found.| 734 735### pushDestinationByName<sup>11+</sup> 736 737pushDestinationByName(name: string, param: Object, animated?: boolean): Promise<void> 738 739Pushes the navigation destination page specified by **name**, with the data specified by **param**, to the navigation stack. This API uses a promise to return the result. 740 741**Atomic service API**: This API can be used in atomic services since API version 12. 742 743**System capability**: SystemCapability.ArkUI.ArkUI.Full 744 745**Parameters** 746 747| Name | Type | Mandatory | Description | 748| ----- | ------- | ---- | --------------------- | 749| name | string | Yes | Name of the navigation destination page. | 750| param | Object | Yes | Detailed parameters of the navigation destination page.| 751| animated | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 752 753**Return value** 754 755| Type | Description | 756| ------------------- | --------- | 757| Promise<void> | Promise used to return the result.| 758 759**Error codes** 760 761For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Router Error Codes](../errorcode-router.md). 762 763| ID | Error Message| 764| --------- | ------- | 765| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 766| 100001 | Internal error.| 767| 100005 | Builder function not registered. | 768| 100006 | NavDestination not found.| 769 770### pushDestinationByName<sup>11+</sup> 771 772pushDestinationByName(name: string, param: Object, onPop: Callback\<PopInfo>, animated?: boolean): Promise<void> 773 774Pushes the navigation destination page specified by **name**, with the data specified by **param**, to the navigation stack. This API uses the **onPop** callback to handle the result returned when the page is popped out of the stack. It uses a promise to return the result. 775 776**Atomic service API**: This API can be used in atomic services since API version 12. 777 778**System capability**: SystemCapability.ArkUI.ArkUI.Full 779 780**Parameters** 781 782| Name | Type | Mandatory | Description | 783| ----- | ------- | ---- | --------------------- | 784| name | string | Yes | Name of the navigation destination page. | 785| param | Object | Yes | Detailed parameters of the navigation destination page.| 786| onPop | Callback\<[PopInfo](#popinfo11)> | Yes | Callback used to handle the result returned when the page is popped out of the stack. It is invoked only after the **result** parameter is set in **pop**.| 787| animated | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 788 789**Return value** 790 791| Type | Description | 792| ------------------- | --------- | 793| Promise<void> | Promise used to return the result.| 794 795**Error codes** 796 797For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Router Error Codes](../errorcode-router.md). 798 799| ID | Error Message| 800| --------- | ------- | 801| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 802| 100001 | Internal error.| 803| 100005 | Builder function not registered. | 804| 100006 | NavDestination not found.| 805 806### replacePath<sup>11+</sup> 807 808replacePath(info: NavPathInfo, animated?: boolean): void 809 810Replaces the top of the navigation stack with the page specified by **info**. 811 812**Atomic service API**: This API can be used in atomic services since API version 12. 813 814**System capability**: SystemCapability.ArkUI.ArkUI.Full 815 816**Parameters** 817 818| Name | Type | Mandatory | Description | 819| ---- | ----------------------------- | ---- | -------------------- | 820| info | [NavPathInfo](#navpathinfo10) | Yes | Parameters for the new top page of the navigation stack.| 821| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 822 823### replacePath<sup>12+</sup> 824 825replacePath(info: NavPathInfo, options?: NavigationOptions): void 826 827Replaces the top page on the navigation stack. Depending on the [LaunchMode](#launchmode12) specified in the **options** parameter, different behaviors will be triggered. 828 829**Atomic service API**: This API can be used in atomic services since API version 12. 830 831**System capability**: SystemCapability.ArkUI.ArkUI.Full 832 833**Parameters** 834 835| Name | Type | Mandatory | Description | 836| ---- | ----------------------------- | ---- | -------------------- | 837| info | [NavPathInfo](#navpathinfo10) | Yes | Parameters for the new top page of the navigation stack.| 838| options | [NavigationOptions](#navigationoptions12) | No | Navigation options.| 839 840### replacePathByName<sup>11+</sup> 841 842replacePathByName(name: string, param: Object, animated?: boolean): void 843 844Replaces the top of the navigation stack with the page specified by **name**. 845 846**Atomic service API**: This API can be used in atomic services since API version 12. 847 848**System capability**: SystemCapability.ArkUI.ArkUI.Full 849 850**Parameters** 851 852| Name | Type | Mandatory | Description | 853| ----- | ------- | ---- | --------------------- | 854| name | string | Yes | Name of the navigation destination page. | 855| param | Object | Yes | Detailed parameters of the navigation destination page.| 856| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 857 858### replaceDestination<sup>18+</sup> 859 860replaceDestination(info: NavPathInfo, options?: NavigationOptions): Promise<void> 861 862Performs a replacement operation on the navigation stack This API uses a promise to return the result. Its behavior varies depending on the value of [LaunchMode](#launchmode12) specified in **options**. 863 864**Atomic service API**: This API can be used in atomic services since API version 18. 865 866**System capability**: SystemCapability.ArkUI.ArkUI.Full 867 868**Parameters** 869 870| Name | Type | Mandatory | Description | 871| ---- | ----------------------------- | ---- | -------------------- | 872| info | [NavPathInfo](#navpathinfo10) | Yes | Information about the navigation destination page.| 873| options | [NavigationOptions](#navigationoptions12) | No | Navigation options.| 874 875**Return value** 876 877| Type | Description | 878| ------------------- | --------- | 879| Promise<void> | Promise used to return the result.| 880 881**Error codes** 882 883For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Router Error Codes](../errorcode-router.md). 884 885| ID | Error Message| 886| --------- | ------- | 887| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 888| 100001 | Internal error.| 889| 100005 | Builder function not registered. | 890| 100006 | NavDestination not found.| 891 892### removeByIndexes<sup>11+</sup> 893 894removeByIndexes(indexes: Array<number\>): number 895 896Removes the navigation destination pages specified by **indexes** from the navigation stack. 897 898**Atomic service API**: This API can be used in atomic services since API version 12. 899 900**System capability**: SystemCapability.ArkUI.ArkUI.Full 901 902**Parameters** 903 904| Name | Type | Mandatory | Description | 905| ----- | ------- | ---- | --------------------- | 906| indexes | Array<number\> | Yes | Array of indexes of the navigation destination pages to remove. The index is zero-based. | 907 908**Return value** 909 910| Type | Description | 911| ----------- | ------------------------ | 912| number | Number of the navigation destination pages removed.| 913 914### removeByName<sup>11+</sup> 915 916removeByName(name: string): number 917 918Removes the navigation destination page specified by **name** from the navigation stack. 919 920**Atomic service API**: This API can be used in atomic services since API version 12. 921 922**System capability**: SystemCapability.ArkUI.ArkUI.Full 923 924**Parameters** 925 926| Name | Type | Mandatory | Description | 927| ----- | ------- | ---- | --------------------- | 928| name | string | Yes | Name of the navigation destination page to remove. | 929 930**Return value** 931 932| Type | Description | 933| ----------- | ------------------------ | 934| number | Number of the navigation destination pages removed.| 935 936### removeByNavDestinationId<sup>12+</sup> 937 938removeByNavDestinationId(navDestinationId: string): boolean 939 940Removes the navigation destination page specified by **navDestinationId** from the navigation stack. **navDestinationId** can be obtained from the [onReady](ts-basic-components-navdestination.md#onready11) callback of **NavDestination** or from [NavDestinationInfo](../js-apis-arkui-observer.md#navdestinationinfo). 941 942**Atomic service API**: This API can be used in atomic services since API version 12. 943 944**System capability**: SystemCapability.ArkUI.ArkUI.Full 945 946**Parameters** 947 948| Name | Type | Mandatory | Description | 949| ----- | ------- | ---- | --------------------- | 950| navDestinationId | string | Yes | Unique ID of the navigation destination page to remove. | 951 952**Return value** 953 954| Type | Description | 955| ----------- | ------------------------ | 956| boolean | Whether the page is removed successfully.<br>**true**: success<br>**false**: failure| 957 958### pop<sup>10+</sup> 959 960pop(animated?: boolean): NavPathInfo | undefined 961 962Pops the top element out of the navigation stack. 963 964**Atomic service API**: This API can be used in atomic services since API version 11. 965 966**System capability**: SystemCapability.ArkUI.ArkUI.Full 967 968**Parameters** 969 970| Name | Type | Mandatory | Description | 971| ---- | ----------------------------- | ---- | -------------------- | 972| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 973 974**Return value** 975 976| Type | Description | 977| ----------- | ------------------------ | 978| [NavPathInfo](#navpathinfo10) | Returns the information about the navigation destination page at the top of the stack.| 979| undefined | Returns **undefined** if the navigation stack is empty. | 980 981### pop<sup>11+</sup> 982 983pop(result: Object, animated?: boolean): NavPathInfo | undefined 984 985Pops the top element out of the navigation stack and invokes the **onPop** callback to pass the page processing result. 986 987**Atomic service API**: This API can be used in atomic services since API version 12. 988 989**System capability**: SystemCapability.ArkUI.ArkUI.Full 990 991**Parameters** 992 993| Name | Type | Mandatory | Description | 994| ---- | ----------------------------- | ---- | -------------------- | 995| result | Object | Yes| Custom processing result on the page. The boolean type is not supported.| 996| animated | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 997 998**Return value** 999 1000| Type | Description | 1001| ----------- | ------------------------ | 1002| [NavPathInfo](#navpathinfo10) | Returns the information about the navigation destination page at the top of the stack.| 1003| undefined | Returns **undefined** if the navigation stack is empty. | 1004 1005### popToName<sup>10+</sup> 1006 1007popToName(name: string, animated?: boolean): number 1008 1009Pops pages until the first navigation destination page that matches **name** from the bottom of the navigation stack is at the top of the stack. 1010 1011**Atomic service API**: This API can be used in atomic services since API version 11. 1012 1013**System capability**: SystemCapability.ArkUI.ArkUI.Full 1014 1015**Parameters** 1016 1017| Name | Type | Mandatory | Description | 1018| ---- | ------ | ---- | ------------------- | 1019| name | string | Yes | Name of the navigation destination page.| 1020| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1021 1022**Return value** 1023 1024| Type | Description | 1025| ------ | ---------------------------------------- | 1026| number | Returns the index of the first navigation destination page that matches **name** from the bottom of the navigation stack; returns **-1** if such a page does not exist.| 1027 1028### popToName<sup>11+</sup> 1029 1030popToName(name: string, result: Object, animated?: boolean): number 1031 1032Pops pages until the first navigation destination page that matches **name** from the bottom of the navigation stack is at the top of the stack. This API uses the **onPop** callback to pass in the page processing result. 1033 1034**Atomic service API**: This API can be used in atomic services since API version 12. 1035 1036**System capability**: SystemCapability.ArkUI.ArkUI.Full 1037 1038**Parameters** 1039 1040| Name | Type | Mandatory | Description | 1041| ---- | ------ | ---- | ------------------- | 1042| name | string | Yes | Name of the navigation destination page.| 1043| result | Object | Yes| Custom processing result on the page. The boolean type is not supported.| 1044| animated | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1045 1046**Return value** 1047 1048| Type | Description | 1049| ------ | ---------------------------------------- | 1050| number | Returns the index of the first navigation destination page that matches **name** from the bottom of the navigation stack; returns **-1** if such a page does not exist.| 1051 1052### popToIndex<sup>10+</sup> 1053 1054popToIndex(index: number, animated?: boolean): void 1055 1056Returns the navigation stack to the page specified by **index**. 1057 1058**Atomic service API**: This API can be used in atomic services since API version 11. 1059 1060**System capability**: SystemCapability.ArkUI.ArkUI.Full 1061 1062**Parameters** 1063 1064| Name | Type | Mandatory | Description | 1065| ----- | ------ | ---- | ---------------------- | 1066| index | number | Yes | Index of the navigation destination page. The index is zero-based.| 1067| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1068 1069### popToIndex<sup>11+</sup> 1070 1071popToIndex(index: number, result: Object, animated?: boolean): void 1072 1073Returns the navigation stack to the page specified by **index** and invokes the **onPop** callback to pass the page processing result. 1074 1075**Atomic service API**: This API can be used in atomic services since API version 11. 1076 1077**System capability**: SystemCapability.ArkUI.ArkUI.Full 1078 1079**Parameters** 1080 1081| Name | Type | Mandatory | Description | 1082| ----- | ------ | ---- | ---------------------- | 1083| index | number | Yes | Index of the navigation destination page. The index is zero-based.| 1084| result | Object | Yes| Custom processing result on the page. The boolean type is not supported.| 1085| animated | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1086 1087### moveToTop<sup>10+</sup> 1088 1089moveToTop(name: string, animated?: boolean): number 1090 1091Moves the first navigation destination page that matches **name** from the bottom of the navigation stack to the top of the stack. 1092 1093**Atomic service API**: This API can be used in atomic services since API version 11. 1094 1095**System capability**: SystemCapability.ArkUI.ArkUI.Full 1096 1097**Parameters** 1098 1099| Name | Type | Mandatory | Description | 1100| ---- | ------ | ---- | ------------------- | 1101| name | string | Yes | Name of the navigation destination page.| 1102| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1103 1104**Return value** 1105 1106| Type | Description | 1107| ------ | ---------------------------------------- | 1108| number | Returns the index of the first navigation destination page that matches **name** from the bottom of the navigation stack; returns **-1** if such a page does not exist.| 1109 1110### moveIndexToTop<sup>10+</sup> 1111 1112moveIndexToTop(index: number, animated?: boolean): void 1113 1114Moves to the top of the navigation stack the navigation destination page specified by **index**. 1115 1116**Atomic service API**: This API can be used in atomic services since API version 11. 1117 1118**System capability**: SystemCapability.ArkUI.ArkUI.Full 1119 1120**Parameters** 1121 1122| Name | Type | Mandatory | Description | 1123| ----- | ------ | ---- | ---------------------- | 1124| index | number | Yes | Index of the navigation destination page. The index is zero-based.| 1125| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1126 1127### clear<sup>10+</sup> 1128 1129clear(animated?: boolean): void 1130 1131Clears the navigation stack. 1132 1133**Atomic service API**: This API can be used in atomic services since API version 11. 1134 1135**System capability**: SystemCapability.ArkUI.ArkUI.Full 1136 1137**Parameters** 1138 1139| Name | Type | Mandatory | Description | 1140| ----- | ------ | ---- | ---------------------- | 1141| animated<sup>11+</sup> | boolean | No | Whether to support the transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1142 1143### getAllPathName<sup>10+</sup> 1144 1145getAllPathName(): Array<string\> 1146 1147Obtains the names of all navigation destination pages in the navigation stack. 1148 1149**Atomic service API**: This API can be used in atomic services since API version 11. 1150 1151**System capability**: SystemCapability.ArkUI.ArkUI.Full 1152 1153**Return value** 1154 1155| Type | Description | 1156| -------------- | -------------------------- | 1157| Array<string\> | Names of all navigation destination pages in the navigation stack.| 1158 1159### getParamByIndex<sup>10+</sup> 1160 1161getParamByIndex(index: number): unknown | undefined 1162 1163Obtains the parameter information of the navigation destination page specified by **index**. 1164 1165**Atomic service API**: This API can be used in atomic services since API version 11. 1166 1167**System capability**: SystemCapability.ArkUI.ArkUI.Full 1168 1169**Parameters** 1170 1171| Name | Type | Mandatory | Description | 1172| ----- | ------ | ---- | ---------------------- | 1173| index | number | Yes | Index of the navigation destination page. The index is zero-based.| 1174 1175**Return value** 1176 1177| Type | Description | 1178| --------- | -------------------------- | 1179| unknown | Parameter information of the matching navigation destination page.| 1180| undefined | Returned if the provided index is invalid. | 1181 1182### getParamByName<sup>10+</sup> 1183 1184getParamByName(name: string): Array<unknown\> 1185 1186Obtains the parameter information of all the navigation destination pages that match **name**. 1187 1188**Atomic service API**: This API can be used in atomic services since API version 11. 1189 1190**System capability**: SystemCapability.ArkUI.ArkUI.Full 1191 1192**Parameters** 1193 1194| Name | Type | Mandatory | Description | 1195| ---- | ------ | ---- | ------------------- | 1196| name | string | Yes | Name of the navigation destination page.| 1197 1198**Return value** 1199 1200| Type | Description | 1201| --------------- | --------------------------------- | 1202| Array<unknown\> | Parameter information of all the matching navigation destination pages.| 1203 1204### getIndexByName<sup>10+</sup> 1205 1206getIndexByName(name: string): Array<number\> 1207 1208Obtains the indexes of all the navigation destination pages that match **name**. 1209 1210**Atomic service API**: This API can be used in atomic services since API version 11. 1211 1212**System capability**: SystemCapability.ArkUI.ArkUI.Full 1213 1214**Parameters** 1215 1216| Name | Type | Mandatory | Description | 1217| ---- | ------ | ---- | ------------------- | 1218| name | string | Yes | Name of the navigation destination page.| 1219 1220**Return value** 1221 1222| Type | Description | 1223| -------------- | --------------------------------- | 1224| Array<number\> | Indexes of all the matching navigation destination pages. If no pages with the specified name exist in the navigation stack, an empty array is returned. The index range is [0, navigation stack size - 1].| 1225 1226### size<sup>10+</sup> 1227 1228size(): number 1229 1230Obtains the stack size. 1231 1232**Atomic service API**: This API can be used in atomic services since API version 11. 1233 1234**System capability**: SystemCapability.ArkUI.ArkUI.Full 1235 1236**Return value** 1237 1238| Type | Description | 1239| ------ | ------ | 1240| number | Stack size.<br>Value range: [0, +∞)| 1241 1242### disableAnimation<sup>11+</sup> 1243 1244disableAnimation(value: boolean): void 1245 1246Disables or enables the transition animation in the **Navigation** component. 1247 1248**Atomic service API**: This API can be used in atomic services since API version 12. 1249 1250**System capability**: SystemCapability.ArkUI.ArkUI.Full 1251 1252**Parameters** 1253 1254| Name | Type | Mandatory | Description | 1255| ----- | ------ | ---- | ---------------------- | 1256| value | boolean | Yes | Whether to disable the transition animation.<br>Default value: **false**<br>**true**:The transition animation is disabled.<br>**false**: The transition animation is not disabled.| 1257 1258### getParent<sup>11+</sup> 1259 1260getParent(): NavPathStack | null 1261 1262Obtains the parent navigation path stack.<br>When a **Navigation** component is nested (directly or indirectly) insider another **Navigation** component, the internal one can obtain the navigation path stack of the external one. 1263 1264**Atomic service API**: This API can be used in atomic services since API version 11. 1265 1266**System capability**: SystemCapability.ArkUI.ArkUI.Full 1267 1268**Return value** 1269 1270| Type | Description | 1271| ------ | ------ | 1272| [NavPathStack](#navpathstack10) \| null | Navigation path stack of the external **Navigation** component inside which the current **Navigation** component is nested. If no nesting is involved, **null** is returned.| 1273 1274### setInterception<sup>12+</sup> 1275 1276setInterception(interception: NavigationInterception): void 1277 1278Sets the interception callback for navigation page redirection. 1279 1280**Atomic service API**: This API can be used in atomic services since API version 12. 1281 1282**System capability**: SystemCapability.ArkUI.ArkUI.Full 1283 1284**Parameters** 1285 1286| Name | Type | Mandatory | Description | 1287| ---- | ---- | --- | ---| 1288|interception| [NavigationInterception](#navigationinterception12)| Yes| Object to be intercepted during navigation redirection.| 1289 1290## NavPathInfo<sup>10+</sup> 1291 1292Provides the navigation page information. 1293 1294### constructor 1295 1296constructor(name: string, param: unknown, onPop?: Callback\<PopInfo>, isEntry?: boolean) 1297 1298**Atomic service API**: This API can be used in atomic services since API version 11. 1299 1300**System capability**: SystemCapability.ArkUI.ArkUI.Full 1301 1302| Name | Type | Mandatory | Description | 1303| ----- | ------- | ---- | --------------------- | 1304| name | string | Yes | Name of the navigation destination page. | 1305| param | unknown | Yes | Detailed parameters of the navigation destination page.| 1306| onPop<sup>11+</sup> | Callback\<[PopInfo](#popinfo11)> | No| Callback returned when [pop](#pop11) is called on the navigation destination page. It is invoked only after the **result** parameter is set in [pop](#pop11).| 1307| isEntry<sup>12+</sup> | boolean | No| Whether the navigation destination page is the entry page.<br>Default value: **false**<br>**true**: The navigation destination page is the entry page.<br>**false**: The navigation destination page is not the entry page.<br>The value of this parameter is reviewed or reset under the following conditions:<br>- When a global back event is triggered on the current navigation destination page.<br> - When the application is switched to the background.<br>**NOTE**<br>The navigation destination page serving as an entry does not respond to the in-app global back events; instead, it directly triggers the global back event between applications.| 1308 1309### Properties 1310 1311**System capability**: SystemCapability.ArkUI.ArkUI.Full 1312 1313| Name | Type | Mandatory | Description | 1314| ----- | ------- | ---- | --------------------- | 1315| name | string | Yes | Name of the navigation destination page.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1316| param | unknown | No | Detailed parameters of the navigation destination page.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1317| onPop<sup>11+</sup> | Callback\<[PopInfo](#popinfo11)> | No| Callback returned when [pop](#pop11) is called on the navigation destination page. It is invoked only after the **result** parameter is set in [pop](#pop11).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1318| isEntry<sup>12+</sup> | boolean | No| Whether the navigation destination page is the entry page.<br>Default value: **false**<br>**true**: The navigation destination page is the entry page.<br>**false**: The navigation destination page is not the entry page.<br>The value of this parameter is reviewed or reset under the following conditions:<br>- When a global back event is triggered on the current navigation destination page.<br> - When the application is switched to the background.<br>**NOTE**<br>The navigation destination page serving as an entry does not respond to the in-app global back events; instead, it directly triggers the global back event between applications.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1319 1320## PopInfo<sup>11+</sup> 1321 1322Provides the callback information returned when a page is popped out of the navigation stack. 1323 1324**Atomic service API**: This API can be used in atomic services since API version 12. 1325 1326**System capability**: SystemCapability.ArkUI.ArkUI.Full 1327 1328| Name| Type| Mandatory| Description| 1329|------|-----|-----|-----| 1330| info | [NavPathInfo](#navpathinfo10) | Yes| Information about the current page when a back action is performed. The value is automatically obtained by the system.| 1331| result | Object | Yes| Result returned when a back action is performed. You must customize the object.| 1332 1333## NavContentInfo<sup>11+</sup> 1334 1335Provides the destination information. 1336 1337**Atomic service API**: This API can be used in atomic services since API version 12. 1338 1339**System capability**: SystemCapability.ArkUI.ArkUI.Full 1340 1341| Name | Type | Mandatory | Description | 1342|-------|-------|------|-------| 1343| name | string | No| Name of the navigation destination. If the view is a root view (**NavBar**), the return value is **undefined**.| 1344| index | number | Yes| Index of the navigation destination in the navigation stack. If the view is a root view (**NavBar**), the return value is **-1**.<br>Value range: [-1, +∞)| 1345| mode | [NavDestinationMode](ts-basic-components-navdestination.md#navdestinationmode11) | No| Mode of the navigation destination. If the view is a root view (**NavBar**), the return value is **undefined**.| 1346| param<sup>12+</sup> | Object | No| Parameters loaded on the navigation destination page.| 1347| navDestinationId<sup>12+</sup> | string | No| Unique identifier of the navigation destination page.| 1348 1349## NavigationAnimatedTransition<sup>11+</sup> 1350 1351Defines the custom transition animation protocol. You need to implement this protocol to define the redirection animation of the navigation route. 1352 1353**Atomic service API**: This API can be used in atomic services since API version 12. 1354 1355**System capability**: SystemCapability.ArkUI.ArkUI.Full 1356 1357| Name| Type| Mandatory| Description| 1358|------|-----|-----|------| 1359| timeout | number | No| Animation timeout time.<br> Unit: ms<br>Value range: [0, +∞)<br> Default value: no default value for interactive animations; 1000 ms for non-interactive animations.| 1360| transition | (transitionProxy : [NavigationTransitionProxy](#navigationtransitionproxy-11)) => void | Yes| Callback for executing the custom transition animation.<br> **transitionProxy**: proxy for the custom transition animation.| 1361| onTransitionEnd | (success: boolean) => void | No| Callback invoked when the transition is complete.<br> **success**: whether the transition is successful.| 1362| isInteractive<sup>12+</sup> | boolean | No| Whether the transition animation is interactive.<br> Default value: **false**<br>**true**: The transition animation is interactive.<br>**false**: The transition animation is not interactive.| 1363 1364## NavigationTransitionProxy <sup>11+</sup> 1365 1366Implements a custom transition animation proxy. 1367 1368**System capability**: SystemCapability.ArkUI.ArkUI.Full 1369 1370### Attributes 1371 1372**Atomic service API**: This API can be used in atomic services since API version 12. 1373 1374**System capability**: SystemCapability.ArkUI.ArkUI.Full 1375 1376| Name| Type | Mandatory| Description | 1377|------|-------|-----|-------| 1378| from | [NavContentInfo](#navcontentinfo11) | Yes| Information about the exit page.| 1379| to | [NavContentInfo](#navcontentinfo11) | Yes| Information about the enter page.| 1380| isInteractive<sup>12+</sup> | boolean | No| Whether the transition animation is interactive.<br>**true**: The transition animation is interactive.<br>**false**: The transition animation is not interactive.| 1381 1382### finishTransition 1383 1384finishTransition(): void; 1385 1386Finishes this custom transition animation. This API must be manually called to end the animation. Otherwise, the system ends the animation when the timeout expires. 1387 1388**Atomic service API**: This API can be used in atomic services since API version 12. 1389 1390**System capability**: SystemCapability.ArkUI.ArkUI.Full 1391 1392### cancelTransition<sup>12+</sup> 1393 1394cancelTransition?(): void; 1395 1396Cancels this interactive transition animation, restoring the navigation stack to its state before page redirection. (Non-interactive transition animations cannot be canceled.) 1397 1398**Atomic service API**: This API can be used in atomic services since API version 12. 1399 1400**System capability**: SystemCapability.ArkUI.ArkUI.Full 1401 1402### updateTransition<sup>12+</sup> 1403 1404updateTransition?(progress: number): void; 1405 1406Updates the progress of this interactive transition animation. (Non-interactive animations do not support setting the animation progress). 1407 1408**Atomic service API**: This API can be used in atomic services since API version 12. 1409 1410**System capability**: SystemCapability.ArkUI.ArkUI.Full 1411 1412**Parameters** 1413 1414| Name| Type| Mandatory| Description| 1415|------|------|------|-----| 1416| progress | number | Yes| Progress percentage of the interactive transition animation. The value ranges from 0 to 1.| 1417 1418## NavigationInterception<sup>12+</sup> 1419 1420Describes the object to be intercepted during navigation redirection. 1421 1422**Atomic service API**: This API can be used in atomic services since API version 12. 1423 1424**System capability**: SystemCapability.ArkUI.ArkUI.Full 1425 1426| Name | Type | Mandatory| Description | 1427| ---- | ----- | ----- | ---- | 1428| willShow | [InterceptionShowCallback](#interceptionshowcallback12) | No| Interception before page redirection, allowing for stack operations. The setting takes effect in the current redirection.| 1429| didShow | [InterceptionShowCallback](#interceptionshowcallback12) | No| Callback after page redirection. The setting takes effect in the next redirection.| 1430| modeChange | [InterceptionModeCallback](#interceptionmodecallback12) | No| Callback invoked when the display mode of the **Navigation** component switches between single-column and dual-column.| 1431 1432### InterceptionShowCallback<sup>12+</sup> 1433 1434type InterceptionShowCallback = (from: NavDestinationContext|NavBar, to: NavDestinationContext|NavBar, operation: NavigationOperation, isAnimated: boolean) => void 1435 1436Represents the interception callback before and after the navigation page. 1437 1438**Atomic service API**: This API can be used in atomic services since API version 12. 1439 1440**System capability**: SystemCapability.ArkUI.ArkUI.Full 1441 1442| Name | Type | Mandatory| Description | 1443| ------ | ------ | ---- | ---------------- | 1444| from | [NavDestinationContext](ts-basic-components-navdestination.md#navdestinationcontext11) \|[NavBar](#navbar12) | Yes| Information about the top page in the navigation stack before page redirection. The value **navBar** indicates that the top page is the home page.| 1445| to | [NavDestinationContext](ts-basic-components-navdestination.md#navdestinationcontext11) \|[NavBar](#navbar12) | Yes| Information about the top page in the navigation stack after page redirection. The value **navBar** indicates that the top page is the home page.| 1446| operation | [NavigationOperation](#navigationoperation11) | Yes| Current page redirection type.| 1447| isAnimated | boolean | Yes| Whether to enable the transition animation.<br>**true**: The transition animation is enabled.<br>**false**: The transition animation is disabled.| 1448 1449### InterceptionModeCallback<sup>12+</sup> 1450 1451type InterceptionModeCallback = (mode: NavigationMode) => void 1452 1453Implements an interception callback triggered when the display mode of the **Navigation** component switches between single-column and dual-column. 1454 1455**Atomic service API**: This API can be used in atomic services since API version 12. 1456 1457**System capability**: SystemCapability.ArkUI.ArkUI.Full 1458 1459| Name | Type | Mandatory| Description | 1460| ------ | ------ | ---- | ---------------- | 1461| mode | [NavigationMode](#navigationmode9) | Yes| Display mode of the navigation bar.| 1462 1463## NavBar<sup>12+</sup> 1464 1465type NavBar = 'navBar' 1466 1467Defines the name of the navigation home page. 1468 1469**Atomic service API**: This API can be used in atomic services since API version 12. 1470 1471**System capability**: SystemCapability.ArkUI.ArkUI.Full 1472 1473| Type | Description | 1474| -------- | ---------------- | 1475| 'navBar' | Navigation home page.| 1476 1477## NavigationMenuItem 1478 1479**System capability**: SystemCapability.ArkUI.ArkUI.Full 1480 1481| Name | Type | Mandatory | Description | 1482| ------ | ------------- | ---- | --------------- | 1483| value | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | Yes | Text of the menu item. Its visibility varies by the API version.<br>API version 9: visible.<br> API version 10: invisible.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1484| icon | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | No | Icon path of the menu item.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1485| isEnabled<sup>12+</sup> | boolean | No | Enabled status.<br>**true** (default): enabled<br>**false**: disabled<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1486| action | () => void | No | Callback invoked when the menu item is selected.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1487| symbolIcon<sup>12+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No |Symbol icon for a single option on the menu bar. It has higher priority than **icon**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1488 1489## ToolbarItem<sup>10+</sup> 1490 1491**Atomic service API**: This API can be used in atomic services since API version 11. 1492 1493**System capability**: SystemCapability.ArkUI.ArkUI.Full 1494 1495| Name | Type | Mandatory | Description | 1496| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 1497| value | ResourceStr | Yes | Text of the toolbar item. | 1498| icon | ResourceStr | No | Icon path of the toolbar item. | 1499| action | () => void | No | Callback invoked when the toolbar item is selected. | 1500| status | [ToolbarItemStatus](#toolbaritemstatus10) | No | Status of the toolbar item.<br>Default value: **ToolbarItemStatus.NORMAL**| 1501| activeIcon | ResourceStr | No | Icon path of the toolbar item in the active state. | 1502| symbolIcon<sup>12+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No | Symbol icon for a single option on the toolbar. It has higher priority than **icon**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1503| activeSymbolIcon<sup>12+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No | Symbol icon for a single option on the menu bar when it is in active state. It has higher priority than **icon**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1504 1505## ToolbarItemStatus<sup>10+</sup> 1506 1507**Atomic service API**: This API can be used in atomic services since API version 11. 1508 1509**System capability**: SystemCapability.ArkUI.ArkUI.Full 1510 1511| Name | Value| Description | 1512| -------- | --- | ------------------------------------------------------------ | 1513| NORMAL | 0 | Normal state. In this state, the toolbar item takes on the default style and can switch to another state-specific style by responding to the hover, press, and focus events.| 1514| DISABLED | 1 | Disabled state. In this state, the toolbar item is disabled and does not allow for user interactions.| 1515| ACTIVE | 2 | Active state. In this state, the toolbar item can update its icon to the one specified by **activeIcon** by responding to a click event.| 1516 1517## NavigationTitleMode 1518 1519**Atomic service API**: This API can be used in atomic services since API version 11. 1520 1521**System capability**: SystemCapability.ArkUI.ArkUI.Full 1522 1523| Name| Value| Description | 1524| ---- | --- | ------------------------------------------------------------ | 1525| Free | 0 | When the content is more than one screen in a scrollable component, the main title shrinks as the content scrolls down (the subtitle fades out with its size remaining unchanged) and restores as the content scrolls up to the top.<br>**NOTE**<br>The effect where the main title's size changes in response to content scrolling is effective only when **title** is set to **ResourceStr** or **NavigationCommonTitle**. If **title** is set to any other value type, the main title changes in mere location when pulled down.<br>For this effect to work when the content is less than one screen in a scrollable component, set the **options** parameter of the scrollable component's [edgeEffect](ts-container-list.md#edgeeffect) attribute to **true**. In the non-scrolling state, the height of the title bar is the same as in **Full** mode; in the scrolling state, the minimum height of the title bar is the same as in **Mini** mode.| 1526| Mini | 1 | The title is fixed at mini mode.<br>Default value:<br>In versions earlier than API version 12, if there is only a main title, the title bar height is 56 vp; if there is both a main title and a subtitle, the title bar height is 82 vp.<br> Since API version 12, the title bar height is 56 vp.| 1527| Full | 2 | The title is fixed at full mode.<br>Default value: If there is only a main title, the title bar height is 112 vp; if there is both a main title and a subtitle, the title bar height is 138 vp.| 1528 1529## NavigationCommonTitle<sup>9+</sup> 1530 1531**Atomic service API**: This API can be used in atomic services since API version 11. 1532 1533**System capability**: SystemCapability.ArkUI.ArkUI.Full 1534 1535| Name | Type | Mandatory | Description | 1536| ---- | ------ | ---- | ------ | 1537| main | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | Yes | Main title.| 1538| sub | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | Yes | Subtitle.| 1539 1540## NavigationCustomTitle<sup>9+</sup> 1541 1542**Atomic service API**: This API can be used in atomic services since API version 11. 1543 1544**System capability**: SystemCapability.ArkUI.ArkUI.Full 1545 1546| Name | Type | Mandatory | Description | 1547| ------- | ---------------------------------------- | ---- | -------- | 1548| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Content of the title bar.| 1549| height | [TitleHeight](ts-appendix-enums.md#titleheight9) \| [Length](ts-types.md#length) | Yes | Height of the title bar.| 1550 1551## NavBarPosition<sup>9+</sup> 1552 1553**Atomic service API**: This API can be used in atomic services since API version 11. 1554 1555**System capability**: SystemCapability.ArkUI.ArkUI.Full 1556 1557| Name | Description | 1558| ----- | -------------------------------- | 1559| Start | When two columns are displayed, the main column is at the start of the main axis.| 1560| End | When two columns are displayed, the main column is at the end of the main axis.| 1561 1562## NavigationMode<sup>9+</sup> 1563 1564**Atomic service API**: This API can be used in atomic services since API version 11. 1565 1566**System capability**: SystemCapability.ArkUI.ArkUI.Full 1567 1568| Name | Description | 1569| ----- | ------------------------------------------------------------ | 1570| Stack | The navigation bar and content area are displayed independently of each other, which are equivalent to two pages. | 1571| Split | The navigation bar and content area are displayed in different columns.<br>The values of **navBarWidthRange** are represented by [minNavBarWidth,maxNavBarWidth].<br>1. When the value of **navBarWidth** is beyond the value range specified by **navBarWidthRange**, **navBarWidth** is set according to the following rules:<br>Value of **navBarWidth** < Value of **minNavBarWidth**: The value of **navBarWidth** is changed to that of **minNavBarWidth**.<br>Value of **navBarWidth** > Value of **maxNavBarWidth** and Result of [Component width - Value of **minContentWidth** - Divider width (1 vp)] > Value of **maxNavBarWidth**: The value of **navBarWidth** is changed to that of **maxNavBarWidth**.<br>Value of **navBarWidth** > Value of **maxNavBarWidth** and Result of [Component width - Value of **minContentWidth** - Divider width (1 vp)] < Value of **maxNavBarWidth**: The value of **navBarWidth** is changed to that of **minNavBarWidth**.<br>Value of **navBarWidth** > Value of **maxNavBarWidth** and Component width - Value of **minContentWidth** - Divider width (1 vp) is within the value range specified by **navBarWidthRange**: The value of **navBarWidth** is changed to Component width - Value of **minContentWidth** - Divider width (1 vp).<br>2. When the value of **navBarWidth** is within the value range specified by **navBarWidthRange**, **navBarWidth** is set according to the following rules:<br>Value of **minNavBarWidth** + Value of **minContentWidth** + Divider width (1 vp) > = Component width: The value of **navBarWidth** is changed to that of **minNavBarWidth**.<br>Value of **minNavBarWidth** + Value of **minContentWidth** + Divider width (1 vp) < Component width and Value of **navBarWidth** + Value of **minContentWidth** + Divider width (1 vp) > = Component width: The value of **navBarWidth** is changed to Component width - Value of **minContentWidth** - Divider width (1 vp).<br>Value of **minNavBarWidth** + Value of **minContentWidth** + Divider width (1 vp) < Component width and Value of **navBarWidth** + Value of **minContentWidth** + Divider width (1 vp) < Component width: The value of **navBarWidth** is the set value. <br>3. When the component size is decreased, the content area is shrunk until its width reaches the value defined by **minContentWidth**, and then the navigation bar is shrunk until its width reaches the value defined by **minNavBarWidth**; if the component size is further decreased, the content area is further shrunk until it disappears, and then navigation bar is shrunk.<br>4. When the navigation bar is set to a fixed size and the component size is continuously decreased, the navigation bar is shrunk.<br>5. If only **navBarWidth** is set, the width of the navigation bar is fixed at the value of **navBarWidth**, and the divider cannot be dragged.| 1572| Auto | In API version 9 and earlier versions: If the window width is greater than or equal to 520 vp, the Split mode is used; otherwise, the Stack mode is used.<br>In API version 10 and later versions: If the window width is greater than or equal to 600 vp, the Split mode is used; otherwise, the Stack mode is used. 600 vp = minNavBarWidth (240 vp) + minContentWidth (360 vp).| 1573 1574## NavigationOperation<sup>11+</sup> 1575 1576**Atomic service API**: This API can be used in atomic services since API version 12. 1577 1578**System capability**: SystemCapability.ArkUI.ArkUI.Full 1579 1580| Name | Value| Description| 1581|---------| --- |------| 1582|PUSH | 1 | The transition is enter transition.| 1583|POP | 2 | The transition is exit transition.| 1584| REPLACE | 3 | The transition is page replacement.| 1585 1586## BarStyle<sup>12+</sup> 1587 1588Enumerates the layout styles of the title bar and toolbar. Note that this API is not supported for the toolbar in **NavDestination**. 1589 1590**System capability**: SystemCapability.ArkUI.ArkUI.Full 1591 1592| Name | Value| Description| 1593|---------| --- |------| 1594|STANDARD | 0 | In this mode, the title bar or toolbar is laid out above the content area.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1595|STACK | 1 | In this mode, the title bar or toolbar is overlaid on top of the content area.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1596|SAFE_AREA_PADDING<sup>14+</sup> | 2 | In this mode, the title bar or toolbar is configured to respect the [component-level safe area](./ts-universal-attributes-size.md#safeareapadding14).<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 1597 1598## NavigationTitleOptions<sup>11+</sup> 1599 1600**System capability**: SystemCapability.ArkUI.ArkUI.Full 1601 1602| Name | Type | Mandatory | Description | 1603| ------ | ------------- | ---- | --------------- | 1604| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the title bar. If this parameter is not set, the default color is used.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1605| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No | Background blur style of the title bar. If this parameter is not set, the background blur effect is disabled.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1606| barStyle<sup>12+</sup> | [BarStyle](#barstyle12) | No | Layout style of the title bar.<br>Default value: **BarStyle.STANDARD**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1607| paddingStart<sup>12+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No | Padding at the start of the title bar.<br>Only supported in one of the following scenarios:<br>1. Displaying the back icon, that is, [hideBackButton](#hidebackbutton) is **false**<br>2. Using a non-custom title, that is, the [title value](#title) type is **ResourceStr** or **NavigationCommonTitle**<br>Default value:<br>LengthMetrics.resource(**$r('sys.float.margin_left')**)<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1608| paddingEnd<sup>12+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No | Padding at the end of the title bar.<br>Only supported in one of the following scenarios:<br>1. Using a non-custom menu, that is, the [menu value](#menus) is Array<NavigationMenuItem><br>2. Using a non-custom menu without a menu in the upper right corner, that is, the [title value](#title) type is **ResourceStr** or **NavigationCommonTitle**<br>Default value:<br>LengthMetrics.resource(**$r('sys.float.margin_right')**)<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1609| mainTitleModifier<sup>13+</sup> | [TextModifier](./ts-universal-attributes-attribute-modifier.md) | No| Main title attribute modifier.<br>Notes for using this modifier:<br>1. Attribute settings configured by this modifier will override the system's default attribute settings. For example, if the modifier is used to set font size attributes, such as **fontSize**, **maxFontSize**, and **minFontSize**, the settings will take precedence over the system's default settings for size-related attributes.<br>2. If no modifier is used or an invalid value is set, the system reverts to its default settings.<br>3. In [Free](#navigationtitlemode) mode, setting the font size will disable the effect where the main title's size changes in response to content scrolling.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 1610| subTitleModifier<sup>13+</sup> | [TextModifier](./ts-universal-attributes-attribute-modifier.md) | No| Subtitle attribute modifier.<br>Notes for using this modifier:<br>1. Attribute settings configured by this modifier will override the system's default attribute settings. For example, if the modifier is used to set font size attributes, such as **fontSize**, **maxFontSize**, and **minFontSize**, the settings will take precedence over the system's default settings for size-related attributes.<br>2. If no modifier is used or an invalid value is set, the system reverts to its default settings.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 1611| enableHoverMode<sup>13+</sup> | boolean | No| Whether to enable the hover mode.<br>Observe the following when using this API:<br>1. Make sure the **Navigation** component is in full screen.<br>2. When the title bar is in [Free](#navigationtitlemode) display mode or in [STANDARD](#barstyle12) layout style, this API has no effect.<br>Default value: **false**<br>**true**: Enable the hover mode.<br>**false**: Disable the hover mode.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 1612 1613## NavigationToolbarOptions<sup>11+</sup> 1614 1615**System capability**: SystemCapability.ArkUI.ArkUI.Full 1616 1617| Name | Type | Mandatory | Description | 1618| ------ | ------------- | ---- | --------------- | 1619| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the toolbar. If this parameter is not set, the default color is used.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1620| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No | Background blur style of the toolbar. If this parameter is not set, the background blur effect is disabled.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1621| barStyle<sup>14+</sup> | [BarStyle](#barstyle12) | No | Layout style of the toolbar.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 1622 1623## LaunchMode<sup>12+</sup> 1624 1625**Atomic service API**: This API can be used in atomic services since API version 12. 1626 1627**System capability**: SystemCapability.ArkUI.ArkUI.Full 1628 1629| Name | Value| Description| 1630| --------- | --- | ------ | 1631| STANDARD | 0 | Default navigation stack operation mode.<br>In this mode, push operations add the specified **NavDestination** page to the stack; replace operations replace the current top **NavDestination** page.| 1632| MOVE_TO_TOP_SINGLETON | 1 | This mode searches from the bottom to the top of the navigation stack. If a **NavDestination** page with the specified name exists, it moves that page to the top of the stack (for a replace operation, it replaces the last top **NavDestination** page with the specified one); otherwise, it behaves like **STANDARD**.| 1633| POP_TO_SINGLETON | 2 | This mode searches from the bottom to the top of the navigation stack. If a **NavDestination** page with the specified name exists, it removes all **NavDestination** pages above it(for a replace operation, it replaces the last top **NavDestination** page with the specified one); otherwise, it behaves like **STANDARD**.| 1634| NEW_INSTANCE | 3 | This mode creates an instance of **NavDestination**. Compared with **STANDARD**, this mode does not reuse the instance with the same name in the stack.| 1635 1636## NavigationOptions<sup>12+</sup> 1637 1638**Atomic service API**: This API can be used in atomic services since API version 12. 1639 1640**System capability**: SystemCapability.ArkUI.ArkUI.Full 1641 1642| Name | Type | Mandatory | Description | 1643| ------ | ------------- | ---- | --------------- | 1644| launchMode | [LaunchMode](#launchmode12) | No | Navigation stack operation mode.<br>Default value: **LaunchMode.STANDARD**| 1645| animated | boolean | No | Whether to support transition animation.<br>Default value: **true**<br>**true**: The transition animation is supported.<br>**false**: The transition animation is not supported.| 1646 1647## SystemBarStyle<sup>12+</sup> 1648 1649type SystemBarStyle = SystemBarStyle 1650 1651Describes the properties of the status bar. These properties are valid for the page-level status bar. 1652 1653**Atomic service API**: This API can be used in atomic services since API version 12. 1654 1655**System capability**: SystemCapability.ArkUI.ArkUI.Full 1656 1657| Type | Description | 1658| -------- | ------------------ | 1659| [SystemBarStyle](../js-apis-window.md#systembarstyle12) | Color of the text on the status bar. The default value is **'#0xE5FFFFFF'**.| 1660 1661## Example 1662 1663The outcome of the sample code may vary depending on the actual device used. The system routing table does not work with DevEco Studio Previewer, cross-platform functionality, or emulators. 1664 1665### Example 1: Implementing a Navigation Page Layout 1666 1667This example demonstrates the layout of a navigation page, including the title bar (**title**), menu bar (**menus**), content area, and toolbar (**toolbarConfiguration**). 1668 1669```ts 1670// xxx.ets 1671class A { 1672 text: string = '' 1673 num: number = 0 1674} 1675 1676@Entry 1677@Component 1678struct NavigationExample { 1679 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1680 @State currentIndex: number = 0 1681 1682 @Builder 1683 NavigationTitle() { 1684 Column() { 1685 Text('Title') 1686 .fontColor('#182431') 1687 .fontSize(30) 1688 .lineHeight(41) 1689 .fontWeight(700) 1690 Text('subtitle') 1691 .fontColor('#182431') 1692 .fontSize(14) 1693 .lineHeight(19) 1694 .opacity(0.4) 1695 .margin({ top: 2, bottom: 20 }) 1696 }.alignItems(HorizontalAlign.Start) 1697 } 1698 1699 @Builder 1700 NavigationMenus() { 1701 Row() { 1702 Image('resources/base/media/ic_public_add.svg') 1703 .width(24) 1704 .height(24) 1705 Image('resources/base/media/ic_public_add.svg') 1706 .width(24) 1707 .height(24) 1708 .margin({ left: 24 }) 1709 Image('common/ic_public_more.svg') 1710 .width(24) 1711 .height(24) 1712 .margin({ left: 24 }) 1713 } 1714 } 1715 1716 build() { 1717 Column() { 1718 Navigation() { 1719 TextInput({ placeholder: 'search...' }) 1720 .width('90%') 1721 .height(40) 1722 .backgroundColor('#FFFFFF') 1723 .margin({ top: 8 }) 1724 1725 List({ space: 12, initialIndex: 0 }) { 1726 ForEach(this.arr, (item: number) => { 1727 ListItem() { 1728 Text('' + item) 1729 .width('90%') 1730 .height(72) 1731 .backgroundColor('#FFFFFF') 1732 .borderRadius(24) 1733 .fontSize(16) 1734 .fontWeight(500) 1735 .textAlign(TextAlign.Center) 1736 } 1737 }, (item: number) => item.toString()) 1738 } 1739 .height(324) 1740 .width('100%') 1741 .margin({ top: 12, left: '10%' }) 1742 } 1743 .title(this.NavigationTitle) 1744 .menus(this.NavigationMenus) 1745 .titleMode(NavigationTitleMode.Full) 1746 .toolbarConfiguration([ 1747 { 1748 value: $r("app.string.navigation_toolbar_add"), 1749 icon: $r("app.media.ic_public_highlightsed") 1750 }, 1751 { 1752 value: $r("app.string.navigation_toolbar_app"), 1753 icon: $r("app.media.ic_public_highlights") 1754 }, 1755 { 1756 value: $r("app.string.navigation_toolbar_collect"), 1757 icon: $r("app.media.ic_public_highlights") 1758 } 1759 ]) 1760 .hideTitleBar(false) 1761 .hideToolBar(false) 1762 .onTitleModeChange((titleModel: NavigationTitleMode) => { 1763 console.info('titleMode' + titleModel) 1764 }) 1765 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1766 } 1767} 1768``` 1769 1770 1771 1772 1773 1774### Example 2: Using NavPathStack Methods 1775 1776This example demonstrates the use of methods in **NavPathStack** and route interception. 1777 1778```ts 1779// Index.ets 1780@Entry 1781@Component 1782struct NavigationExample { 1783 pageInfos: NavPathStack = new NavPathStack() 1784 isUseInterception: boolean = false; 1785 1786 registerInterception() { 1787 this.pageInfos.setInterception({ 1788 // Interception before page redirection, allowing for stack operations. The setting takes effect in the current redirection. 1789 willShow: (from: NavDestinationContext | "navBar", to: NavDestinationContext | "navBar", 1790 operation: NavigationOperation, animated: boolean) => { 1791 if (!this.isUseInterception) { 1792 return; 1793 } 1794 if (typeof to === "string") { 1795 console.log("target page is navigation home"); 1796 return; 1797 } 1798 // Redirect the target page from pageTwo to pageOne. 1799 let target: NavDestinationContext = to as NavDestinationContext; 1800 if (target.pathInfo.name === 'pageTwo') { 1801 target.pathStack.pop(); 1802 target.pathStack.pushPathByName('pageOne', null); 1803 } 1804 }, 1805 // Callback invoked after the page is navigated. Stack operations in this callback are effective in the next navigation. 1806 didShow: (from: NavDestinationContext | "navBar", to: NavDestinationContext | "navBar", 1807 operation: NavigationOperation, isAnimated: boolean) => { 1808 if (!this.isUseInterception) { 1809 return; 1810 } 1811 if (typeof from === "string") { 1812 console.log("current transition is from navigation home"); 1813 } else { 1814 console.log(`current transition is from ${(from as NavDestinationContext).pathInfo.name}`) 1815 } 1816 if (typeof to === "string") { 1817 console.log("current transition to is navBar"); 1818 } else { 1819 console.log(`current transition is to ${(to as NavDestinationContext).pathInfo.name}`); 1820 } 1821 }, 1822 // Callback invoked when the display mode of the Navigation component switches between single-column and dual-column. 1823 modeChange: (mode: NavigationMode) => { 1824 if (!this.isUseInterception) { 1825 return; 1826 } 1827 console.log(`current navigation mode is ${mode}`); 1828 } 1829 }) 1830 } 1831 1832 build() { 1833 Navigation(this.pageInfos) { 1834 Column() { 1835 Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }) 1836 .width('80%') 1837 .height(40) 1838 .margin(20) 1839 .onClick(() => { 1840 this.pageInfos.pushPath({ name:'pageOne'}) // Push the navigation destination page specified by name to the navigation stack. 1841 }) 1842 Button('use interception', { stateEffect: true, type: ButtonType.Capsule }) 1843 .width('80%') 1844 .height(40) 1845 .margin(20) 1846 .onClick(() => { 1847 this.isUseInterception = !this.isUseInterception; 1848 if (this.isUseInterception) { 1849 this.registerInterception(); 1850 } else { 1851 this.pageInfos.setInterception(undefined); 1852 } 1853 }) 1854 } 1855 }.title('NavIndex') 1856 } 1857} 1858``` 1859```ts 1860// PageOne.ets 1861class TmpClass { 1862 count: number = 10 1863} 1864 1865@Builder 1866export function PageOneBuilder(name: string, param: Object) { 1867 PageOne() 1868} 1869 1870@Component 1871export struct PageOne { 1872 pageInfos: NavPathStack = new NavPathStack() 1873 1874 build() { 1875 NavDestination() { 1876 Column() { 1877 Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }) 1878 .width('80%') 1879 .height(40) 1880 .margin(20) 1881 .onClick(() => { 1882 let tmp = new TmpClass() 1883 this.pageInfos.pushPathByName('pageTwo', tmp) // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. 1884 }) 1885 Button('singletonLaunchMode', { stateEffect: true, type: ButtonType.Capsule }) 1886 .width('80%') 1887 .height(40) 1888 .margin(20) 1889 .onClick(() => { 1890 this.pageInfos.pushPath({ name: 'pageOne' }, 1891 { launchMode: LaunchMode.MOVE_TO_TOP_SINGLETON }) // Search from the bottom to the top of the stack. If the page with the specified name exists, move that page to the top of the stack. 1892 }) 1893 Button('popToname', { stateEffect: true, type: ButtonType.Capsule }) 1894 .width('80%') 1895 .height(40) 1896 .margin(20) 1897 .onClick(() => { 1898 this.pageInfos.popToName('pageTwo') // Pop the first navigation destination page that matches the value of name to the top of the navigation stack. 1899 console.log('popToName' + JSON.stringify(this.pageInfos), 1900 'Return value' + JSON.stringify(this.pageInfos.popToName('pageTwo'))) 1901 }) 1902 Button('popToIndex', { stateEffect: true, type: ButtonType.Capsule }) 1903 .width('80%') 1904 .height(40) 1905 .margin(20) 1906 .onClick(() => { 1907 this.pageInfos.popToIndex(1) // Return the navigation stack to the navigation destination page that matches the value of index. 1908 console.log('popToIndex' + JSON.stringify(this.pageInfos)) 1909 }) 1910 Button('moveToTop', { stateEffect: true, type: ButtonType.Capsule }) 1911 .width('80%') 1912 .height(40) 1913 .margin(20) 1914 .onClick(() => { 1915 this.pageInfos.moveToTop('pageTwo') // Move to the top of the navigation stack the first navigation destination page that matches the value of name. 1916 console.log('moveToTop' + JSON.stringify(this.pageInfos), 1917 'Return value' + JSON.stringify(this.pageInfos.moveToTop('pageTwo'))) 1918 }) 1919 Button('moveIndexToTop', { stateEffect: true, type: ButtonType.Capsule }) 1920 .width('80%') 1921 .height(40) 1922 .margin(20) 1923 .onClick(() => { 1924 this.pageInfos.moveIndexToTop(1) // Move to the top of the navigation stack the navigation destination page that matches the value of index. 1925 console.log('moveIndexToTop' + JSON.stringify(this.pageInfos)) 1926 }) 1927 Button('clear', { stateEffect: true, type: ButtonType.Capsule }) 1928 .width('80%') 1929 .height(40) 1930 .margin(20) 1931 .onClick(() => { 1932 this.pageInfos.clear() // Clear the navigation stack. 1933 }) 1934 Button('get', { stateEffect: true, type: ButtonType.Capsule }) 1935 .width('80%') 1936 .height(40) 1937 .margin(20) 1938 .onClick(() => { 1939 console.log('-------------------') 1940 console.log('Obtained the names of all pages in the navigation stack', JSON.stringify(this.pageInfos.getAllPathName())) 1941 console.log('Obtained the parameter information of the navigation destination page specified by index.', 1942 JSON.stringify(this.pageInfos.getParamByIndex(1))) 1943 console.log('Obtained the parameter information of all the navigation destination pages that match name.', 1944 JSON.stringify(this.pageInfos.getParamByName('pageTwo'))) 1945 console.log('Obtains the indexes of all the navigation destination pages that match name.', 1946 JSON.stringify(this.pageInfos.getIndexByName('pageOne'))) 1947 console.log('Obtained the stack size', JSON.stringify(this.pageInfos.size())) 1948 }) 1949 }.width('100%').height('100%') 1950 }.title('pageOne') 1951 .onBackPressed(() => { 1952 const popDestinationInfo = this.pageInfos.pop() // Pop the top element out of the navigation stack. 1953 console.log('pop' + 'Return value' + JSON.stringify(popDestinationInfo)) 1954 return true 1955 }).onReady((context: NavDestinationContext) => { 1956 this.pageInfos = context.pathStack 1957 }) 1958 } 1959} 1960``` 1961```ts 1962// PageTwo.ets 1963@Builder 1964export function PageTwoBuilder(name: string, param: Object) { 1965 PageTwo() 1966} 1967 1968@Component 1969export struct PageTwo { 1970 pathStack: NavPathStack = new NavPathStack() 1971 private menuItems: Array<NavigationMenuItem> = [ 1972 { 1973 value: "1", 1974 icon: 'resources/base/media/undo.svg', 1975 }, 1976 { 1977 value: "2", 1978 icon: 'resources/base/media/redo.svg', 1979 isEnabled: false, 1980 }, 1981 { 1982 value: "3", 1983 icon: 'resources/base/media/ic_public_ok.svg', 1984 isEnabled: true, 1985 } 1986 ] 1987 1988 build() { 1989 NavDestination() { 1990 Column() { 1991 Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }) 1992 .width('80%') 1993 .height(40) 1994 .margin(20) 1995 .onClick(() => { 1996 this.pathStack.pushPathByName('pageOne', null) 1997 }) 1998 }.width('100%').height('100%') 1999 }.title('pageTwo') 2000 .menus(this.menuItems) 2001 .onBackPressed(() => { 2002 this.pathStack.pop() 2003 return true 2004 }) 2005 .onReady((context: NavDestinationContext) => { 2006 this.pathStack = context.pathStack; 2007 console.log("current page config info is " + JSON.stringify(context.getConfigInRouteMap())) 2008 }) 2009 } 2010} 2011``` 2012 2013```json 2014// Configure {"routerMap": "$profile:route_map"} in the project configuration file module.json5. 2015// route_map.json 2016{ 2017 "routerMap": [ 2018 { 2019 "name": "pageOne", 2020 "pageSourceFile": "src/main/ets/pages/PageOne.ets", 2021 "buildFunction": "PageOneBuilder", 2022 "data": { 2023 "description": "this is pageOne" 2024 } 2025 }, 2026 { 2027 "name": "pageTwo", 2028 "pageSourceFile": "src/main/ets/pages/PageTwo.ets", 2029 "buildFunction": "PageTwoBuilder" 2030 } 2031 ] 2032} 2033``` 2034 2035 2036### Example 3: Setting an Interactive Transition Animation 2037 2038This sample demonstrates how to set a custom transition animation and an interactive transition animation for each **NavDestination** page. 2039 2040<!--code_no_check--> 2041```ts 2042// Index.ets 2043import { CustomTransition, AnimateCallback } from './CustomNavigationUtils' 2044 2045@Entry 2046@Component 2047struct NavigationExample { 2048 pageInfos: NavPathStack = new NavPathStack(); 2049 2050 aboutToAppear() { 2051 if (this.pageInfos === undefined) { 2052 this.pageInfos = new NavPathStack(); 2053 } 2054 this.pageInfos.pushPath({ name: 'pageOne', param: CustomTransition.getInstance().getAnimationId() }); 2055 } 2056 2057 build() { 2058 Navigation(this.pageInfos) { 2059 } 2060 .title('NavIndex') 2061 .hideNavBar(true) 2062 .customNavContentTransition((from: NavContentInfo, to: NavContentInfo, operation: NavigationOperation) => { 2063 if (from.mode == NavDestinationMode.DIALOG || to.mode == NavDestinationMode.DIALOG) { 2064 return undefined; 2065 } 2066 2067 // No custom animation for the home page 2068 if (from.index === -1 || to.index === -1) { 2069 return undefined; 2070 } 2071 2072 CustomTransition.getInstance().operation = operation; 2073 if (CustomTransition.getInstance().interactive) { 2074 let customAnimation: NavigationAnimatedTransition = { 2075 onTransitionEnd: (isSuccess: boolean) => { 2076 console.log("===== current transition is " + isSuccess); 2077 CustomTransition.getInstance().recoverState(); 2078 CustomTransition.getInstance().proxy = undefined; 2079 }, 2080 transition: (transitionProxy: NavigationTransitionProxy) => { 2081 CustomTransition.getInstance().proxy = transitionProxy; 2082 let targetIndex: string | undefined = operation == NavigationOperation.PUSH ? 2083 (to.navDestinationId) : (from.navDestinationId); 2084 if (targetIndex) { 2085 CustomTransition.getInstance().fireInteractiveAnimation(targetIndex, operation); 2086 } 2087 }, 2088 isInteractive: CustomTransition.getInstance().interactive 2089 } 2090 return customAnimation; 2091 } 2092 let customAnimation: NavigationAnimatedTransition = { 2093 onTransitionEnd: (isSuccess: boolean) => { 2094 console.log(`current transition result is ${isSuccess}`) 2095 }, 2096 timeout: 7000, 2097 // When the transition starts, the system calls this method and passes in the transition context proxy object. 2098 transition: (transitionProxy: NavigationTransitionProxy) => { 2099 if (!from.navDestinationId || !to.navDestinationId) { 2100 return; 2101 } 2102 // Obtain the corresponding transition animation callback from the CustomTransition class based on the sequence of subpages. 2103 let fromParam: AnimateCallback = CustomTransition.getInstance().getAnimateParam(from.navDestinationId); 2104 let toParam: AnimateCallback = CustomTransition.getInstance().getAnimateParam(to.navDestinationId); 2105 if (operation == NavigationOperation.PUSH) { 2106 if (toParam.start) { 2107 toParam.start(true, false); 2108 } 2109 animateTo({ 2110 duration: 500, onFinish: () => { 2111 transitionProxy.finishTransition(); 2112 } 2113 }, () => { 2114 if (toParam.finish) { 2115 toParam.finish(true, false); 2116 } 2117 }) 2118 } else { 2119 if (fromParam.start) { 2120 fromParam.start(true, true); 2121 } 2122 animateTo({ 2123 duration: 500, onFinish: () => { 2124 transitionProxy.finishTransition(); 2125 } 2126 }, () => { 2127 if (fromParam.finish) { 2128 fromParam.finish(true, true); 2129 } 2130 }) 2131 } 2132 } 2133 }; 2134 return customAnimation; 2135 }) 2136 } 2137} 2138``` 2139 2140<!--code_no_check--> 2141```ts 2142// PageOne.ets 2143import { CustomTransition } from './CustomNavigationUtils'; 2144 2145@Builder 2146export function PageOneBuilder(name: string, param: Object) { 2147 PageOne() 2148} 2149 2150@Component 2151export struct PageOne { 2152 pageInfos: NavPathStack = new NavPathStack(); 2153 @State translateX: string = '0'; 2154 pageId: string = ''; 2155 rectWidth: number = 0; 2156 interactive: boolean = false; 2157 2158 registerCallback() { 2159 CustomTransition.getInstance().registerNavParam(this.pageId, (isPush: boolean, isExit: boolean) => { 2160 if (isPush) { 2161 this.translateX = '100%'; 2162 } else { 2163 this.translateX = '0'; 2164 } 2165 }, (isPush: boolean, isExit: boolean) => { 2166 if (isPush) { 2167 this.translateX = '0'; 2168 } else { 2169 this.translateX = '100%'; 2170 } 2171 }, (isPush: boolean, isExit: boolean) => { 2172 this.translateX = '0'; 2173 }, (operation: NavigationOperation) => { 2174 if (operation == NavigationOperation.PUSH) { 2175 this.translateX = '100%'; 2176 animateTo({ 2177 duration: 1000, 2178 onFinish: () => { 2179 this.translateX = '0'; 2180 } 2181 }, () => { 2182 this.translateX = '0'; 2183 }) 2184 } else { 2185 this.translateX = '0'; 2186 animateTo({ 2187 duration: 1000, 2188 onFinish: () => { 2189 this.translateX = '0'; 2190 } 2191 }, () => { 2192 this.translateX = '100%'; 2193 }) 2194 } 2195 }, 200); 2196 } 2197 2198 build() { 2199 NavDestination() { 2200 Column() { 2201 Button(`setInteractive`) 2202 .onClick(() => { 2203 CustomTransition.getInstance().interactive = !CustomTransition.getInstance().interactive; 2204 this.interactive = CustomTransition.getInstance().interactive; 2205 }) 2206 2207 Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }) 2208 .width('80%') 2209 .height(40) 2210 .margin(20) 2211 .onClick(() => { 2212 // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. 2213 this.pageInfos.pushDestinationByName('pageTwo', CustomTransition.getInstance().getAnimationId()); 2214 }) 2215 } 2216 .size({ width: '100%', height: '100%' }) 2217 } 2218 .title('pageOne') 2219 .onDisAppear(() => { 2220 CustomTransition.getInstance().unRegisterNavParam(this.pageId); 2221 }) 2222 .onReady((context: NavDestinationContext) => { 2223 this.pageInfos = context.pathStack; 2224 if (context.navDestinationId) { 2225 this.pageId = context.navDestinationId; 2226 this.registerCallback(); 2227 } 2228 }) 2229 .translate({ x: this.translateX }) 2230 .backgroundColor('#F1F3F5') 2231 .gesture(PanGesture() 2232 .onActionStart((event: GestureEvent) => { 2233 this.rectWidth = event.target.area.width as number; 2234 if (event.offsetX < 0) { 2235 this.pageInfos.pushPath({ name: 'pageTwo', param: CustomTransition.getInstance().getAnimationId() }); 2236 } else { 2237 this.pageInfos.pop(); 2238 } 2239 }) 2240 .onActionUpdate((event: GestureEvent) => { 2241 let rate = event.fingerList[0].localX / this.rectWidth; 2242 CustomTransition.getInstance().updateProgress(rate); 2243 }) 2244 .onActionEnd((event: GestureEvent) => { 2245 let rate: number = event.fingerList[0].localX / this.rectWidth; 2246 CustomTransition.getInstance().finishInteractiveAnimation(rate); 2247 })) 2248 } 2249} 2250``` 2251<!--code_no_check--> 2252```ts 2253// PageTwo.ets 2254import { CustomTransition } from './CustomNavigationUtils' 2255 2256@Builder 2257export function PageTwoBuilder(name: string, param: Object) { 2258 PageTwo({ param: param as number }) 2259} 2260 2261@Component 2262export struct PageTwo { 2263 pageInfos: NavPathStack = new NavPathStack(); 2264 @State translateX: string = '0'; 2265 pageId: string = ''; 2266 rectWidth: number = 0; 2267 param: number = 0; 2268 2269 registerCallback() { 2270 CustomTransition.getInstance().registerNavParam(this.pageId, (isPush: boolean, isExit: boolean) => { 2271 if (isPush) { 2272 this.translateX = '100%' 2273 } else { 2274 this.translateX = '0'; 2275 } 2276 }, (isPush: boolean, isExit: boolean) => { 2277 if (isPush) { 2278 this.translateX = '0'; 2279 } else { 2280 this.translateX = '100%' 2281 } 2282 }, (isPush: boolean, isExit: boolean) => { 2283 this.translateX = '0'; 2284 }, (operation: NavigationOperation) => { 2285 if (operation == NavigationOperation.PUSH) { 2286 this.translateX = '100%'; 2287 animateTo({ 2288 duration: 500, onFinish: () => { 2289 this.translateX = '0'; 2290 } 2291 }, () => { 2292 this.translateX = '0' 2293 }) 2294 } else { 2295 this.translateX = '0'; 2296 animateTo({ 2297 duration: 500, onFinish: () => { 2298 this.translateX = "0" 2299 } 2300 }, () => { 2301 this.translateX = '100%'; 2302 }) 2303 } 2304 }, 2000) 2305 } 2306 2307 build() { 2308 NavDestination() { 2309 Column() { 2310 Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }) 2311 .width('80%') 2312 .height(40) 2313 .margin(20) 2314 .onClick(() => { 2315 // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. 2316 this.pageInfos.pushPath({ name: 'pageOne', param: CustomTransition.getInstance().getAnimationId() }) 2317 }) 2318 } 2319 .size({ width: '100%', height: '100%' }) 2320 } 2321 .title('pageTwo') 2322 .gesture(PanGesture() 2323 .onActionStart((event: GestureEvent) => { 2324 this.rectWidth = event.target.area.width as number; 2325 if (event.offsetX < 0) { 2326 this.pageInfos.pushPath({ name: 'pageOne', param: CustomTransition.getInstance().getAnimationId() }); 2327 } else { 2328 this.pageInfos.pop(); 2329 } 2330 }) 2331 .onActionUpdate((event: GestureEvent) => { 2332 let rate = event.fingerList[0].localX / this.rectWidth; 2333 CustomTransition.getInstance().updateProgress(rate); 2334 }) 2335 .onActionEnd((event: GestureEvent) => { 2336 let rate = event.fingerList[0].localX / this.rectWidth; 2337 CustomTransition.getInstance().finishInteractiveAnimation(rate); 2338 })) 2339 .onAppear(() => { 2340 this.registerCallback(); 2341 }) 2342 .onDisAppear(() => { 2343 CustomTransition.getInstance().unRegisterNavParam(this.pageId); 2344 }) 2345 .onReady((context: NavDestinationContext) => { 2346 this.pageInfos = context.pathStack; 2347 if (context.navDestinationId) { 2348 this.pageId = context.navDestinationId; 2349 this.registerCallback(); 2350 } 2351 }) 2352 .translate({ x: this.translateX }) 2353 .backgroundColor(Color.Yellow) 2354 } 2355} 2356``` 2357```ts 2358// CustomNavigationUtils.ets 2359// Custom API to save the transition animation callback and parameters related to a page. 2360export interface AnimateCallback { 2361 finish: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined; 2362 start: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined; 2363 onFinish: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined; 2364 interactive: ((operation: NavigationOperation) => void | undefined) | undefined; 2365 timeout: (number | undefined) | undefined; 2366} 2367 2368const customTransitionMap: Map<string, AnimateCallback> = new Map(); 2369 2370export class CustomTransition { 2371 static delegate = new CustomTransition(); 2372 interactive: boolean = false; 2373 proxy: NavigationTransitionProxy | undefined = undefined; 2374 private animationId: number = 0; 2375 operation: NavigationOperation = NavigationOperation.PUSH 2376 2377 static getInstance() { 2378 return CustomTransition.delegate; 2379 } 2380 2381 /* Register animation callbacks for a page. 2382 * name: unique ID of the target page 2383 * startCallback: used to set the page state at the start of the animation. 2384 * endCallback: used to set the page state at the end of the animation. 2385 * onFinish: used to perform other operations after the animation ends. 2386 * interactiveCallback: used to handle the interactive part of the transition. 2387 * timeout: timeout for ending the transition. 2388 */ 2389 registerNavParam(name: string, startCallback: (operation: boolean, isExit: boolean) => void, 2390 endCallback: (operation: boolean, isExit: boolean) => void, 2391 onFinish: (operation: boolean, isExit: boolean) => void, 2392 interactiveCallback: (operation: NavigationOperation) => void, 2393 timeout: number): void { 2394 if (customTransitionMap.has(name)) { 2395 let param = customTransitionMap.get(name); 2396 if (param != undefined) { 2397 param.start = startCallback; 2398 param.finish = endCallback; 2399 param.timeout = timeout; 2400 param.onFinish = onFinish; 2401 param.interactive = interactiveCallback; 2402 return; 2403 } 2404 } 2405 let params: AnimateCallback = { 2406 timeout: timeout, 2407 start: startCallback, 2408 finish: endCallback, 2409 onFinish: onFinish, 2410 interactive: interactiveCallback 2411 }; 2412 customTransitionMap.set(name, params); 2413 } 2414 2415 getAnimationId() { 2416 return Date.now(); 2417 } 2418 2419 unRegisterNavParam(name: string): void { 2420 customTransitionMap.delete(name); 2421 } 2422 2423 fireInteractiveAnimation(id: string, operation: NavigationOperation) { 2424 let animation = customTransitionMap.get(id)?.interactive; 2425 if (!animation) { 2426 return; 2427 } 2428 animation(operation); 2429 } 2430 2431 updateProgress(progress: number) { 2432 if (!this.proxy?.updateTransition) { 2433 return; 2434 } 2435 progress = this.operation == NavigationOperation.PUSH ? 1 - progress : progress; 2436 this.proxy?.updateTransition(progress); 2437 } 2438 2439 cancelTransition() { 2440 if (this.proxy?.cancelTransition) { 2441 this.proxy.cancelTransition(); 2442 } 2443 } 2444 2445 recoverState() { 2446 if (!this.proxy?.from.navDestinationId || !this.proxy?.to.navDestinationId) { 2447 return; 2448 } 2449 let fromParam = customTransitionMap.get(this.proxy.from.navDestinationId); 2450 if (fromParam?.onFinish) { 2451 fromParam.onFinish(false, false); 2452 } 2453 let toParam = customTransitionMap.get(this.proxy?.to.navDestinationId); 2454 if (toParam?.onFinish) { 2455 toParam.onFinish(true, true); 2456 } 2457 } 2458 2459 finishTransition() { 2460 this.proxy?.finishTransition(); 2461 } 2462 2463 finishInteractiveAnimation(rate: number) { 2464 if (this.operation == NavigationOperation.PUSH) { 2465 if (rate > 0.5) { 2466 if (this.proxy?.cancelTransition) { 2467 this.proxy.cancelTransition(); 2468 } 2469 } else { 2470 this.proxy?.finishTransition(); 2471 } 2472 } else { 2473 if (rate > 0.5) { 2474 this.proxy?.finishTransition(); 2475 } else { 2476 if (this.proxy?.cancelTransition) { 2477 this.proxy.cancelTransition(); 2478 } 2479 } 2480 } 2481 } 2482 2483 getAnimateParam(name: string): AnimateCallback { 2484 let result: AnimateCallback = { 2485 start: customTransitionMap.get(name)?.start, 2486 finish: customTransitionMap.get(name)?.finish, 2487 timeout: customTransitionMap.get(name)?.timeout, 2488 onFinish: customTransitionMap.get(name)?.onFinish, 2489 interactive: customTransitionMap.get(name)?.interactive, 2490 }; 2491 return result; 2492 } 2493} 2494``` 2495```json 2496// Configure {"routerMap": "$profile:route_map"} in the project configuration file module.json5. 2497// route_map.json 2498{ 2499 "routerMap": [ 2500 { 2501 "name": "pageOne", 2502 "pageSourceFile": "src/main/ets/pages/PageOne.ets", 2503 "buildFunction": "PageOneBuilder", 2504 "data": { 2505 "description": "this is pageOne" 2506 } 2507 }, 2508 { 2509 "name": "pageTwo", 2510 "pageSourceFile": "src/main/ets/pages/PageTwo.ets", 2511 "buildFunction": "PageTwoBuilder" 2512 } 2513 ] 2514} 2515``` 2516 2517 2518### Example 4: Implementing a Navigation Component with Parameter Returning 2519 2520This example demonstrates how to use the APIs in **NavPathStack** to pass parameters back to the previous page. 2521 2522```ts 2523// Index.ets 2524@Entry 2525@Component 2526struct NavigationExample { 2527 pageInfo: NavPathStack = new NavPathStack() 2528 2529 build() { 2530 Navigation(this.pageInfo) { 2531 Column() { 2532 Button('StartTest', { stateEffect: true, type: ButtonType.Capsule }) 2533 .width('80%') 2534 .height(40) 2535 .margin(20) 2536 .onClick(() => { 2537 this.pageInfo.pushPath({ name: 'pageOne' }); // Push the navigation destination page specified by name to the navigation stack. 2538 }) 2539 } 2540 }.title('NavIndex') 2541 } 2542} 2543``` 2544```ts 2545// PageOne.ets 2546import { BusinessError } from '@kit.BasicServicesKit'; 2547 2548class TmpClass { 2549 count: number = 10 2550} 2551 2552class ParamWithOp { 2553 operation: number = 1 2554 count: number = 10 2555} 2556 2557@Builder 2558export function PageOneBuilder(name: string, param: Object) { 2559 PageOne() 2560} 2561 2562@Component 2563export struct PageOne { 2564 pageInfo: NavPathStack = new NavPathStack(); 2565 @State message: string = 'Hello World' 2566 2567 build() { 2568 NavDestination() { 2569 Column() { 2570 Text(this.message) 2571 .width('80%') 2572 .height(50) 2573 .margin(10) 2574 2575 Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }) 2576 .width('80%') 2577 .height(40) 2578 .margin(10) 2579 .onClick(() => { 2580 this.pageInfo.pushPath({ 2581 name: 'pageTwo', param: new ParamWithOp(), onPop: (popInfo: PopInfo) => { 2582 this.message = 2583 '[pushPath]last page is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result); 2584 } 2585 }); // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. Use the onPop callback to receive the page processing result. 2586 }) 2587 2588 Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }) 2589 .width('80%') 2590 .height(40) 2591 .margin(10) 2592 .onClick(() => { 2593 let tmp = new TmpClass() 2594 this.pageInfo.pushPathByName('pageTwo', tmp, (popInfo) => { 2595 this.message = 2596 '[pushPathByName]last page is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result); 2597 }); // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. Use the onPop callback to receive the page processing result. 2598 }) 2599 2600 Button('pushDestination', { stateEffect: true, type: ButtonType.Capsule }) 2601 .width('80%') 2602 .height(40) 2603 .margin(10) 2604 .onClick(() => { 2605 let tmp = new TmpClass() 2606 // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. Use the onPop callback to receive the page processing result. 2607 this.pageInfo.pushDestination({ 2608 name: 'pageTwo', param: new ParamWithOp(), onPop: (popInfo: PopInfo) => { 2609 this.message = 2610 '[pushDestination]last page is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result); 2611 } 2612 }).catch((error: BusinessError) => { 2613 console.error(`[pushDestination]failed, error code = ${error.code}, error.message = ${error.message}.`); 2614 }).then(() => { 2615 console.error('[pushDestination]success.'); 2616 }); 2617 }) 2618 2619 Button('pushDestinationByName', { stateEffect: true, type: ButtonType.Capsule }) 2620 .width('80%') 2621 .height(40) 2622 .margin(10) 2623 .onClick(() => { 2624 let tmp = new TmpClass() 2625 // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. Use the onPop callback to receive the page processing result. 2626 this.pageInfo.pushDestinationByName('pageTwo', tmp, (popInfo) => { 2627 this.message = '[pushDestinationByName]last page is: ' + popInfo.info.name + ', result: ' + 2628 JSON.stringify(popInfo.result); 2629 }).catch((error: BusinessError) => { 2630 console.error(`[pushDestinationByName]failed, error code = ${error.code}, error.message = ${error.message}.`); 2631 }).then(() => { 2632 console.error('[pushDestinationByName]success.'); 2633 }); 2634 }) 2635 2636 Button('pushPathWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }) 2637 .width('80%') 2638 .height(40) 2639 .margin(10) 2640 .onClick(() => { 2641 this.pageInfo.pushPath({ name: 'pageTwo', param: new ParamWithOp() }); // Push the navigation destination page specified by name to the navigation stack. 2642 }) 2643 2644 Button('pushPathByNameWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }) 2645 .width('80%') 2646 .height(40) 2647 .margin(10) 2648 .onClick(() => { 2649 let tmp = new TmpClass() 2650 this.pageInfo.pushPathByName('pageTwo', tmp); // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. 2651 }) 2652 2653 Button('pushDestinationWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }) 2654 .width('80%') 2655 .height(40) 2656 .margin(10) 2657 .onClick(() => { 2658 let tmp = new TmpClass() 2659 // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. Use the onPop callback to receive the page processing result. 2660 this.pageInfo.pushDestination({ name: 'pageTwo', param: new ParamWithOp() }) 2661 .catch((error: BusinessError) => { 2662 console.error(`[pushDestinationWithoutOnPop]failed, error code = ${error.code}, error.message = ${error.message}.`); 2663 }).then(() => { 2664 console.error('[pushDestinationWithoutOnPop]success.'); 2665 }); 2666 }) 2667 2668 Button('pushDestinationByNameWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }) 2669 .width('80%') 2670 .height(40) 2671 .margin(10) 2672 .onClick(() => { 2673 let tmp = new TmpClass() 2674 // Push the navigation destination page specified by name, with the data specified by param, to the navigation stack. 2675 this.pageInfo.pushDestinationByName('pageTwo', tmp) 2676 .catch((error: BusinessError) => { 2677 console.error(`[pushDestinationByNameWithoutOnPop]failed, error code = ${error.code}, error.message = ${error.message}.`); 2678 }).then(() => { 2679 console.error('[pushDestinationByNameWithoutOnPop]success.'); 2680 }); 2681 }) 2682 2683 Button('clear', { stateEffect: true, type: ButtonType.Capsule }) 2684 .width('80%') 2685 .height(40) 2686 .margin(10) 2687 .onClick(() => { 2688 this.pageInfo.clear(); // Clear the navigation stack. 2689 }) 2690 }.width('100%').height('100%') 2691 }.title('pageOne') 2692 .onBackPressed(() => { 2693 this.pageInfo.pop({ number: 1 }) // Pop the top element out of the navigation stack. 2694 return true 2695 }).onReady((context: NavDestinationContext) => { 2696 this.pageInfo = context.pathStack; 2697 }) 2698 } 2699} 2700``` 2701```ts 2702// PageTwo.ets 2703class resultClass { 2704 constructor(count: number) { 2705 this.count = count; 2706 } 2707 2708 count: number = 10 2709} 2710 2711@Builder 2712export function PageTwoBuilder() { 2713 PageTwo() 2714} 2715 2716@Component 2717export struct PageTwo { 2718 pathStack: NavPathStack = new NavPathStack() 2719 2720 build() { 2721 NavDestination() { 2722 Column() { 2723 Button('pop', { stateEffect: true, type: ButtonType.Capsule }) 2724 .width('80%') 2725 .height(40) 2726 .margin(20) 2727 .onClick(() => { 2728 this.pathStack.pop(new resultClass(1)); // Return to the previous page and pass in the processing result to the onPop callback of push. 2729 }) 2730 2731 Button('popToName', { stateEffect: true, type: ButtonType.Capsule }) 2732 .width('80%') 2733 .height(40) 2734 .margin(20) 2735 .onClick(() => { 2736 this.pathStack.popToName('pageOne', 2737 new resultClass(11)); // Move the first navigation destination page that matches name to the top of the navigation stack, and pass in the processing result to the onPop callback of push. 2738 }) 2739 2740 Button('popToIndex', { stateEffect: true, type: ButtonType.Capsule }) 2741 .width('80%') 2742 .height(40) 2743 .margin(20) 2744 .onClick(() => { 2745 this.pathStack.popToIndex(0, new resultClass(111)); // Move the navigation destination page specified by index to the top of the navigation stack, and pass in the processing result to the onPop callback of push. 2746 }) 2747 2748 Button('popWithoutResult', { stateEffect: true, type: ButtonType.Capsule }) 2749 .width('80%') 2750 .height(40) 2751 .margin(20) 2752 .onClick(() => { 2753 this.pathStack.pop(); 2754 }) 2755 2756 Button('popToNameWithoutResult', { stateEffect: true, type: ButtonType.Capsule }) 2757 .width('80%') 2758 .height(40) 2759 .margin(20) 2760 .onClick(() => { 2761 this.pathStack.popToName('pageOne'); 2762 }) 2763 2764 Button('popToIndexWithoutResult', { stateEffect: true, type: ButtonType.Capsule }) 2765 .width('80%') 2766 .height(40) 2767 .margin(20) 2768 .onClick(() => { 2769 this.pathStack.popToIndex(0); 2770 }) 2771 }.width('100%').height('100%') 2772 }.title('pageTwo') 2773 .onBackPressed(() => { 2774 this.pathStack.pop(new resultClass(0)); // Return to the previous page and pass in the processing result to the onPop callback of push. 2775 return true; 2776 }).onReady((context: NavDestinationContext) => { 2777 this.pathStack = context.pathStack 2778 }) 2779 } 2780} 2781``` 2782```json 2783// Configure {"routerMap": "$profile:route_map"} in the project configuration file module.json5. 2784// route_map.json 2785{ 2786 "routerMap": [ 2787 { 2788 "name": "pageOne", 2789 "pageSourceFile": "src/main/ets/pages/PageOne.ets", 2790 "buildFunction": "PageOneBuilder", 2791 "data": { 2792 "description": "this is pageOne" 2793 } 2794 }, 2795 { 2796 "name": "pageTwo", 2797 "pageSourceFile": "src/main/ets/pages/PageTwo.ets", 2798 "buildFunction": "PageTwoBuilder" 2799 } 2800 ] 2801} 2802``` 2803 2804 2805### Example 5: Setting the Background Color and Blur Effect 2806 2807This example demonstrates how to set the background color and background blur effect for the title bar of the home page in **Navigation**, as well as for the toolbar and the title bars on the **NavDestination** pages. 2808 2809```ts 2810let COLOR1: string = "#80004AAF"; 2811let COLOR2: string = "#802787D9"; 2812let BLUR_STYLE_1: BlurStyle = BlurStyle.BACKGROUND_THIN; 2813let BLUR_STYLE_2: BlurStyle = BlurStyle.BACKGROUND_THICK; 2814 2815@Component 2816struct BackComponent { 2817 build() { 2818 Row() { 2819 Column() { 2820 } 2821 .height('100%') 2822 .backgroundColor("#3D9DB4") 2823 .layoutWeight(9) 2824 2825 Column() { 2826 } 2827 .height('100%') 2828 .backgroundColor("#17A98D") 2829 .layoutWeight(9) 2830 2831 Column() { 2832 } 2833 .height('100%') 2834 .backgroundColor("#FFC000") 2835 .layoutWeight(9) 2836 } 2837 .height('100%') 2838 .width('100%') 2839 } 2840} 2841 2842@Component 2843struct ColorAndBlur { 2844 @State useColor1: boolean = true; 2845 @State useBlur1: boolean = true; 2846 2847 build() { 2848 NavDestination() { 2849 Stack({ alignContent: Alignment.Center }) { 2850 BackComponent() 2851 .width('100%') 2852 .height('100%') 2853 Column() { 2854 Stack({ alignContent: Alignment.Center }) { 2855 Button("switch color") 2856 .onClick(() => { 2857 this.useColor1 = !this.useColor1; 2858 }) 2859 } 2860 .width('100%') 2861 .layoutWeight(1) 2862 2863 Stack({ alignContent: Alignment.Center }) { 2864 Button("switch blur") 2865 .onClick(() => { 2866 this.useBlur1 = !this.useBlur1; 2867 }) 2868 } 2869 .width('100%') 2870 .layoutWeight(1) 2871 } 2872 .width('100%') 2873 .height('100%') 2874 }.width('100%') 2875 .height('100%') 2876 } 2877 .width('100%') 2878 .height('100%') 2879 // You can set the background color and background blur style of the title bar. 2880 .title("switch titlebar color and blur", { 2881 backgroundColor: this.useColor1 ? COLOR1 : COLOR2, 2882 backgroundBlurStyle: this.useBlur1 ? BLUR_STYLE_1 : BLUR_STYLE_2, 2883 barStyle: BarStyle.STACK 2884 }) 2885 } 2886} 2887 2888@Entry 2889@Component 2890struct Index { 2891 private stack: NavPathStack = new NavPathStack(); 2892 @State useColor1: boolean = true; 2893 @State useBlur1: boolean = true; 2894 2895 @Builder 2896 PageBuilder(name: string) { 2897 ColorAndBlur() 2898 } 2899 2900 build() { 2901 Navigation(this.stack) { 2902 Stack({ alignContent: Alignment.Center }) { 2903 BackComponent() 2904 .width('100%') 2905 .height('100%') 2906 Column() { 2907 Stack({ alignContent: Alignment.Center }) { 2908 Button("switch color") 2909 .onClick(() => { 2910 this.useColor1 = !this.useColor1; 2911 }) 2912 } 2913 .width('100%') 2914 .layoutWeight(1) 2915 2916 Stack({ alignContent: Alignment.Center }) { 2917 Button("switch blur") 2918 .onClick(() => { 2919 this.useBlur1 = !this.useBlur1; 2920 }) 2921 } 2922 .width('100%') 2923 .layoutWeight(1) 2924 2925 Stack({ alignContent: Alignment.Center }) { 2926 Button("push page") 2927 .onClick(() => { 2928 this.stack.pushPath({ name: "page" }) 2929 }) 2930 } 2931 .width('100%') 2932 .layoutWeight(1) 2933 } 2934 .width('100%') 2935 .height('80%') 2936 }.width('100%') 2937 .height('100%') 2938 } 2939 .width('100%') 2940 .height('100%') 2941 .navDestination(this.PageBuilder) 2942 // You can set the background color and background blur style of the title bar. 2943 .title("NavTitle", { 2944 backgroundColor: this.useColor1 ? COLOR1 : COLOR2, 2945 backgroundBlurStyle: this.useBlur1 ? BLUR_STYLE_1 : BLUR_STYLE_2, 2946 barStyle: BarStyle.STACK 2947 }) 2948 // You can set the background color and background blur style of the toolbar. 2949 .toolbarConfiguration([ 2950 { value: "a" }, 2951 { value: "b" }, 2952 { value: "c" } 2953 ], { 2954 backgroundColor: this.useColor1 ? COLOR1 : COLOR2, 2955 backgroundBlurStyle: this.useBlur1 ? BLUR_STYLE_1 : BLUR_STYLE_2 2956 }) 2957 } 2958} 2959``` 2960 2961 2962### Example 6: Obtaining the Outer Stack for a Nested Navigation Component 2963 2964This example shows how to obtain the parent **NavPathStack** for a nested **Navigation** component. 2965 2966```ts 2967@Entry 2968@Component 2969struct NavigationExample1 { 2970 @State childNavStack: NavPathStack = new NavPathStack(); 2971 2972 build() { 2973 Navigation() { 2974 Stack({ alignContent: Alignment.Center }) { 2975 Navigation(this.childNavStack) { 2976 Button('push Path to parent Navigation', { stateEffect: true, type: ButtonType.Capsule }) 2977 .width('80%') 2978 .height(40) 2979 .margin(20) 2980 .onClick(() => { 2981 // The parent the parent navigation path stack can be obtained. 2982 let parentStack = this.childNavStack.getParent(); 2983 parentStack?.pushPath({ name: "pageOne" }) 2984 }) 2985 } 2986 .clip(true) 2987 .backgroundColor(Color.Orange) 2988 .width('80%') 2989 .height('80%') 2990 .title('ChildNavigation') 2991 } 2992 .width('100%') 2993 .height('100%') 2994 } 2995 .backgroundColor(Color.Green) 2996 .width('100%') 2997 .height('100%') 2998 .title('ParentNavigation') 2999 } 3000} 3001``` 3002```ts 3003// PageOne.ets 3004@Builder 3005export function PageOneBuilder(name: string) { 3006 NavDestination() { 3007 Text("this is " + name) 3008 } 3009 .title(name) 3010} 3011``` 3012```json 3013// Configure {"routerMap": "$profile:route_map"} in the project configuration file module.json5. 3014// route_map.json 3015{ 3016 "routerMap": [ 3017 { 3018 "name": "pageOne", 3019 "pageSourceFile": "src/main/ets/pages/PageOne.ets", 3020 "buildFunction": "PageOneBuilder", 3021 "data": { 3022 "description": "this is pageOne" 3023 } 3024 } 3025 ] 3026} 3027``` 3028 3029 3030### Example 7: Obtaining the Stack Through onReady 3031 3032This example demonstrates the following: 3033 30341. The navigation stack operation can be conducted even when **NavPathStack** is not declared as a state variable. 3035 30362. The **NavDestination** can obtain the corresponding **NavPathInfo** and **NavPathStack** through the **onReady** event. 3037 3038```ts 3039class PageParam { 3040 constructor(num_: number) { 3041 this.num = num_; 3042 } 3043 3044 num: number = 0; 3045} 3046 3047@Builder 3048export function PageOneBuilder(name: string, param: Object) { 3049 PageOne() 3050} 3051 3052@Component 3053struct PageOne { 3054 private stack: NavPathStack | null = null; 3055 private name: string = ""; 3056 private paramNum: number = 0; 3057 3058 build() { 3059 NavDestination() { 3060 Column() { 3061 Text("NavPathInfo: name: " + this.name + ", paramNum: " + this.paramNum) 3062 Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }) 3063 .width('80%') 3064 .height(40) 3065 .margin(20) 3066 .onClick(() => { 3067 if (this.stack) { 3068 let p = new PageParam(this.paramNum + 1); 3069 this.stack.pushPath({ name: "pageOne", param: p }); 3070 } 3071 }) 3072 Button('pop', { stateEffect: true, type: ButtonType.Capsule }) 3073 .width('80%') 3074 .height(40) 3075 .margin(20) 3076 .onClick(() => { 3077 this.stack?.pop() 3078 }) 3079 } 3080 .width('100%') 3081 .height('100%') 3082 } 3083 .title('pageOne') 3084 .onReady((ctx: NavDestinationContext) => { 3085 // The passed NavPathInfo and the owning NavPathStack objects can be obtained for <NavDestination>. 3086 try { 3087 this.name = ctx?.pathInfo?.name; 3088 this.paramNum = (ctx?.pathInfo?.param as PageParam)?.num; 3089 this.stack = ctx.pathStack; 3090 } catch (e) { 3091 console.log(`testTag onReady catch exception: ${JSON.stringify(e)}`) 3092 } 3093 }) 3094 } 3095} 3096 3097@Entry 3098@Component 3099struct NavigationExample2 { 3100 private stack: NavPathStack = new NavPathStack(); 3101 3102 build() { 3103 Navigation(this.stack) { 3104 Stack({ alignContent: Alignment.Center }) { 3105 Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }) 3106 .width('80%') 3107 .height(40) 3108 .margin(20) 3109 .onClick(() => { 3110 let p = new PageParam(1); 3111 this.stack.pushPath({ name: "pageOne", param: p }) 3112 }) 3113 } 3114 .width('100%') 3115 .height('100%') 3116 } 3117 .width('100%') 3118 .height('100%') 3119 .title('Navigation') 3120 } 3121} 3122``` 3123```json 3124// Configure {"routerMap": "$profile:route_map"} in the project configuration file module.json5. 3125// route_map.json 3126{ 3127 "routerMap": [ 3128 { 3129 "name": "pageOne", 3130 "pageSourceFile": "src/main/ets/pages/Index.ets", 3131 "buildFunction": "PageOneBuilder", 3132 "data": { 3133 "description": "this is pageOne" 3134 } 3135 } 3136 ] 3137} 3138``` 3139 3140 3141### Example 8: Using NavDestination Lifecycle Callbacks 3142 3143This example demonstrates the timing of the **NavDestination** component lifecycle callbacks: **onAppear**, **onDisappear**, **onShown**, **onHidden**, **onWillAppear**, **onWillDisappear**, **onWillShow**, and **onWillHide**. 3144 3145```ts 3146@Builder 3147export function PageOneBuilder(name: string, param: Object) { 3148 PageOneComponent() 3149} 3150 3151@Component 3152struct PageOneComponent { 3153 private stack: NavPathStack | null = null; 3154 @State eventStr: string = ""; 3155 3156 build() { 3157 NavDestination() { 3158 Column() { 3159 Text("event: " + this.eventStr) 3160 Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }) 3161 .width('80%') 3162 .height(40) 3163 .margin(20) 3164 .onClick(() => { 3165 if (this.stack) { 3166 this.stack.pushPath({ name: "pageOne" }); 3167 } 3168 }) 3169 Button('pop', { stateEffect: true, type: ButtonType.Capsule }) 3170 .width('80%') 3171 .height(40) 3172 .margin(20) 3173 .onClick(() => { 3174 this.stack?.pop() 3175 }) 3176 } 3177 .width('100%') 3178 .height('100%') 3179 } 3180 .title('pageOne') 3181 .onAppear(() => { 3182 this.eventStr += "<onAppear>"; 3183 }) 3184 .onDisAppear(() => { 3185 this.eventStr += "<onDisAppear>"; 3186 }) 3187 .onShown(() => { 3188 this.eventStr += "<onShown>"; 3189 }) 3190 .onHidden(() => { 3191 this.eventStr += "<onHidden>"; 3192 }) 3193 .onWillAppear(() => { 3194 this.eventStr += "<onWillAppear>"; 3195 }) 3196 .onWillDisappear(() => { 3197 this.eventStr += "<onWillDisappear>"; 3198 }) 3199 .onWillShow(() => { 3200 this.eventStr += "<onWillShow>"; 3201 }) 3202 .onWillHide(() => { 3203 this.eventStr += "<onWillHide>"; 3204 }) 3205 // onReady is called before onAppear. 3206 .onReady((ctx: NavDestinationContext) => { 3207 try { 3208 this.eventStr += "<onReady>"; 3209 this.stack = ctx.pathStack; 3210 } catch (e) { 3211 console.log(`testTag onReady catch exception: ${JSON.stringify(e)}`) 3212 } 3213 }) 3214 } 3215} 3216 3217@Entry 3218@Component 3219struct NavigationExample3 { 3220 private stack: NavPathStack = new NavPathStack(); 3221 3222 build() { 3223 Navigation(this.stack) { 3224 Stack({ alignContent: Alignment.Center }) { 3225 Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }) 3226 .width('80%') 3227 .height(40) 3228 .margin(20) 3229 .onClick(() => { 3230 this.stack.pushPath({ name: "pageOne" }) 3231 }) 3232 } 3233 .width('100%') 3234 .height('100%') 3235 } 3236 .width('100%') 3237 .height('100%') 3238 .title('Navigation') 3239 } 3240} 3241``` 3242```json 3243// Configure {"routerMap": "$profile:route_map"} in the project configuration file module.json5. 3244// route_map.json 3245{ 3246 "routerMap": [ 3247 { 3248 "name": "pageOne", 3249 "pageSourceFile": "src/main/ets/pages/Index.ets", 3250 "buildFunction": "PageOneBuilder", 3251 "data": { 3252 "description": "this is pageOne" 3253 } 3254 } 3255 ] 3256} 3257``` 3258 3259 3260 3261### Example 9: Configuring the Title Bar Stack Layout 3262 3263This example demonstrates the stack layout of the title bar in the **Navigation** component. 3264 3265```ts 3266@Entry 3267@Component 3268struct NavigationExample { 3269 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]; 3270 private scrollerForScroll: Scroller = new Scroller(); 3271 @State barStyle: BarStyle = BarStyle.STANDARD; 3272 3273 build() { 3274 Column() { 3275 Navigation() { 3276 Column() { 3277 Scroll(this.scrollerForScroll) { 3278 Column() { 3279 Image($r('app.media.image_1'))// Set the height to be the same as that of the title bar to observe the STACK effect. 3280 .height(138) 3281 .width('100%') 3282 Button('BarStyle.STANDARD') 3283 .height('50vp') 3284 .onClick(() => { 3285 this.barStyle = BarStyle.STANDARD; 3286 }) 3287 Button('BarStyle.STACK') 3288 .height('50vp') 3289 .margin({ top: 12 }) 3290 .onClick(() => { 3291 this.barStyle = BarStyle.STACK; 3292 }) 3293 3294 ForEach(this.arr, (item: number) => { 3295 ListItem() { 3296 Text('' + item) 3297 .width('100%') 3298 .height(100) 3299 .fontSize(16) 3300 .textAlign(TextAlign.Center) 3301 .borderRadius(10) 3302 .backgroundColor(Color.Orange) 3303 .margin({ top: 12 }) 3304 } 3305 }, (item: string) => item) 3306 } 3307 } 3308 } 3309 .width('100%') 3310 .height('100%') 3311 .backgroundColor(0xDCDCDC) 3312 } 3313 .title( 3314 { 3315 main: 'NavTitle', 3316 sub: 'subtitle' 3317 }, 3318 { 3319 backgroundBlurStyle: BlurStyle.COMPONENT_THICK, 3320 barStyle: this.barStyle, 3321 } 3322 ) 3323 .titleMode(NavigationTitleMode.Free) 3324 .hideTitleBar(false) 3325 }.width('100%').height('100%').backgroundColor('#F1F3F5') 3326 } 3327} 3328``` 3329 3330 3331 3332### Example 10: Defining a Derived Class of NavPathStack 3333 3334This example demonstrates how to define a derived class of **NavPathStack** and the basic usage of the derived class in **Navigation**. 3335 3336```ts 3337class DerivedNavPathStack extends NavPathStack { 3338 // usr defined property 'id' 3339 id: string = "__default__" 3340 3341 // new function in derived class 3342 setId(id: string) { 3343 this.id = id; 3344 } 3345 3346 // new function in derived class 3347 getInfo(): string { 3348 return "this page used Derived NavPathStack, id: " + this.id 3349 } 3350 3351 // overwrite function of NavPathStack 3352 pushPath(info: NavPathInfo, animated?: boolean): void 3353 pushPath(info: NavPathInfo, options?: NavigationOptions): void 3354 pushPath(info: NavPathInfo, secArg?: boolean | NavigationOptions): void { 3355 console.log('[derive-test] reached DerivedNavPathStack\'s pushPath'); 3356 if (typeof secArg === 'boolean') { 3357 super.pushPath(info, secArg); 3358 } else { 3359 super.pushPath(info, secArg); 3360 } 3361 } 3362 3363 // overwrite and overload function of NavPathStack 3364 pop(animated?: boolean | undefined): NavPathInfo | undefined 3365 pop(result: Object, animated?: boolean | undefined): NavPathInfo | undefined 3366 pop(result?: Object, animated?: boolean | undefined): NavPathInfo | undefined { 3367 console.log('[derive-test] reached DerivedNavPathStack\'s pop'); 3368 return super.pop(result, animated); 3369 } 3370 3371 // other function of base class... 3372} 3373 3374class param { 3375 info: string = "__default_param__"; 3376 3377 constructor(info: string) { 3378 this.info = info 3379 } 3380} 3381 3382@Entry 3383@Component 3384struct Index { 3385 derivedStack: DerivedNavPathStack = new DerivedNavPathStack(); 3386 3387 aboutToAppear(): void { 3388 this.derivedStack.setId('origin stack'); 3389 } 3390 3391 @Builder 3392 pageMap(name: string) { 3393 PageOne() 3394 } 3395 3396 build() { 3397 Navigation(this.derivedStack) { 3398 Button('to Page One').margin(20).onClick(() => { 3399 this.derivedStack.pushPath({ 3400 name: 'pageOne', 3401 param: new param('push pageOne in homePage when stack size: ' + this.derivedStack.size()) 3402 }); 3403 }) 3404 }.navDestination(this.pageMap) 3405 .title('Home Page') 3406 } 3407} 3408 3409@Component 3410struct PageOne { 3411 derivedStack: DerivedNavPathStack = new DerivedNavPathStack(); 3412 curStringifyParam: string = "NA"; 3413 3414 build() { 3415 NavDestination() { 3416 Column() { 3417 Text(this.derivedStack.getInfo()) 3418 .margin(10) 3419 .fontSize(25) 3420 .fontWeight(FontWeight.Bold) 3421 .textAlign(TextAlign.Start) 3422 Text('current page param info:') 3423 .margin(10) 3424 .fontSize(25) 3425 .fontWeight(FontWeight.Bold) 3426 .textAlign(TextAlign.Start) 3427 Text(this.curStringifyParam) 3428 .margin(20) 3429 .fontSize(20) 3430 .textAlign(TextAlign.Start) 3431 }.backgroundColor(Color.Pink) 3432 3433 Button('to Page One').margin(20).onClick(() => { 3434 this.derivedStack.pushPath({ 3435 name: 'pageOne', 3436 param: new param('push pageOne in pageOne when stack size: ' + this.derivedStack.size()) 3437 }); 3438 }) 3439 }.title('Page One') 3440 .onReady((context: NavDestinationContext) => { 3441 console.log('[derive-test] reached PageOne\'s onReady'); 3442 // get derived stack from navdestinationContext 3443 this.derivedStack = context.pathStack as DerivedNavPathStack; 3444 console.log('[derive-test] -- got derivedStack: ' + this.derivedStack.id); 3445 this.curStringifyParam = JSON.stringify(context.pathInfo.param); 3446 console.log('[derive-test] -- got param: ' + this.curStringifyParam); 3447 }) 3448 } 3449} 3450``` 3451 3452 3453### Example 11: Using Symbol Icons 3454 3455This example shows how to use symbol icons in **Navigation** and **NavDestination**. 3456 3457```ts 3458import { SymbolGlyphModifier } from '@kit.ArkUI'; 3459 3460@Entry 3461@Component 3462struct NavigationExample { 3463 @Provide('navPathStack') navPathStack: NavPathStack = new NavPathStack(); 3464 @State menuItems: Array<NavigationMenuItem> = [ 3465 { 3466 value: 'menuItem1', 3467 icon: 'resources/base/media/ic_public_ok.svg' // Icon resource path. 3468 }, 3469 { 3470 value: 'menuItem2', 3471 icon: 'resources/base/media/ic_public_ok.svg', // Icon resource path. 3472 symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_folder_badge_plus')).fontColor([Color.Red, Color.Green]) 3473 .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR), 3474 }, 3475 { 3476 value: 'menuItem3', 3477 symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_lungs')), 3478 }, 3479 ] 3480 @State toolItems: Array<ToolbarItem> = [ 3481 { 3482 value: 'toolItem1', 3483 icon: 'resources/base/media/ic_public_ok.svg', // Icon resource path. 3484 symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_lungs')), 3485 status: ToolbarItemStatus.ACTIVE, 3486 activeSymbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_folder_badge_plus')).fontColor([Color.Red, 3487 Color.Green]).renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR), 3488 action: () => { 3489 } 3490 }, 3491 { 3492 value: 'toolItem2', 3493 symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_star')), 3494 status: ToolbarItemStatus.ACTIVE, 3495 activeIcon: 'resources/base/media/ic_public_more.svg', // Icon resource path. 3496 action: () => { 3497 } 3498 }, 3499 { 3500 value: 'toolItem3', 3501 symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_star')), 3502 status: ToolbarItemStatus.ACTIVE, 3503 activeSymbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_lungs')), 3504 action: () => { 3505 } 3506 } 3507 ] 3508 3509 @Builder 3510 myRouter(name: string, param?: Object) { 3511 if (name === 'NavigationMenu') { 3512 NavigationMenu(); 3513 } 3514 } 3515 3516 build() { 3517 Navigation(this.navPathStack) { 3518 Column() { 3519 Button('Go').onClick(() => { 3520 this.navPathStack.pushPathByName('NavigationMenu', null); 3521 }) 3522 } 3523 } 3524 .backButtonIcon(new SymbolGlyphModifier($r('sys.symbol.ohos_wifi'))) 3525 .titleMode(NavigationTitleMode.Mini) 3526 .menus(this.menuItems) 3527 .toolbarConfiguration(this.toolItems) 3528 .title('Level-1 page') 3529 .navDestination(this.myRouter) 3530 } 3531} 3532 3533@Component 3534export struct NavigationMenu { 3535 @Consume('navPathStack') navPathStack: NavPathStack; 3536 @State menuItems: Array<NavigationMenuItem> = [ 3537 { 3538 value: 'menuItem1', 3539 icon: 'resources/base/media/ic_public_ok.svg', // Icon resource path. 3540 action: () => { 3541 } 3542 }, 3543 { 3544 value: 'menuItem2', 3545 symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_folder_badge_plus')).fontColor([Color.Red, Color.Green]) 3546 .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR), 3547 action: () => { 3548 } 3549 }, 3550 { 3551 value: 'menuItem3', 3552 symbolIcon: new SymbolGlyphModifier($r('sys.symbol.repeat_1')), 3553 action: () => { 3554 } 3555 }, 3556 ] 3557 3558 build() { 3559 NavDestination() { 3560 Row() { 3561 Column() { 3562 } 3563 .width('100%') 3564 } 3565 .height('100%') 3566 } 3567 .hideTitleBar(false) 3568 .title('NavDestination title') 3569 .backgroundColor($r('sys.color.ohos_id_color_titlebar_sub_bg')) 3570 .backButtonIcon(new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Blue])) 3571 .menus(this.menuItems) 3572 } 3573} 3574``` 3575 3576 3577### Example 12: Setting the Custom Title Bar Margin 3578 3579This example demonstrates how to set custom title bar padding in **Navigation** and **NavDestination**, and how to modify the main title and subtitle text styles through **TextModifier**. 3580 3581```ts 3582import { LengthMetrics } from '@kit.ArkUI'; 3583import { TextModifier } from '@ohos.arkui.modifier'; 3584 3585class MainTitleTextModfier extends TextModifier { 3586 useStyle1: boolean = true; 3587 3588 applyNormalAttribute(instance: TextModifier): void { 3589 if (this.useStyle1) { 3590 console.log(`testTag mainTitle use style1`); 3591 instance.fontColor('#FFFFC000') 3592 instance.fontSize(35) 3593 instance.fontWeight(FontWeight.Bolder) 3594 instance.fontStyle(FontStyle.Normal) 3595 instance.textShadow({ radius: 5, offsetX: 9 }) 3596 } else { 3597 console.log(`testTag mainTitle use style2`); 3598 instance.fontColor('#FF23A98D') 3599 instance.fontSize(20) 3600 instance.heightAdaptivePolicy(TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST) 3601 instance.fontWeight(FontWeight.Lighter) 3602 instance.fontStyle(FontStyle.Italic) 3603 instance.textShadow({ radius: 3, offsetX: 3 }) 3604 } 3605 } 3606} 3607 3608class SubTitleTextModfier extends TextModifier { 3609 useStyle1: boolean = true; 3610 3611 applyNormalAttribute(instance: TextModifier): void { 3612 if (this.useStyle1) { 3613 console.log(`testTag subTitle use style1`); 3614 instance.fontColor('#FFFFC000') 3615 instance.fontSize(15) 3616 instance.fontWeight(FontWeight.Bolder) 3617 instance.fontStyle(FontStyle.Normal) 3618 instance.textShadow({ radius: 5, offsetX: 9 }) 3619 } else { 3620 console.log(`testTag subTitle use style2`); 3621 instance.fontColor('#FF23A98D') 3622 instance.fontSize(10) 3623 instance.fontWeight(FontWeight.Lighter) 3624 instance.fontStyle(FontStyle.Italic) 3625 instance.textShadow({ radius: 3, offsetX: 3 }) 3626 } 3627 } 3628} 3629 3630@Entry 3631@Component 3632struct NavigationExample { 3633 private navPathStack: NavPathStack = new NavPathStack(); 3634 // Assign an initial padding at the start of the title bar. 3635 @State paddingStart: LengthMetrics = LengthMetrics.vp(0); 3636 // Assign an initial padding at the end of the title bar. 3637 @State paddingEnd: LengthMetrics = LengthMetrics.vp(0); 3638 // Main title attribute modifier. 3639 @State mainTitleModifier: MainTitleTextModfier = new MainTitleTextModfier(); 3640 // Subtitle attribute modifier. 3641 @State subTitleModifier: SubTitleTextModfier = new SubTitleTextModfier(); 3642 @State applyModifier: boolean = false; 3643 @State useStyle1: boolean = true; 3644 3645 @Builder 3646 myRouter(name: string, param?: Object) { 3647 if (name === 'NavDestinationExample') { 3648 NavDestinationExample(); 3649 } 3650 } 3651 3652 build() { 3653 Navigation(this.navPathStack) { 3654 Column() { 3655 // Switch between padding values for the title bar. 3656 Button('apply padding 32vp') 3657 .onClick(() => { 3658 this.paddingStart = LengthMetrics.vp(32); 3659 this.paddingEnd = LengthMetrics.vp(32); 3660 }) 3661 .margin({ top: 70 }) 3662 .width(180) 3663 Button('apply padding 20vp') 3664 .onClick(() => { 3665 this.paddingStart = LengthMetrics.vp(20); 3666 this.paddingEnd = LengthMetrics.vp(20); 3667 }) 3668 .margin({ top: 40 }) 3669 .width(180) 3670 Button('pushPage') 3671 .onClick(() => { 3672 this.navPathStack.pushPath({ name: 'NavDestinationExample' }) 3673 }) 3674 .margin({ top: 40 }) 3675 .width(180) 3676 Row() { 3677 Text(`apply Modifier`) 3678 Toggle({ isOn: this.applyModifier, type: ToggleType.Switch }).onChange((isOn: boolean) => { 3679 this.applyModifier = isOn; 3680 }) 3681 } 3682 .padding({ top: 95, left: 5, right: 5 }) 3683 .width(180) 3684 .justifyContent(FlexAlign.SpaceBetween) 3685 3686 Row() { 3687 Text(`use Style1`) 3688 Toggle({ isOn: this.useStyle1, type: ToggleType.Switch }).onChange((isOn: boolean) => { 3689 this.mainTitleModifier.useStyle1 = isOn; 3690 this.subTitleModifier.useStyle1 = isOn; 3691 this.useStyle1 = isOn; 3692 }) 3693 } 3694 .padding({ top: 40, left: 5, right: 5 }) 3695 .width(180) 3696 .justifyContent(FlexAlign.SpaceBetween) 3697 } 3698 .width('100%') 3699 .height('100%') 3700 } 3701 .titleMode(NavigationTitleMode.Full) 3702 .title( 3703 { main: "Title", sub: "subTitle" }, 3704 this.applyModifier ? 3705 { 3706 paddingStart: this.paddingStart, 3707 paddingEnd: this.paddingEnd, 3708 mainTitleModifier: this.mainTitleModifier, 3709 subTitleModifier: this.subTitleModifier, 3710 } : { 3711 paddingStart: this.paddingStart, 3712 paddingEnd: this.paddingEnd 3713 }) 3714 .navDestination(this.myRouter) 3715 } 3716} 3717 3718@Component 3719export struct NavDestinationExample { 3720 @State menuItems: Array<NavigationMenuItem> = [ 3721 { 3722 value: 'menuItem1', 3723 icon: 'resources/base/media/ic_public_ok.svg', // Icon resource path. 3724 action: () => { 3725 } 3726 } 3727 ] 3728 @State paddingStart: LengthMetrics = LengthMetrics.vp(0); 3729 @State paddingEnd: LengthMetrics = LengthMetrics.vp(0); 3730 // Main title attribute modifier. 3731 @State mainTitleModifier: MainTitleTextModfier = new MainTitleTextModfier(); 3732 // Subtitle attribute modifier. 3733 @State subTitleModifier: SubTitleTextModfier = new SubTitleTextModfier(); 3734 @State applyModifier: boolean = false; 3735 @State useStyle1: boolean = true; 3736 3737 build() { 3738 NavDestination() { 3739 Column() { 3740 // Switch between padding values for the title bar. 3741 Button('apply padding 32vp') 3742 .onClick(() => { 3743 this.paddingStart = LengthMetrics.vp(32); 3744 this.paddingEnd = LengthMetrics.vp(32); 3745 }) 3746 .margin({ top: 150 }) 3747 .width(180) 3748 Button('apply padding 20vp') 3749 .onClick(() => { 3750 this.paddingStart = LengthMetrics.vp(20); 3751 this.paddingEnd = LengthMetrics.vp(20); 3752 }) 3753 .margin({ top: 40 }) 3754 .width(180) 3755 Row() { 3756 Text(`apply Modifier`) 3757 Toggle({ isOn: this.applyModifier, type: ToggleType.Switch }).onChange((isOn: boolean) => { 3758 this.applyModifier = isOn; 3759 }) 3760 } 3761 .padding({ top: 95, left: 5, right: 5 }) 3762 .width(180) 3763 .justifyContent(FlexAlign.SpaceBetween) 3764 3765 Row() { 3766 Text(`use Style1`) 3767 Toggle({ isOn: this.useStyle1, type: ToggleType.Switch }).onChange((isOn: boolean) => { 3768 this.mainTitleModifier.useStyle1 = isOn; 3769 this.subTitleModifier.useStyle1 = isOn; 3770 this.useStyle1 = isOn; 3771 }) 3772 } 3773 .padding({ top: 40, left: 5, right: 5 }) 3774 .width(180) 3775 .justifyContent(FlexAlign.SpaceBetween) 3776 } 3777 .width('100%') 3778 .height('90%') 3779 } 3780 .hideTitleBar(false) 3781 .title( 3782 { main: "Title", sub: "subTitle" }, 3783 this.applyModifier ? 3784 { 3785 paddingStart: this.paddingStart, 3786 paddingEnd: this.paddingEnd, 3787 mainTitleModifier: this.mainTitleModifier, 3788 subTitleModifier: this.subTitleModifier, 3789 } : { 3790 paddingStart: this.paddingStart, 3791 paddingEnd: this.paddingEnd 3792 }) 3793 .menus(this.menuItems) 3794 } 3795} 3796``` 3797 3798 3799### Example 13: Implementing a Custom Transition Animation 3800 3801This example shows how to implement a custom transition animation for navigation between pages. 3802 3803<!--code_no_check--> 3804```ts 3805// Index.ets 3806import { AnimateCallback, CustomTransition } from './CustomTransitionUtils' 3807 3808@Entry 3809@Component 3810struct NavigationCustomTransitionExample { 3811 pageInfos: NavPathStack = new NavPathStack(); 3812 3813 aboutToAppear() { 3814 this.pageInfos.pushPath({ name: 'PageOne' }, false); 3815 } 3816 3817 build() { 3818 Navigation(this.pageInfos) { 3819 } 3820 .hideNavBar(true) 3821 .customNavContentTransition((from: NavContentInfo, to: NavContentInfo, operation: NavigationOperation) => { 3822 // No custom animation for the home page 3823 if (from.index === -1 || to.index === -1) { 3824 return undefined; 3825 } 3826 3827 let customAnimation: NavigationAnimatedTransition = { 3828 timeout: 2000, 3829 // When the transition starts, the system calls this method and passes in the transition context proxy object. 3830 transition: (transitionProxy: NavigationTransitionProxy) => { 3831 if (!from.navDestinationId || !to.navDestinationId) { 3832 return; 3833 } 3834 // Obtain the corresponding transition animation callback from the CustomTransition class based on the sequence of subpages. 3835 let fromParam: AnimateCallback = CustomTransition.getInstance().getAnimateParam(from.navDestinationId); 3836 let toParam: AnimateCallback = CustomTransition.getInstance().getAnimateParam(to.navDestinationId); 3837 // Push animation 3838 if (operation == NavigationOperation.PUSH) { 3839 if (fromParam.start && toParam.start) { 3840 // Set the animation start for both pages in the push transition. 3841 fromParam.start(true, true); 3842 toParam.start(true, false); 3843 } 3844 animateTo({ 3845 duration: 500, curve: Curve.Friction, onFinish: () => { 3846 // Manually call the finishTransition API after the animation ends. Otherwise, the system will automatically call the API after the specified timeout period. 3847 transitionProxy.finishTransition(); 3848 } 3849 }, () => { 3850 if (fromParam.finish && toParam.finish) { 3851 // Set the animation end for both pages in the push transition. 3852 fromParam.finish(true, true); 3853 toParam.finish(true, false); 3854 } 3855 3856 }) 3857 } else if (operation == NavigationOperation.POP) { 3858 // Pop animation 3859 if (fromParam.start && toParam.start) { 3860 // Set the animation start for both pages in the pop transition. 3861 fromParam.start(false, true); 3862 toParam.start(false, false); 3863 } 3864 animateTo({ 3865 duration: 500, curve: Curve.Friction, onFinish: () => { 3866 // Manually call the finishTransition API after the animation ends. Otherwise, the system will automatically call the API after the specified timeout period. 3867 transitionProxy.finishTransition(); 3868 } 3869 }, () => { 3870 if (fromParam.finish && toParam.finish) { 3871 // Set the animation end for both pages in the pop transition. 3872 fromParam.finish(false, true); 3873 toParam.finish(false, false); 3874 } 3875 }) 3876 } else { 3877 // No animation for the replacement operation 3878 } 3879 } 3880 }; 3881 return customAnimation; 3882 }) 3883 } 3884} 3885 3886 3887// PageOne 3888@Builder 3889export function PageOneBuilder() { 3890 PageContainer({ title: "PageOne" }) 3891} 3892 3893// PageTwo 3894@Builder 3895export function PageTwoBuilder() { 3896 PageContainer({ title: "PageTwo" }) 3897} 3898 3899@Component 3900export struct PageContainer { 3901 pageInfos: NavPathStack = new NavPathStack(); 3902 @State translateY: string = '0'; 3903 pageId: string = ''; 3904 title: string = '' 3905 3906 registerCallback() { 3907 CustomTransition.getInstance().registerNavParam(this.pageId, 3908 // Set the start point of the transition animation based on the transition type. 3909 (isPush: boolean, isExit: boolean) => { 3910 if (isPush) { 3911 if (isExit) { 3912 this.translateY = '0'; 3913 } else { 3914 this.translateY = '100%'; 3915 } 3916 } else { 3917 if (isExit) { 3918 this.translateY = '0'; 3919 } else { 3920 this.translateY = '0'; 3921 } 3922 } 3923 }, 3924 // Set the end point of the transition animation based on the transition type. 3925 (isPush: boolean, isExit: boolean) => { 3926 if (isPush) { 3927 if (isExit) { 3928 this.translateY = '0'; 3929 } else { 3930 this.translateY = '0'; 3931 } 3932 } else { 3933 if (isExit) { 3934 this.translateY = '100%'; 3935 } else { 3936 this.translateY = '0'; 3937 } 3938 } 3939 }); 3940 } 3941 3942 build() { 3943 NavDestination() { 3944 Column() { 3945 Button('push next page', { stateEffect: true, type: ButtonType.Capsule }) 3946 .width('80%') 3947 .height(40) 3948 .margin(20) 3949 .onClick(() => { 3950 this.pageInfos.pushPath({ name: this.title == 'PageOne' ? "PageTwo" : "PageOne" }) 3951 }) 3952 } 3953 .size({ width: '100%', height: '100%' }) 3954 } 3955 .title(this.title) 3956 .onDisAppear(() => { 3957 // Unregister the custom transition animation parameters when the page is destroyed. 3958 CustomTransition.getInstance().unRegisterNavParam(this.pageId); 3959 }) 3960 .onReady((context: NavDestinationContext) => { 3961 this.pageInfos = context.pathStack; 3962 if (context.navDestinationId) { 3963 this.pageId = context.navDestinationId; 3964 // Register the custom transition animation parameters when the page is created. 3965 this.registerCallback(); 3966 } 3967 }) 3968 .translate({ y: this.translateY }) 3969 .backgroundColor(this.title == 'PageOne' ? '#F1F3F5' : '#ff11dee5') 3970 } 3971} 3972``` 3973```ts 3974// The CustomNavigationUtils.ts file defines a utility class for managing custom animation parameters for different pages. 3975 3976// Custom API to save the transition animation callback and parameters related to a page. 3977export interface AnimateCallback { 3978 start: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined; 3979 finish: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined 3980} 3981 3982const customTransitionMap: Map<string, AnimateCallback> = new Map(); 3983 3984export class CustomTransition { 3985 static delegate = new CustomTransition(); 3986 3987 static getInstance() { 3988 return CustomTransition.delegate; 3989 } 3990 3991 /* Register animation callbacks for a page. 3992 * name: unique ID of the target page 3993 * startCallback: used to set the page state at the start of the animation. 3994 * endCallback: used to set the page state at the end of the animation. 3995 */ 3996 registerNavParam(name: string, startCallback: (isPush: boolean, isExit: boolean) => void, 3997 endCallback: (isPush: boolean, isExit: boolean) => void): void { 3998 if (customTransitionMap.has(name)) { 3999 let param = customTransitionMap.get(name); 4000 if (param != undefined) { 4001 param.start = startCallback; 4002 param.finish = endCallback; 4003 return; 4004 } 4005 } 4006 let params: AnimateCallback = { start: startCallback, finish: endCallback }; 4007 customTransitionMap.set(name, params); 4008 } 4009 4010 unRegisterNavParam(name: string): void { 4011 customTransitionMap.delete(name); 4012 } 4013 4014 getAnimateParam(name: string): AnimateCallback { 4015 let result: AnimateCallback = { 4016 start: customTransitionMap.get(name)?.start, 4017 finish: customTransitionMap.get(name)?.finish 4018 }; 4019 return result; 4020 } 4021} 4022``` 4023 4024```json 4025// Configure {"routerMap": "$profile:route_map"} in the project configuration file module.json5. 4026// route_map.json 4027{ 4028 "routerMap": [ 4029 { 4030 "name": "PageOne", 4031 "pageSourceFile": "src/main/ets/pages/Index.ets", 4032 "buildFunction": "PageOneBuilder", 4033 "data": { 4034 "description": "this is pageOne" 4035 } 4036 }, 4037 { 4038 "name": "PageTwo", 4039 "pageSourceFile": "src/main/ets/pages/Index.ets", 4040 "buildFunction": "PageTwoBuilder" 4041 } 4042 ] 4043} 4044``` 4045 4046
