NavDestination is the root container of a destination page and represents the content area of the Navigation component.
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 a page in the middle of the navigation stack changes, the lifecycle of the destination page at the top of the stack before the transition (onWillShow, onShown, onHidden, onWillDisappear) and the lifecycle of the destination page after the transition (onWillShow, onShown, onHidden, onWillDisappear) are both triggered at the end.
Built-in components and custom components are allowed, with support for (if/else, ForEach, and LazyForEach) rendering control.
Number of child components: multiple.
NavDestination()
Atomic service API: This API can be used in atomic services since API version 11.
The universal attributes are supported.
Avoid setting layout-related attributes such as the position and size. They may result in display issues on the page.
title(value: string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle, options?: NavigationTitleOptions)
Sets the page title. When the NavigationCustomTitle type is used to set the height, the titleMode attribute 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 with an ellipsis (...); (2) If a subtitle is set, the subtitle is scaled down and then clipped with an ellipsis (...).
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 | Yes | Page title. |
| options12+ | NavigationTitleOptions | No | Title bar options. |
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: Display the title bar. |
mode(value: NavDestinationMode)
Sets the type of the navigation destination page. Dynamic modification is not supported.
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 navigation destination page. Default value: NavDestinationMode.STANDARD |
backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)
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.
Sets the icon of the back button on the title bar.
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 | SymbolGlyphModifier12+ | Yes | Icon of the back button on the title bar. |
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.
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] |
After LayoutSafeArea is set:
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 must have an absolute vertical offset between 0 and 100 to extend into 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.
systemBarStyle(style: Optional<SystemBarStyle>)
Sets the style of the system status bar when this NavDestination page is displayed in the Navigation component.
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. |
onShown(callback: () => void)
Called when the navigation destination page is displayed.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
onWillAppear(callback: Callback<void>)
Called when the navigation destination is about to be mounted. You can change the navigation stack in this callback function, and the change takes effect in the current frame.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
onWillShow(callback: Callback<void>)
Called when the navigation destination is about to be displayed.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
onWillHide(callback: Callback<void>)
Called when the navigation destination is about to be hidden.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
onWillDisappear(callback: Callback<void>)
Called when the navigation destination is about to be unmounted (or when the transition animation, if any, is about to start).
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
onBackPressed(callback: () => boolean)
This callback takes effect when there is one or more entries in the navigation stack bound to the Navigation component. Called 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
onReady(callback: Callback<NavDestinationContext>)
Called when the NavDestination component is about to build a child component.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
getConfigInRouteMap(): RouteMapConfig |undefined
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 | Route map configuration of the current page. |
| undefined | undefined, returned when the page is not configured through the route table. |