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