77768380创建于 4月10日历史提交

NavDestination

NavDestination is the root container of a destination page and represents the content area of the Navigation component.

NOTE

This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.

Since API version 11, this component supports the safe area attribute by default, with the default attribute value being expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]). You can override this attribute to change the default behavior. In earlier versions, you need to use the expandSafeArea attribute to implement the safe area feature.

The NavDestination component must be used in conjunction with the Navigation component to act as the root node for the navigation destination page. When used alone, it can only function as a standard container component and does not possess any routing-related attributes or capabilities.

If the lifecycle of an intermediate page in the routing stack changes, the lifecycle callbacks (onWillShow, onShown, onHidden, onWillDisappear) of the top NavDestination in the stack both before and after the navigation will be triggered last in the sequence.

If no main title or subtitle is set for NavDestination and there is no back button, the title bar is not displayed.

Avoid setting layout-related attributes such as the position and size. They may result in display issues on the page. For example, do not apply the zIndex attribute to a NavDestination component. This will override the system-defined stacking order and may cause display anomalies.

Child Components

NOTE

Allowed child component types: built-in and custom components, including rendering control types (if/else, ForEach, and LazyForEach).

Number of child components: multiple.

APIs

NavDestination()

Creates the root container for a subpage in Navigation.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Attributes

The universal attributes are supported.

title

title(value: string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle | Resource, options?: NavigationTitleOptions)

Sets the page title. 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 with an ellipsis (...) if it is still overlong. (2) If a subtitle is set, the subtitle is scaled down and then truncated with an ellipsis (...) if it is still overlong.

NOTE

This API can be called within attributeModifier since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	string \| CustomBuilder \| NavDestinationCommonTitle \| NavDestinationCustomTitle \| Resource¹⁴⁺	Yes	Page title.
options¹²⁺	NavigationTitleOptions	No	Title bar options.

hideTitleBar

hideTitleBar(value: boolean)

Specifies whether to hide the title bar.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	boolean	Yes	Whether to hide the title bar. Default value: false. true: Hide the title bar. false: Show the title bar.

hideTitleBar¹³⁺

hideTitleBar(hide: boolean, animated: boolean)

Specifies whether to hide the title bar. Compared with hideTitleBar, this API adds the capability to control whether to animate the visibility change of the title bar.

Atomic service API: This API can be used in atomic services since API version 13.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
hide	boolean	Yes	Whether to hide the title bar. Default value: false. true: Hide the title bar. false: Show the title bar.
animated	boolean	Yes	Whether to animate the visibility change of the title bar. Default value: false. true: Animate the visibility change of the title bar. false: Do not animate the visibility change of the title bar.

toolbarConfiguration¹³⁺

toolbarConfiguration(toolbarParam: Array<ToolbarItem> | CustomBuilder, options?: NavigationToolbarOptions)

Sets the content of the toolbar. If this API is not called, the toolbar remains hidden.

NOTE

This API can be called within attributeModifier since API version 20.

The following operations are not allowed: modifying the icon size through the fontSize attribute of the SymbolGlyphModifier object, changing the animation effects through the effectStrategy attribute, or changing the animation effect type through the symbolEffect attribute.

Atomic service API: This API can be used in atomic services since API version 13.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
toolbarParam	Array<ToolbarItem> \| CustomBuilder	Yes	Content of the toolbar. When configured with Array<ToolbarItem>, the toolbar follows the rules below: - Toolbar items are evenly distributed on the bottom toolbar, with text and icons evenly spaced in each content area. - 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, the display will remain the same as in portrait mode. (2) If the display mode is Stack, the toolbar must be used together with Array<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. When configured with CustomBuilder, the toolbar does not follow the above rules.
options	NavigationToolbarOptions	No	Toolbar options. Toolbar options include the background color, background blur style and blur option, background properties, layout mode of the toolbar, as well as whether to hide the toolbar text, and options for the toolbar's more button menu.

hideToolBar¹³⁺

hideToolBar(hide: boolean, animated?: boolean)

Specifies whether to hide the toolbar.

Atomic service API: This API can be used in atomic services since API version 13.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
hide	boolean	Yes	Whether to hide the toolbar. Default value: false. true: Hide the toolbar. false: Show the toolbar.
animated	boolean	No	Whether to animate the visibility change of the toolbar. Default value: false. true: Animate the visibility change of the toolbar. false: Do not animate the visibility change of the toolbar.

mode¹¹⁺

mode(value: NavDestinationMode)

Sets the mode of the NavDestination component. Dynamic modification is not supported.

NOTE

This API can be called within attributeModifier since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	NavDestinationMode	Yes	Mode of the NavDestination component. Default value: NavDestinationMode.STANDARD.

backButtonIcon¹¹⁺

backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)

Sets the icon of the back button on the title bar.

NOTE

This API can be called within attributeModifier since API version 12.

The following operations are not allowed: modifying the icon size through the fontSize attribute of the SymbolGlyphModifier object, changing the animation effects through the effectStrategy attribute, or changing the animation effect type through the symbolEffect attribute.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	ResourceStr \| PixelMap \| SymbolGlyphModifier¹²⁺	Yes	Icon of the back button on the title bar.

backButtonIcon¹⁹⁺

backButtonIcon(icon: ResourceStr | PixelMap | SymbolGlyphModifier, accessibilityText?: ResourceStr)

Sets the icon and accessibility text for the back button on the title bar.

NOTE

This API cannot be called within attributeModifier.

The following operations are not allowed: modifying the icon size through the fontSize attribute of the SymbolGlyphModifier object, changing the animation effects through the effectStrategy attribute, or changing the animation effect type through the symbolEffect attribute.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
icon	ResourceStr \| PixelMap \| SymbolGlyphModifier	Yes	Icon of the back button on the title bar.
accessibilityText	ResourceStr	No	Accessibility text for the back button. Default value: back when the system language is English.

menus¹²⁺

menus(value: Array<NavigationMenuItem> | CustomBuilder)

Sets 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>, 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.

NOTE

This API can be called within attributeModifier since API version 14.

The following operations are not allowed: modifying the icon size through the fontSize attribute of the SymbolGlyphModifier object, changing the animation effects through the effectStrategy attribute, or changing the animation effect type through the symbolEffect attribute.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	Array<NavigationMenuItem> \| CustomBuilder	Yes	Menu items in the upper right corner of the page.

menus¹⁹⁺

menus(items: Array<NavigationMenuItem> | CustomBuilder, options?: NavigationMenuOptions)

Sets the menu items in the upper right corner of the page. If this attribute is not set, no menu item is displayed. Compared with menus, this API adds menu options. When the value type is Array<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.

NOTE

This API cannot be called within attributeModifier.

The following operations are not allowed: modifying the icon size through the fontSize attribute of the SymbolGlyphModifier object, changing the animation effects through the effectStrategy attribute, or changing the animation effect type through the symbolEffect attribute.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
items	Array<NavigationMenuItem> \| CustomBuilder	Yes	Menu items in the upper right corner of the page.
options	NavigationMenuOptions	No	Optional settings for menu items in the upper right corner of the page.

ignoreLayoutSafeArea¹²⁺

ignoreLayoutSafeArea(types?: Array<LayoutSafeAreaType>, edges?: Array<LayoutSafeAreaEdge>)

Ignores the layout safe area by allowing the component to extend into the non-safe areas of the screen.

NOTE

Prerequisites for the ignoreLayoutSafeArea attribute to take effect:
When LayoutSafeAreaType.SYSTEM is set, the component can extend into the non-safe area if its boundaries overlap with the non-safe area.

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.

To allow a component to extend into non-safe areas, the title bar and toolbar must be hidden or set to STACK mode.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
types	Array <LayoutSafeAreaType>	No	Types of non-safe areas to extend into. Default value: [LayoutSafeAreaType.SYSTEM]
edges	Array <LayoutSafeAreaEdge>	No	Edges for expanding the safe area. Default value: [LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]

systemBarStyle¹²⁺

systemBarStyle(style: Optional<SystemBarStyle>)

Sets the style of the system status bar when this NavDestination page is displayed in the Navigation component.

NOTE

The setting takes effect only when the NavDestination component is used in conjunction with the Navigation component.

For other usage restrictions, see the description of systemBarStyle for the Navigation component.

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
style	Optional<SystemBarStyle>	Yes	Style of the system status bar.

systemTransition¹⁴⁺

systemTransition(type: NavigationSystemTransitionType)

Sets the system transition animation of the NavDestination component. System transition animations for the title bar and content area can be configured separately.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	NavigationSystemTransitionType	Yes	Type of the system transition animation. Default value: NavigationSystemTransitionType.DEFAULT.

recoverable¹⁴⁺

recoverable(recoverable: Optional<boolean>)

Sets whether the NavDestination component is recoverable. If set to recoverable, when the application process exits unexpectedly and restarts, the NavDestination component will be automatically re-created. To use this feature, ensure that the recoverable attribute is set for the Navigation component associated with the NavDestination component.

NOTE

This API must be used together with the recoverable API of Navigation.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
recoverable	Optional<boolean>	Yes	Whether the NavDestination component is recoverable. By default, it is not recoverable. Default value: false. true: The NavDestination component is recoverable. false: The NavDestination component is not recoverable.

bindToScrollable¹⁴⁺

bindToScrollable(scrollers: Array<Scroller>)

Binds the NavDestination component with a scrollable container, which can be a List, Scroll, Grid, or WaterFlow component. This way, scrolling in the scrollable container triggers the display and hide animations of the title bar and toolbar of all NavDestination components that are bound to it – scrolling up triggers the hide animation, and scrolling down triggers the show animation. A single NavDestination component can be bound to multiple scrollable containers, and a single scrollable container can be bound to multiple NavDestination components. For details, see Example 1.

NOTE

The connection between the scrolling actions and the animations for showing or hiding the title bar and toolbar of the NavDestination component takes effect only when the title bar or toolbar is visible.

If a NavDestination component is bound to multiple scrollable containers, scrolling in any of these containers triggers the display or hiding animations of the title bar and toolbar. Specifically, when any scrollable container reaches either the bottom or the top, the display animation for the title bar and toolbar is triggered without delay. As such, to ensure the optimal user experience, avoid triggering scroll events of multiple scrollable containers simultaneously.

This API can be called in attributeModifier since API version 22.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
scrollers	Array<Scroller>	Yes	Controller of the target scrollable container.

bindToNestedScrollable¹⁴⁺

bindToNestedScrollable(scrollInfos: Array<NestedScrollInfo>)

Binds the NavDestination component with a nested scrollable container, which can be a List, Scroll, Grid, or WaterFlow component. This way, scrolling in the scrollable container triggers the display and hide animations of the title bar and toolbar of all NavDestination components that are bound to it – scrolling up triggers the hide animation, and scrolling down triggers the show animation. A single NavDestination component can be bound to multiple nested scrollable containers, and a single nested scrollable container can be bound to multiple NavDestination components. For details, see Example 1.

NOTE

The connection between the scrolling actions and the animations for showing or hiding the title bar and toolbar of the NavDestination component takes effect only when the title bar or toolbar is visible.

If a NavDestination component is bound to multiple scrollable containers, scrolling in any of these containers triggers the display or hiding animations of the title bar and toolbar. Specifically, when any scrollable container reaches either the bottom or the top, the display animation for the title bar and toolbar is triggered without delay. As such, to ensure the optimal user experience, avoid triggering scroll events of multiple scrollable containers simultaneously.

This API can be called in attributeModifier since API version 22.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
scrollInfos	Array<NestedScrollInfo>	Yes	Controller of the target nested scrollable containers.

hideBackButton¹⁵⁺

hideBackButton(hide: Optional<boolean>)

Sets whether to hide the back button in the title bar.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
hide	Optional<boolean>	Yes	Whether to hide the back button in the title bar. Default value: false. true: Hide the back button in the title bar. false: Show the back button in the title bar.

customTransition¹⁵⁺

customTransition(delegate: NavDestinationTransitionDelegate)

Sets a custom transition animation for the NavDestination component.

NOTE

This API cannot be called within attributeModifier.

If both this attribute and systemTransition are set, whichever is set later takes effect.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
delegate	NavDestinationTransitionDelegate	Yes	Delegate function for custom animations of the NavDestination component.

preferredOrientation¹⁹⁺

preferredOrientation(orientation: Optional<Orientation>)

Sets the display orientation for the NavDestination component. After the transition to the NavDestination, the system also switches the application's main window to the specified display orientation.

NOTE

This attribute is effective only if the following conditions are all met:

The NavDestination component belongs to the application's main window page, and the main window is a full-screen window.

The Navigation container containing the NavDestination component occupies the entire application page area.

The type of NavDestination is NavDestinationMode.STANDARD.

The actual effect of setting the display orientation depends on the specific device support. For details, see setPreferredOrientation.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
orientation	Optional<Orientation>	Yes	Display orientation to set.

enableStatusBar¹⁹⁺

enableStatusBar(enabled: Optional<boolean>, animated?: boolean)

Sets whether to show or hide the system status bar when entering this NavDestination component.

NOTE

This attribute is effective only if the following conditions are all met:

The NavDestination component belongs to the application's main window page, and the main window is a full-screen window.

The Navigation container containing the NavDestination component occupies the entire page area.

The NavDestination component occupies the entire Navigation container.

The type of NavDestination is NavDestinationMode.STANDARD.

The actual effect of setting the system status bar depends on the specific device support. For details, see setSpecificSystemBarEnabled.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
enabled	Optional<boolean>	Yes	Whether to show or hide the system status bar when entering the current NavDestination component. true: Show the system status bar. false: Hide the system status bar.
animated	boolean	No	Whether to animate the visibility change of the system status bar. Default value: false. true: Animate the visibility change of the system status bar. false: Do not animate the visibility change of the system status bar.

enableNavigationIndicator¹⁹⁺

enableNavigationIndicator(enabled: Optional<boolean>)

Sets whether to show or hide the system navigation bar when entering this NavDestination component.

NOTE

This attribute is effective only if the following conditions are all met:

The NavDestination component belongs to the application's main window page, and the main window is a full-screen window.

The Navigation container containing the NavDestination component occupies the entire page area.

The NavDestination component occupies the entire Navigation container.

The type of NavDestination is NavDestinationMode.STANDARD.

The actual effect of setting the system navigation bar depends on the specific device support. For details, see setSpecificSystemBarEnabled.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
enabled	Optional<boolean>	Yes	Whether to show or hide the system navigation bar when entering the current NavDestination component. true: Show the system navigation bar. false: Hide the system navigation bar.

NavDestinationMode¹¹⁺

Mode of the NavDestination component.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Value	Description
STANDARD	0	Standard mode.
DIALOG	1	The navigation destination is transparent by default. Stack operations do not affect the visibility of underlying NavDestination components (lifecycle methods like onShown and onHidden remain unchanged). Only the onActive and onInactive lifecycle methods are triggered. Before API version 13, no system transition animation is available by default. System transition animations are supported since API version 13.

NavigationSystemTransitionType¹⁴⁺

Type of the system transition animation.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Value	Description
DEFAULT	0	Default system transition animation. Atomic service API: This API can be used in atomic services since API version 14.
NONE	1	No system transition animation. Atomic service API: This API can be used in atomic services since API version 14.
TITLE	2	System transition animation of the title bar. Atomic service API: This API can be used in atomic services since API version 14.
CONTENT	3	System transition animation of the content area. Atomic service API: This API can be used in atomic services since API version 14.
FADE¹⁵⁺	4	Fade-type system transition animation. Atomic service API: This API can be used in atomic services since API version 15.
EXPLODE¹⁵⁺	5	Center-scale type system transition animation. Atomic service API: This API can be used in atomic services since API version 15.
SLIDE_RIGHT¹⁵⁺	6	Right-slide type system transition animation. Atomic service API: This API can be used in atomic services since API version 15.
SLIDE_BOTTOM¹⁵⁺	7	Bottom-slide type system transition animation. Atomic service API: This API can be used in atomic services since API version 15.

NOTE

System transition animations for the title bar and content area can be configured separately.

The system transition animation of the title bar is only available for the push and pop animations of navigation destination pages in STANDARD mode, with the following constraints:

When NavigationSystemTransitionType is set to TITLE, only the system transition animation of the title bar is displayed.

When NavigationSystemTransitionType is set to CONTENT, only the system transition animation of the content area is displayed.

When NONE or TITLE is set, no system transition animation is displayed. When CONTENT or DEFAULT is set, the system transition animation is displayed by default.

Events

In addition to the universal events, the following events are supported.

onShown¹⁰⁺

onShown(callback: Callback<VisibilityChangeReason>)

Triggered when the navigation destination page is displayed. Starting from API version 21, the callback includes a VisibilityChangeReason parameter indicating the cause of the visibility change.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Callback<VisibilityChangeReason>²¹⁺	Yes	Triggered when the navigation destination page is displayed. In versions earlier than API version 21, the callback is a basic callback without parameters. Since API version 21, the callback includes a VisibilityChangeReason parameter describing the trigger cause.

onHidden¹⁰⁺

onHidden(callback: Callback<VisibilityChangeReason>)

Triggered when the navigation destination page is hidden. Starting from API version 21, the callback includes a VisibilityChangeReason parameter indicating the cause of the visibility change.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Callback<VisibilityChangeReason>²¹⁺	Yes	Triggered when the navigation destination page is hidden. In versions earlier than API version 21, the callback is a basic callback without parameters. Since API version 21, the callback includes a VisibilityChangeReason parameter describing the trigger cause.

onWillAppear¹²⁺

onWillAppear(callback: Callback<void>)

Called when the NavDestination component is about to be mounted. The routing stack can be modified in the callback, and the modification takes effect in the current frame.

NOTE

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Callback<void>	Yes	Called when the NavDestination component is about to be mounted. The routing stack can be modified in the callback, and the modification takes effect in the current frame.

onWillShow¹²⁺

onWillShow(callback: Callback<void>)

Called when the NavDestination component is about to display.

NOTE

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Callback<void>	Yes	Called when the NavDestination component is about to display.

onWillHide¹²⁺

onWillHide(callback: Callback<void>)

Called when the NavDestination component is about to be hidden.

NOTE

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Callback<void>	Yes	Called when the NavDestination component is about to be hidden.

onWillDisappear¹²⁺

onWillDisappear(callback: Callback<void>)

Called when the the NavDestination component is about to be unmounted (or when the transition animation, if any, is about to start).

NOTE

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Callback<void>	Yes	Called when the the NavDestination component is about to be unmounted (or when the transition animation, if any, is about to start).

onBackPressed¹⁰⁺

onBackPressed(callback: () => boolean)

This callback takes effect when content exists in the navigation controller bound to the Navigation component. Triggered when the back button is pressed.

The value true means that the back button logic is overridden, and false means that the previous page is displayed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	() => boolean	Yes	This callback takes effect when content exists in the navigation controller bound to the Navigation component. Triggered when the back button is pressed.

onReady¹¹⁺

onReady(callback: Callback<NavDestinationContext>)

Triggered when the NavDestination component is about to build a child component.

NOTE

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Callback<NavDestinationContext>	Yes	Triggered when the NavDestination component is about to build a child component.

onResult¹⁵⁺

onResult(callback: Optional<Callback<ESObject>>)

Triggered when the NavDestination component returns.

NOTE

This API can be called in attributeModifier since API version 22.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Optional<Callback<ESObject>>	Yes	Callback for page returning, with the parameter being the result parameter passed by the pop, popToName, or popToIndex API. If this parameter is not passed, the input is undefined.

onActive¹⁷⁺

onActive(callback: Optional<Callback<NavDestinationActiveReason>>)

Triggered when the NavDestination component becomes active (on top of the stack and operable, with no special components blocking it). For details, see Example 5.

NOTE

This API can be called in attributeModifier since API version 22.

Atomic service API: This API can be used in atomic services since API version 17.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Optional<Callback<NavDestinationActiveReason>>	Yes	Reason why the NavDestination component switches from inactive to active.

onInactive¹⁷⁺

onInactive(callback: Optional<Callback<NavDestinationActiveReason>>)

Triggered when the NavDestination component becomes inactive (not on top of the stack and inoperable, or on top but blocked by special components). For details, see Example 5.

NOTE

This API can be called in attributeModifier since API version 22.

Atomic service API: This API can be used in atomic services since API version 17.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Optional<Callback<NavDestinationActiveReason>>	Yes	Reason why the NavDestination component switches from active to inactive.

onNewParam¹⁹⁺

onNewParam(callback: Optional<Callback<ESObject>>)

Triggered when a NavDestination page that already exists in the stack is moved to the top using launchMode.MOVE_TO_TOP_SINGLETON or launchMode.POP_TO_SINGLETON.

NOTE

This callback is not triggered by replacePath or replaceDestination.

This API can be called in attributeModifier since API version 22.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
callback	Optional<Callback<ESObject>>	Yes	Callback triggered by onNewParam, with the parameter being the data passed to the target page during navigation.

NavDestinationCommonTitle

Defines a general title for the NavDestination component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
main	string \| Resource¹⁴⁺	No	No	Main title.
sub	string \| Resource¹⁴⁺	No	No	Subtitle.

NavDestinationCustomTitle

Defines a custom title for the NavDestination component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
builder	CustomBuilder	No	No	Content of the title bar.
height	TitleHeight \| Length	No	No	Height of the title bar. Value range: [0, +∞)

NavDestinationContext¹¹⁺

Defines the context information for the NavDestination component.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
pathInfo	NavPathInfo	No	No	Path information of the navigation destination page. Atomic service API: This API can be used in atomic services since API version 11.
pathStack	NavPathStack	No	No	Navigation controller of the current NavDestination component. Atomic service API: This API can be used in atomic services since API version 11.
navDestinationId¹²⁺	string	No	Yes	Unique ID of the current navigation destination page, which is automatically generated by the system and is irrelevant to the universal attribute id of the component. Atomic service API: This API can be used in atomic services since API version 12.
mode²²⁺	NavDestinationMode	No	Yes	Type of the current NavDestination. Atomic service API: This API can be used in atomic services since API version 22.

getConfigInRouteMap¹²⁺

getConfigInRouteMap(): RouteMapConfig | undefined

Obtains the routing configuration of the current NavDestination component.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
RouteMapConfig \| undefined	Routing configuration of the current page. undefined is returned when the page is not configured through the route table.

RouteMapConfig¹²⁺

Defines the routing configuration.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
name	string	No	No	Page name.
pageSourceFile	string	No	No	Path of the page in the current package.
data	Object	No	No	Custom data of the page.

NestedScrollInfo¹⁴⁺

Provides the information about the nested scrollable containers.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
parent	Scroller	No	No	Controller of the target scrollable container.
child	Scroller	No	No	Controller of the scrollable container nested within the target scrollable container. This scrollable container is a child component of the target scrollable container.

NavDestinationActiveReason¹⁷⁺

Enumerates reasons for the activation state changes of the NavDestination component.

Atomic service API: This API can be used in atomic services since API version 17.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Value	Description
TRANSITION	0	Activation state changes due to page navigation.
CONTENT_COVER	1	Activation state changes due to the opening or closing of a modal page.
SHEET	2	Activation state changes due to the opening or closing of a sheet.
DIALOG	3	Activation state changes due to the opening or closing of a custom dialog box.
OVERLAY	4	Activation state changes due to the opening or closing of an overlay using OverlayManager.
APP_STATE	5	Activation state changes due to switching between foreground and background states of the application.

VisibilityChangeReason²¹⁺

Enumerates reasons for NavDestination visibility changes.

Atomic service API: This API can be used in atomic services since API version 21.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Value	Description
TRANSITION	0	Visibility changes due to page navigation.
CONTENT_COVER	1	Visibility changes due to the opening or closing of a modal page.
APP_STATE	2	Visibility changes due to switching between the foreground and background states.

NavDestinationTransition¹⁵⁺

Defines a custom transition animation for the NavDestination component.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
onTransitionEnd	Callback<void>	No	Yes	Callback triggered when the transition animation ends.
duration	number	No	Yes	Duration of the transition animation. Default value: 1000 (in milliseconds)
curve	Curve	No	Yes	Curve type of the animation. Default value: Curve.EaseInOut](ts-appendix-enums.md#curve)
delay	number	No	Yes	Delay of the transition animation. Default value: 0 (in milliseconds)
event	Callback<void>	No	No	Closure function specifying the transition animation. The system generates the corresponding transition animation based on the modifications to the component's UI state within the closure. For details, see event in animateTo.

NavDestinationTransitionDelegate¹⁵⁺

type NavDestinationTransitionDelegate = (operation: NavigationOperation, isEnter: boolean) => Array<NavDestinationTransition> | undefined

Defines the delegate function for custom transition animations of the NavDestination component.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
operation	NavigationOperation	Yes	Type of navigation operation for the current page transition.
isEnter	boolean	Yes	Whether the current page is an entry page. true: The current page is an entry page. false: The current page is not an entry page.

Return value

Type	Description
Array<NavDestinationTransition> \| undefined	Array of custom animations for the NavDestination page. If undefined is returned, the default system animation is used.

Orientation¹⁹⁺

type Orientation = Orientation

Defines an instance object of the Orientation type.

System capability: SystemCapability.ArkUI.ArkUI.Full

Atomic service API: This API can be used in atomic services since API version 19.

Type	Description
Orientation	Orientation instance.

Example

This example shows how to bind a NavDestination component to scrollable containers so that scrolling in the scrollable containers triggers the animations for showing or hiding the title bar and toolbar of the NavDestination component.

import { SymbolGlyphModifier } from '@kit.ArkUI';

@Component
struct MyPageOne {
  private listScroller: Scroller = new Scroller();
  private scrollScroller: Scroller = new Scroller();
  private arr: number[] = [];

  aboutToAppear(): void {
    for (let i = 0; i < 30; i++) {
      this.arr.push(i);
    }
  }

  build() {
    NavDestination() {
      Scroll(this.scrollScroller) {
        Column() {
          List({ space: 0, initialIndex: 0, scroller: this.listScroller }) {
            ForEach(this.arr, (item: number, index: number) => {
              ListItem() {
                Text('' + item)
                  .height(100)
                  .fontSize(16)
                  .textAlign(TextAlign.Center)
                  .width('90%')
                  .margin({ left: '5%' })
                  .borderRadius(10)
                  .backgroundColor(Color.Gray)
              }
            }, (item: string) => item);
          }.width('100%').height('80%').scrollBar(BarState.Off)
          .nestedScroll({ scrollForward: NestedScrollMode.SELF_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST })

          ForEach(this.arr, (item: number, index: number) => {
            ListItem() {
              Text('' + item)
                .height(100)
                .fontSize(16)
                .textAlign(TextAlign.Center)
                .width('90%')
                .margin({ top: '5%' })
                .borderRadius(10)
                .backgroundColor(Color.Pink)
            }
          }, (item: string) => item);
        }
      }
      .width('100%')
      .scrollBar(BarState.Off)
      .scrollable(ScrollDirection.Vertical)
      .edgeEffect(EdgeEffect.Spring)
    }
    .title('PageOne', { backgroundColor: Color.Yellow, barStyle: BarStyle.STACK })
    .toolbarConfiguration([
      {
        // Replace $r('sys.symbol.phone_badge_star') with the resource file you use.
        value: 'item1',
        symbolIcon: new SymbolGlyphModifier($r('sys.symbol.phone_badge_star'))
      }
    ], { backgroundColor: Color.Orange, barStyle: BarStyle.STACK })
    // Bind the component to nested scrollable containers.
    .bindToNestedScrollable([{ parent: this.scrollScroller, child: this.listScroller }])
  }
}

@Component
struct MyPageTwo {
  private listScroller: Scroller = new Scroller();
  private arr: number[] = [];

  aboutToAppear(): void {
    for (let i = 0; i < 30; i++) {
      this.arr.push(i);
    }
  }

  build() {
    NavDestination() {
      List({ scroller: this.listScroller }) {
        ForEach(this.arr, (item: number, index: number) => {
          ListItem() {
            Text('' + item)
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .width('90%')
              .margin({ left: '5%' })
              .borderRadius(10)
              .backgroundColor(Color.Gray)
          }
        }, (item: string) => item);
      }.width('100%')
    }
    .title('PageTwo', { backgroundColor: Color.Yellow, barStyle: BarStyle.STACK })
    .toolbarConfiguration([
      {
        // Replace $r('sys.symbol.phone_badge_star') with the resource file you use.
        value: 'item1',
        symbolIcon: new SymbolGlyphModifier($r('sys.symbol.phone_badge_star'))
      }
    ], { backgroundColor: Color.Orange, barStyle: BarStyle.STACK })
    // Bind the component to a scrollable container.
    .bindToScrollable([this.listScroller])
  }
}

@Entry
@Component
struct Index {
  private stack: NavPathStack = new NavPathStack();

  @Builder
  MyPageMap(name: string) {
    if (name === 'myPageOne') {
      MyPageOne();
    } else {
      MyPageTwo();
    }
  }

  build() {
    Navigation(this.stack) {
      Column() {
        Button('push PageOne').onClick(() => {
          this.stack.pushPath({ name: 'myPageOne' });
        })
        Button('push PageTwo').onClick(() => {
          this.stack.pushPath({ name: 'myPageTwo' });
        })
      }.height('40%').justifyContent(FlexAlign.SpaceAround)
    }.width('100%')
    .height('100%')
    .title({ main: 'MainTitle', sub: 'subTitle' })
    .navDestination(this.MyPageMap)
  }
}

navdestination_bind_scrollable

Example 2: Setting a Custom Transitions for the NavDestination Component

The following example demonstrates how to set a custom transition animation for the NavDestination component using customTransition.

@Entry
@Component
struct NavDestinationCustomTransition {
  stack: NavPathStack = new NavPathStack();

  @Builder
  pageMap(name: string) {
    if (name) {
      NavDest();
    }
  }

  aboutToAppear(): void {
    this.stack.pushPath({name: 'dest0'});
  }

  build() {
    Navigation(this.stack) {
      // empty
    }
    .navDestination(this.pageMap)
    .hideNavBar(true)
    .title('Main Page')
    .titleMode(NavigationTitleMode.Mini)
  }
}

declare type voidFunc = () => void;

@Component
struct NavDest {
  @State name: string = 'NA';
  @State destWidth: string = '100%';
  stack: NavPathStack = new NavPathStack();
  @State translateY: string = '0';

  @Builder
  titleBuilder() {
    Text(this.name)
      .fontSize(20)
      .height(55)
      .fontWeight(FontWeight.Bold)
      .width('100%')
      .padding({ left: 16, right: 16 })
  }

  build() {
    NavDestination() {
      Column() {
        Button('push next page', { stateEffect: true, type: ButtonType.Capsule })
          .width('80%')
          .height(40)
          .margin(20)
          .onClick(() => {
            this.stack.pushPath({ name: this.name == 'PageOne' ? "PageTwo" : "PageOne" });
          })
      }
      .size({ width: '100%', height: '100%' })
    }
    .title(this.titleBuilder)
    .translate({ y: this.translateY })
    .onReady((context) => {
      this.name = context.pathInfo.name;
      this.stack = context.pathStack;
    })
    .backgroundColor(this.name == 'PageOne' ? '#F1F3F5' : '#ff11dee5')
    .customTransition(
      (op: NavigationOperation, isEnter: boolean)
        : Array<NavDestinationTransition> | undefined => {
        console.info('[NavDestinationTransition]', 'reached delegate in frontend, op: ' + op + ', isEnter: ' + isEnter);

        let transitionOneEvent: voidFunc = () => { console.info('[NavDestinationTransition]', 'reached transitionOne, empty now!'); }
        let transitionOneFinishEvent: voidFunc = () => { console.info('[NavDestinationTransition]', 'reached transitionOneFinish, empty now!'); }
        let transitionOneDuration: number = 500;
        if (op === NavigationOperation.PUSH) {
          if (isEnter) {
            // ENTER_PUSH
            this.translateY = '100%';
            transitionOneEvent = () => {
              console.info('[NavDestinationTransition]', 'transitionOne, push & isEnter');
              this.translateY = '0';
            }
          } else {
            // EXIT_PUSH
            this.translateY = '0';
            transitionOneEvent = () => {
              console.info('[NavDestinationTransition]', 'transitionOne, push & !isEnter');
              this.translateY = '0';
            }
            transitionOneDuration = 450;
          }
        } else if (op === NavigationOperation.POP) {
          if (isEnter) {
            // ENTER_POP
            this.translateY = '0';
            transitionOneEvent = () => {
              console.info('[NavDestinationTransition]', 'transitionOne, pop & isEnter');
              this.translateY = '0';
            }
          } else {
            // EXIT_POP
            this.translateY = '0';
            transitionOneEvent = () => {
              console.info('[NavDestinationTransition]', 'transitionOne, pop & !isEnter');
              this.translateY = '100%';
            }
          }
        }

        let transitionOne: NavDestinationTransition = {
          duration: transitionOneDuration,
          delay: 0,
          curve: Curve.Friction,
          event: transitionOneEvent,
          onTransitionEnd: transitionOneFinishEvent
        };

        let transitionTwoEvent: voidFunc = () => { console.info('[NavDestinationTransition]', 'reached transitionTwo, empty now!'); }
        let transitionTwo: NavDestinationTransition = {
          duration: 1000,
          delay: 0,
          curve: Curve.EaseInOut,
          event: transitionTwoEvent,
          onTransitionEnd: () => { console.info('[NavDestinationTransition]', 'reached Two\'s finish'); }
        };

        return [
          transitionOne,
          transitionTwo,
        ];
      })
  }
}

navdestination_custom_transition

Example 3: Setting System Transition Animations for the NavDestination Component

The following example demonstrates how to set system transition animations using systemTransition with Fade, Explode, SlideBottom, and SlideRight effects.

@Entry
@Component
struct NavDestinationSystemTransition {
  @Provide stack: NavPathStack = new NavPathStack()
  @Provide homePageTransitionType: NavigationSystemTransitionType = NavigationSystemTransitionType.DEFAULT;

  @Builder
  pageMap(name: string) {
    if (name === 'Fade') {
      Fade();
    } else if (name === 'Explode') {
      Explode();
    } else if (name === 'SlideRight') {
      SlideRight();
    } else if (name === 'SlideBottom') {
      SlideBottom();
    } else {
      Dest();
    }
  }

  aboutToAppear(): void {
    this.stack.pushPath({name: 'Dest'});
  }

  build() {
    Navigation(this.stack) {
      // empty
    }
    .navDestination(this.pageMap)
    .hideNavBar(true)
  }
}

@Component
struct Dest {
  @Consume stack: NavPathStack;
  @Consume homePageTransitionType: NavigationSystemTransitionType;
  @State name: string = 'NA';

  build() {
    NavDestination() {
      HomeBody();
    }
    .title('Navigation System Animation')
    .onReady((context) => {
      this.name = context.pathInfo.name;
    })
    .systemTransition(this.homePageTransitionType)
  }
}

@Component
struct Fade {
  @Consume stack: NavPathStack;
  @State name: string = 'NA';

  build() {
    NavDestination() {
      DestBody({
        name: this.name
      })
    }
    .title(this.name)
    .onReady((context) => {
      this.name = context.pathInfo.name;
    })
    .systemTransition(NavigationSystemTransitionType.FADE)
  }
}

@Component
struct Explode {
  @Consume stack: NavPathStack;
  @State name: string = 'NA';

  build() {
    NavDestination() {
      DestBody({
        name: this.name
      })
    }
    .title(this.name)
    .onReady((context) => {
      this.name = context.pathInfo.name;
    })
    .systemTransition(NavigationSystemTransitionType.EXPLODE)
  }
}

@Component
struct SlideRight {
  @Consume stack: NavPathStack;
  @State name: string = 'NA';

  build() {
    NavDestination() {
      DestBody({
        name: this.name
      })
    }
    .title(this.name)
    .onReady((context) => {
      this.name = context.pathInfo.name;
    })
    .systemTransition(NavigationSystemTransitionType.SLIDE_RIGHT)
  }
}

@Component
struct SlideBottom {
  @Consume stack: NavPathStack;
  @State name: string = 'NA';

  build() {
    NavDestination() {
      DestBody({
        name: this.name
      })
    }
    .title(this.name)
    .onReady((context) => {
      this.name = context.pathInfo.name;
    })
    .systemTransition(NavigationSystemTransitionType.SLIDE_BOTTOM)
  }
}

@Component
struct DestBody {
  name: string = 'NA';

  columnTextSize: number = 22;
  columnTextFontWeight: FontWeight = FontWeight.Bolder;
  columnWidth: string = '65%';
  columnPadding: number = 22;
  columnMargin: number = 10;
  columnBorderRadius: number = 10;

  build() {
    Column() {
      Column()
        .width('85')
        .height(50)
        .backgroundColor(Color.White)
      Column() {
        Text(this.name)
          .fontSize(this.columnTextSize)
          .fontWeight(this.columnTextFontWeight)
      }
      .width(this.columnWidth)
      .padding(this.columnPadding)
      .margin(this.columnMargin)
      .borderRadius(this.columnBorderRadius)
      .shadow(ShadowStyle.OUTER_DEFAULT_LG)
    }
  }
}

@Component
struct HomeBody {
  @Consume stack: NavPathStack;
  @Consume homePageTransitionType: NavigationSystemTransitionType;

  columnTextSize: number = 22;
  columnTextFontWeight: FontWeight = FontWeight.Bolder;
  columnWidth: string = '85%';
  columnPadding: number = 22;
  columnMargin: number = 10;
  columnBorderRadius: number = 10;
  columnShadow: ShadowStyle = ShadowStyle.OUTER_DEFAULT_MD;

  build() {
    Column() {
      Search({ value: 'Search' })
        .width(this.columnWidth)

      Column() {
        Text('fade')
          .fontSize(this.columnTextSize)
          .fontWeight(this.columnTextFontWeight)
      }
      .width(this.columnWidth)
      .padding(this.columnPadding)
      .margin(this.columnMargin)
      .borderRadius(this.columnBorderRadius)
      .shadow(this.columnShadow)
      .onClick(() => {
        this.homePageTransitionType = NavigationSystemTransitionType.FADE;
        this.stack.pushPath({name: 'Fade'});
      })

      Column() {
        Text('explode')
          .fontSize(this.columnTextSize)
          .fontWeight(this.columnTextFontWeight)
      }
      .width(this.columnWidth)
      .padding(this.columnPadding)
      .margin(this.columnMargin)
      .borderRadius(this.columnBorderRadius)
      .shadow(this.columnShadow)
      .onClick(() => {
        this.homePageTransitionType = NavigationSystemTransitionType.EXPLODE;
        this.stack.pushPath({name: 'Explode'});
      })

      Column() {
        Text('slide right')
          .fontSize(this.columnTextSize)
          .fontWeight(this.columnTextFontWeight)
      }
      .width(this.columnWidth)
      .padding(this.columnPadding)
      .margin(this.columnMargin)
      .borderRadius(this.columnBorderRadius)
      .shadow(this.columnShadow)
      .onClick(() => {
        this.homePageTransitionType = NavigationSystemTransitionType.SLIDE_RIGHT;
        this.stack.pushPath({name: 'SlideRight'});
      })

      Column() {
        Text('slide bottom')
          .fontSize(this.columnTextSize)
          .fontWeight(this.columnTextFontWeight)
      }
      .width(this.columnWidth)
      .padding(this.columnPadding)
      .margin(this.columnMargin)
      .borderRadius(this.columnBorderRadius)
      .shadow(this.columnShadow)
      .onClick(() => {
        this.homePageTransitionType = NavigationSystemTransitionType.SLIDE_BOTTOM;
        this.stack.pushPath({name: 'SlideBottom'});
      })
    }
  }
}

navdestination_fade

navdestination_explode

navdestination_slide_bottom

navdestination_slide_right

This example demonstrates how to configure each NavDestination component with specific display orientations and control the visibility of the status bar and navigation bar.

import { window } from '@kit.ArkUI';

@Component
struct PortraitPage {
  @State info: string = '';
  private stack: NavPathStack | undefined = undefined;
  build() {
    NavDestination() {
      Stack({alignContent: Alignment.Center}) {
        Button('push LANDSCAPE page').onClick(() => {
          this.stack?.pushPath({name: 'landscape'});
        })
      }.width('100%').height('100%')
    }
    .width('100%').height('100%')
    .title('PortraitPage')
    .preferredOrientation(window.Orientation.PORTRAIT) // Portrait orientation.
    .enableStatusBar (true) // Show the status bar.
    .enableNavigationIndicator(true) // Show the navigation bar.
    .backgroundColor('#ffbaece9')
    .onResult((result: ESObject)=>{
      this.info = result as string;
    })
    .onReady((ctx: NavDestinationContext) => {
      this.stack = ctx.pathStack;
    })
  }
}

@Component
struct LandscapePage {
  private stack: NavPathStack | undefined = undefined;
  build() {
    NavDestination() {
      Stack({alignContent: Alignment.Center}) {
        Button('push PORTRAIT page').onClick(() => {
          this.stack?.pushPath({name: 'portrait'});
        })
      }.width('100%').height('100%')
    }
    .width('100%').height('100%')
    .title('LandscapePage')
    .preferredOrientation(window.Orientation.LANDSCAPE) // Landscape orientation.
    .enableStatusBar(false) // Hide the status bar.
    .enableNavigationIndicator(false) // Hide the navigation bar.
    .backgroundColor('#ffecb8b8')
    .ignoreLayoutSafeArea([LayoutSafeAreaType.SYSTEM], [LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM])
    .onReady((ctx: NavDestinationContext) => {
      this.stack = ctx.pathStack;
    })
  }
}

@Entry
@Component
struct ExamplePage {
  private stack: NavPathStack = new NavPathStack();

  aboutToAppear(): void {
    this.stack.pushPath({name: "portrait"});
  }

  @Builder
  MyPageMap(name: string) {
    if (name === 'portrait') {
      PortraitPage();
    } else {
      LandscapePage();
    }
  }

  build() {
    Navigation(this.stack) {
    }
    .width('100%')
    .height('100%')
    .hideNavBar(true)
    .navDestination(this.MyPageMap)
  }
}

navdestination_orientation

Example 5: Handling NavDestination onActive and onInActive Lifecycle Events

Starting from API version 17, the NavDestination component includes the onActive and onInactive lifecycle events. This example demonstrates various triggering scenarios for the onActive and onInactive lifecycle callbacks.

import { promptAction, ComponentContent, OverlayManager } from '@kit.ArkUI';

class Params {
  text: string = "";
  offset: Position;

  constructor(text: string, offset: Position) {
    this.text = text;
    this.offset = offset;
  }
}

let overlayShownTag: boolean = false;

@Builder
function builderText(params: Params) {
  Column() {
    Text('I am ' + params.text)
      .fontWeight(FontWeight.Bolder)
      .align(Alignment.Center)
      .fontSize(25)
      .offset({ y: '10%' })
  }
  .backgroundColor(params.text === 'overlay' ? '#ffc' : '#ccf')
  .width('100%')
  .height('100%')
  .offset(params.offset)
}

@Entry
@Component
struct Index {
  stack: NavPathStack = new NavPathStack();

  @Builder
  pageMap(name: string) {
    if (name === 'standard' || name === 'Home') {
      NavDest({
        name: name
      })
    }
    else if (name === 'dialog') {
      NavDest({
        name: name,
        mode: NavDestinationMode.DIALOG,
        positionY: '40%'
      })
    }
  }

  aboutToAppear(): void {
    this.stack.pushPath({name: 'Home'});
  }

  build() {
    Navigation(this.stack) {

    }
    .hideNavBar(true)
    .navDestination(this.pageMap)
  }
}

@Component
struct NavDest {
  @State positionY: string = '0%';
  name: string = 'NA';
  mode: NavDestinationMode = NavDestinationMode.STANDARD;

  build() {
    NavDestination() {
      NavBody()
    }
    .backgroundColor(this.mode === NavDestinationMode.DIALOG ? Color.Pink : undefined)
    .height(this.mode === NavDestinationMode.DIALOG ? '65%' : '100%')
    .mode(this.mode)
    .title(this.name)
    .position({ y: this.positionY })
    .onActive((reason: NavDestinationActiveReason) => {
      let onActiveMsg: string = `[activeTest] ${this.name} onActive, reason: ${reason}`;
      console.info(onActiveMsg);
      // Use promptAction.showToast for API version 17, and promptAction.openToast for API version 18 or later.
      promptAction.openToast({ message: onActiveMsg }).catch(() => {
        console.info('open toast failed');
      });
    })
    .onInactive((reason: NavDestinationActiveReason) => {
      let onInActiveMsg: string = `[activeTest] ${this.name} onInactive, reason: ${reason}`;
      console.info(onInActiveMsg);
      // Use promptAction.showToast for API version 17, and promptAction.openToast for API version 18 or later.
      promptAction.openToast({ message: onInActiveMsg }).catch(() => {
        console.info('open toast failed');
      });
    })
    .onBackPressed(() => {
      if (overlayShownTag) {
        overlayShownTag = false;
        this.getUIContext().getOverlayManager().hideAllComponentContents();
        return true;
      }
      return false;
    })
  }
}

@Component
struct NavBody {
  @State isShow: boolean = false;
  @State isBindSheetShow: boolean = false;
  stack: NavPathStack = new NavPathStack();

  aboutToAppear(): void {
    this.stack = this.queryNavigationInfo()?.pathStack!;
  }

  @Builder
  myBuilder(id: string) {
    Column() {
      Text('I am ' + id)
        .fontWeight(FontWeight.Bolder)
        .align(Alignment.Center)
        .fontSize(25)
        .offset({ y: '10%' })
    }
    .width('100%')
    .height('100%')
  }

  build() {
    Column() {
      Row() {
        Button('pushPath standard')
          .margin(5)
          .onClick(() => {
            this.stack.pushPath({name: 'standard'});
          })
        Button('pushPath dialog')
          .margin(5)
          .onClick(() => {
            this.stack.pushPath({name: 'dialog'});
          })
      }
      Column() {
        Row() {
          Button("open Modal")
            .onClick(() => {
              this.isShow = true;
            })
            .fontColor(Color.Black)
            .backgroundColor('#ccc')
            .margin(5)
            .bindContentCover(
              this.isShow,
              this.myBuilder('modal'), {
                backgroundColor: '#fcf',
                onDisappear: () => {
                  this.isShow = false;
                }
              })
          Button("open BindSheet")
            .onClick(() => {
              this.isBindSheetShow = true;
            })
            .fontColor(Color.Black)
            .backgroundColor('#ccc')
            .margin(5)
            .bindSheet($$this.isBindSheetShow, this.myBuilder('bindSheet'), {
              height: '60%',
              backgroundColor: '#cfc'
            })
        }
        Row() {
          Button("open Dialog")
            .onClick(() => {
              let componentContent = new ComponentContent(
                this.getUIContext(), wrapBuilder<[Params]>(builderText),
                new Params('dialog', {y: '10%'}));
              this.getUIContext().getPromptAction().openCustomDialog(componentContent)
                .then(() => {
                  console.info('[activeTest] open custom dialog success');
                })
                .catch(() => {
                  console.info('[activeTest] open custom dialog failed');
                })
            })
            .fontColor(Color.Black)
            .backgroundColor('#ccc')
            .margin(5)
          Button("open Overlay")
            .onClick(() => {
              let componentContent = new ComponentContent(
                this.getUIContext(), wrapBuilder<[Params]>(builderText),
                new Params('overlay', {y: '10%'}));
              this.getUIContext().getOverlayManager().addComponentContent(componentContent);
              this.getUIContext().getOverlayManager().showComponentContent(componentContent);
              overlayShownTag = true;
            })
            .fontColor(Color.Black)
            .backgroundColor('#ccc')
            .margin(5)
        }
      }
      .width('95%')
    }
    .width('100%')
    .height('100%')
  }
}

navdestination_active_inactive_demo

For more usage of the NavDestination component, see Example in Navigation.

NavDestination

Child Components

APIs

Attributes

title

hideTitleBar

hideTitleBar13+

toolbarConfiguration13+

hideToolBar13+

mode11+

backButtonIcon11+

backButtonIcon19+

menus12+

menus19+

ignoreLayoutSafeArea12+

systemBarStyle12+

systemTransition14+

recoverable14+

bindToScrollable14+

bindToNestedScrollable14+

hideBackButton15+

customTransition15+

preferredOrientation19+

enableStatusBar19+

enableNavigationIndicator19+

NavDestinationMode11+

NavigationSystemTransitionType14+

Events

onShown10+

onHidden10+

onWillAppear12+

onWillShow12+

onWillHide12+

onWillDisappear12+

onBackPressed10+

onReady11+

onResult15+

onActive17+

onInactive17+

onNewParam19+

NavDestinationCommonTitle

NavDestinationCustomTitle

NavDestinationContext11+

getConfigInRouteMap12+

RouteMapConfig12+

NestedScrollInfo14+

NavDestinationActiveReason17+

VisibilityChangeReason21+

NavDestinationTransition15+

NavDestinationTransitionDelegate15+

Orientation19+

Example

Example 1: Linking the Title Bar and Toolbar with Scrollable Components

Example 2: Setting a Custom Transitions for the NavDestination Component

Example 3: Setting System Transition Animations for the NavDestination Component

Example 4: Configuring Display Orientation and Status Bar and Navigation Bar Visibility

Example 5: Handling NavDestination onActive and onInActive Lifecycle Events

hideTitleBar¹³⁺

toolbarConfiguration¹³⁺

hideToolBar¹³⁺

mode¹¹⁺

backButtonIcon¹¹⁺

backButtonIcon¹⁹⁺

menus¹²⁺

menus¹⁹⁺

ignoreLayoutSafeArea¹²⁺

systemBarStyle¹²⁺

systemTransition¹⁴⁺

recoverable¹⁴⁺

bindToScrollable¹⁴⁺

bindToNestedScrollable¹⁴⁺

hideBackButton¹⁵⁺

customTransition¹⁵⁺

preferredOrientation¹⁹⁺

enableStatusBar¹⁹⁺

enableNavigationIndicator¹⁹⁺

NavDestinationMode¹¹⁺

NavigationSystemTransitionType¹⁴⁺

onShown¹⁰⁺

onHidden¹⁰⁺

onWillAppear¹²⁺

onWillShow¹²⁺

onWillHide¹²⁺

onWillDisappear¹²⁺

onBackPressed¹⁰⁺

onReady¹¹⁺

onResult¹⁵⁺

onActive¹⁷⁺

onInactive¹⁷⁺

onNewParam¹⁹⁺

NavDestinationContext¹¹⁺

getConfigInRouteMap¹²⁺

RouteMapConfig¹²⁺

NestedScrollInfo¹⁴⁺

NavDestinationActiveReason¹⁷⁺

VisibilityChangeReason²¹⁺

NavDestinationTransition¹⁵⁺

NavDestinationTransitionDelegate¹⁵⁺

Orientation¹⁹⁺