目录

NavDestination

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.

Child Components

Built-in components and custom components are allowed, with support for (if/else, ForEach, and LazyForEach) rendering control.

Number of child components: multiple.

APIs

NavDestination()

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

Attributes

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.

[h2]title

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.

[h2]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: Display the title bar.

[h2]mode 11+

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

[h2]backButtonIcon11+

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.

[h2]ignoreLayoutSafeArea12+

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.

[h2]systemBarStyle12+

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.
  1. The setting takes effect only when the NavDestination component is used in conjunction with the Navigation component.
  2. For other usage restrictions, see the description of systemBarStyle for the Navigation component.

Events

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

[h2]onShown10+

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

[h2]onHidden10+

onHidden(callback: () => void)

Called when the navigation destination page is hidden.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

[h2]onWillAppear12+

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

[h2]onWillShow12+

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

[h2]onWillHide12+

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

[h2]onWillDisappear12+

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

[h2]onBackPressed10+

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

[h2]onReady11+

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

[h2]getConfigInRouteMap12+

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.

RouteMapConfig12+

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

Name Type Description
name string Page name.
pageSourceFile string Path of the page in the current package.
data object Custom data of the page.

Example

For details, see Example in Navigation.