目录

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 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

  • 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.

[h2]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.

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 | Resource14+ 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: Show the title bar.

[h2]hideTitleBar13+

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.

[h2]toolbarConfiguration13+

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

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

  • 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.

[h2]hideToolBar13+

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.

[h2]mode11+

mode(value: NavDestinationMode)

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

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.

[h2]backButtonIcon11+

backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)

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

  • 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 | SymbolGlyphModifier12+ Yes Icon of the back button on the title bar.

[h2]backButtonIcon19+

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

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

  • 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.

[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.

  • 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]

[h2]systemBarStyle12+

systemBarStyle(style: Optional<SystemBarStyle>)

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

  • 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.

[h2]systemTransition14+

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.

[h2]recoverable14+

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.

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.

[h2]bindToScrollable14+

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.

  • 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.

[h2]bindToNestedScrollable14+

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.

  • 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.

[h2]hideBackButton15+

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.

[h2]customTransition15+

customTransition(delegate: NavDestinationTransitionDelegate)

Sets 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

Parameters

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

[h2]preferredOrientation19+

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.

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

    1. The NavDestination component belongs to the application's main window page, and the main window is a full-screen window.
    2. The Navigation container containing the NavDestination component occupies the entire application page area.
    3. 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.

[h2]enableStatusBar19+

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

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

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

    1. The NavDestination component belongs to the application's main window page, and the main window is a full-screen window.
    2. The Navigation container containing the NavDestination component occupies the entire page area.
    3. The NavDestination component occupies the entire Navigation container.
    4. 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.

[h2]enableNavigationIndicator19+

enableNavigationIndicator(enabled: Optional<boolean>)

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

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

  1. The NavDestination component belongs to the application's main window page, and the main window is a full-screen window.
  2. The Navigation container containing the NavDestination component occupies the entire page area.
  3. The NavDestination component occupies the entire Navigation container.
  4. 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.

Events

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

[h2]onShown10+

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>21+ 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.

[h2]onHidden10+

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>21+ 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.

[h2]onWillAppear12+

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.

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.

[h2]onWillShow12+

onWillShow(callback: Callback<void>)

Called when the NavDestination component is about to display.

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.

[h2]onWillHide12+

onWillHide(callback: Callback<void>)

Called when the NavDestination component is about to be hidden.

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.

[h2]onWillDisappear12+

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).

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).

[h2]onBackPressed10+

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.

[h2]onReady11+

onReady(callback: Callback<NavDestinationContext>)

Triggered when the NavDestination component is about to build a child 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 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.

[h2]onResult15+

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

Triggered when the NavDestination component returns.

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.

[h2]onActive17+

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.

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.

[h2]onInactive17+

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.

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.

[h2]onNewParam19+

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.

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.

[h2]getConfigInRouteMap12+

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.

RouteMapConfig12+

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.

NestedScrollInfo14+

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.

[h2]VisibilityChangeReason21+

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.

Orientation19+

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

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

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)
  }
}

[h2]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,
        ];
      })
  }
}

[h2]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'});
      })
    }
  }
}

[h2]Example 4: Configuring Display Orientation and Status Bar and Navigation Bar Visibility

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)
  }
}

[h2]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%')
  }
}

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