Subpage

NavDestination is the root container for Navigation subpages and is used to hold special attributes as well as lifecycles of subpages. You can set separate attributes such as the title bar and menu bar for NavDestination, in the same way you set attributes for Navigation. You can also set different display modes for NavDestination through the mode attribute to meet different page requirements.

Page Display Mode

NavDestination is divided into two modes:

• Standard mode

  By default, subpages in the NavDestination component are in standard mode, which corresponds to the NavDestinationMode.STANDARD value of the mode attribute. Only one standard NavDestination page can be displayed in Navigation.

• Dialog mode

  With mode set to NavDestinationMode.DIALOG, a NavDestination is displayed transparently by default. The appearance and disappearance of the NavDestination in dialog mode do not affect the display and lifecycle of the underlying NavDestination in standard mode, and both can be displayed at the same time.

  // Dialog NavDestination
  @Entry
  @Component
  struct PageDisplayType {
    @Provide('NavPathStack') pageStack: NavPathStack = new NavPathStack();
  
    @Builder
    PagesMap(name: string) {
      if (name == 'DialogPage') {
        DialogPage();
      }
    }
  
    build() {
      Navigation(this.pageStack) {
        Button('Push DialogPage')
          .margin(20)
          .width('80%')
          .onClick(() => {
            this.pageStack.pushPathByName('DialogPage', '');
          })
      }
      .mode(NavigationMode.Stack)
      .title('Main')
      .navDestination(this.PagesMap)
    }
  }
  
  @Component
  export struct DialogPage {
    @Consume('NavPathStack') pageStack: NavPathStack;
  
    build() {
      NavDestination() {
        Stack({ alignContent: Alignment.Center }) {
          Column() {
            Text('Dialog NavDestination')
              .fontSize(20)
              .margin({ bottom: 100 })
            Button('Close').onClick(() => {
              this.pageStack.pop();
            }).width('30%')
          }
          .justifyContent(FlexAlign.Center)
          .backgroundColor(Color.White)
          .borderRadius(10)
          .height('30%')
          .width('80%')
        }.height('100%').width('100%')
      }
      .backgroundColor('rgba(0,0,0,0.5)')
      .hideTitleBar(true)
      .mode(NavDestinationMode.DIALOG)
    }
  }
  

  PageDisplayType.ets

  

Page Lifecycle

The lifecycle of Navigation can be divided into three categories: custom component lifecycle, universal component lifecycle, and NavDestination lifecycle. aboutToAppear and aboutToDisappear are the lifecycle callbacks of custom components (custom components contained in the outer layer of NavDestination); onAppear and onDisappear are universal component lifecycle callbacks. The remaining lifecycle events are unique to NavDestination.

The sequence of these lifecycle events is illustrated in the figure below.

• aboutToAppear: invoked when the custom component is about to appear. Specifically, it is invoked after a new instance of the custom component is created and before its build() function is executed (before the creation of NavDestination). You can change state variables in this callback, and the changes take effect in the subsequent execution of build().
• onWillAppear: invoked after the NavDestination component is created and before it is mounted to the component tree. Changing the state variable in this callback takes effect in the current frame.
• onAppear: invoked when the NavDestination component is mounted to the component tree. It is a universal lifecycle event.
• onWillShow: invoked before the NavDestination component layout is displayed. In this case, the page is invisible. (This callback is not invoked when the application is switched to the foreground.)
• onShown: invoked after the NavDestination component layout is displayed. At this time, the page layout is complete.
• onActive: invoked when the NavDestination component becomes active (on top of the stack and operable, with no special components blocking it).
• onWillHide: invoked when the NavDestination component is about to be hidden (it is not invoked when the application is switched to the background).
• onInactive: invoked when the NavDestination component becomes inactive (not on top of the stack and inoperable, or on top but blocked by special components).
• onHidden: invoked after the NavDestination component is hidden (when a non-top page is pushed into the stack, the top page pops out of the stack, or the application is switched to the background).
• onWillDisappear: invoked before the NavDestination component is about to be destroyed. If there is a transition animation, this callback is invoked before the animation (when the top page of the stack pops out of the stack).
• onDisAppear: invoked when the NavDestination component is unloaded and destroyed from the component tree. It is a universal lifecycle event.
• aboutToDisappear: invoked before the custom component is destroyed. The state variable cannot be changed in this callback.

In addition, there are two special lifecycle callbacks:

• onResult: invoked when other NavDestination pages are popped, or when the user swipes left/right to return from another NavDestination page.
• onNewParam: invoked when a NavDestination page that previously exists in the stack is moved to the top of the stack through launchMode.MOVE_TO_TOP_SINGLETON or launchMode.POP_TO_SINGLETON.

Page Listening and Query

To facilitate the decoupling of components from pages, custom components within NavDestination subpages can listen for or query some page status information through global APIs.

• Page information query

  Custom components provide the queryNavDestinationInfo API, which can be used to query the information of the current page within NavDestination. The return value is NavDestinationInfo. If the query fails, the return value is undefined.

  import { uiObserver } from '@kit.ArkUI';
  
  // Custom components within NavDestination
  @Component
  struct MyComponent {
    navDesInfo: uiObserver.NavDestinationInfo | undefined;
    context = this.getUIContext().getHostContext();
  
    aboutToAppear() {
      this.navDesInfo = this.queryNavDestinationInfo();
    }
  
    build() {
      // ...
        Column() {
          // The value in the $r('app.string.onPageName') resource file is "Page name:".
          Text(this.context!.resourceManager.getStringSync($r('app.string.onPageName').id) + `${this.navDesInfo?.name}`)
        }.width('100%').height('100%')
        // ...
    }
  }
  

  Index.ets

• Page status listening

  You can register a listener for NavDestination lifecycle changes using the observer.on('navDestinationUpdate') API.

  Alternatively, you can register a callback for page transition states through observer.on('navDestinationSwitch'). This callback can be used to obtain page information during route changes using NavDestinationSwitchInfo. This registration supports different scopes: UIAbilityContext and UIContext.