Page Routing

Navigation-related routing operations are all based on the APIs provided by the navigation controller NavPathStack. For each Navigation component, a NavPathStack object must be created and passed to manage pages. NavPathStack mainly provides page navigation, page return, page replacement, page deletion, parameter acquisition, and route interception.

In API version 9, the Navigation component must be used together with the NavRouter component for page routing. Since API version 10, NavPathStack is recommended for page routing.

Key concepts related to routing:

Routing table: defines the mapping between page names and NavDestination pages. If the page name passed during navigation is not registered in the routing table, the navigation fails. The system provides system routing table and custom routing table to implement navigation.
Navigation stack: NavDestination pages are managed in a stack structure. Each Navigation has its own navigation stack, which cannot be shared. The navigation stack is controlled by NavPathStack. You can obtain the complete navigation stack information through NavPathStack.getPathStack.
Page transition: Navigation provides the page transition animations by default. You can customize the transition animations.

NOTE

NavPathStack and Navigation must map to each other and cannot be reused.

NavPathStack mainly controls NavDestination page redirection and deletion. It cannot directly operate the NavBar (navigation bar). If navigation to the NavBar page is required, you can only clear the navigation stack using the clear API.

Avoid relying on lifecycle event listeners to manage the navigation stack. Instead, you can query the navigation stack through NavPathStack.getPathStack.

When the application is in the background, calling stack operation APIs of NavPathStack will trigger a refresh upon the application's return to the foreground.

You should first create a Navigation as the navigation root container and create a NavPathStack object as the input parameter for the Navigation component to bind them. Subsequent routing operations are performed based on the NavPathStack.

@Entry
@Component
struct Index {
  // Create a navigation controller object and pass it to the Navigation component.
  pageStack: NavPathStack = new NavPathStack();
  // ...
  build() {
    Navigation(this.pageStack) {
      // ...
    }.title('Main')
  }
}

Index.ets

Building a Subpage

Declare the instantiation method for each NavDestination, for example, PageOneBuilder in the code. Executing this method creates a custom component of PageOne, which is a subpage of Navigation.

@Builder
export function PageOneBuilder(name: string, param: string) {
  PageOne({ name: name, value: param });
}

@Component
export struct PageOne {
  navPathStack: NavPathStack = new NavPathStack();
  name: string = '';
  @State value: string = '';
  context = this.getUIContext().getHostContext();

  build() {
    NavDestination() {
      // ...
    }.title(`${this.name}`)
    // ...
  }
}

NavigationExampleOne.ets

Configuring a Routing Table

The system provides system routing table and custom routing table. The former is used as an example. Register the instantiation method written in the subpage with its name (customized) in the routing table configuration file, which should be created in entry/src/main/resources/base/profile/router_map.json.

{
  "routerMap": [
    {
      "name": "basicPageOne", // Unique identifier of the route page
      "pageSourceFile": "src/main/ets/pages/PageOne.ets", // Path of the source code
      "buildFunction": "PageOneBuilder" // Name of the instantiation method of the page
    }
  ]
}

After creating a routing table, register it with the project by configuring "routerMap": "$profile:router_map" in the module field of the project configuration file module.json5.

Routing Operations

After the Navigation root container, subpages, and routing table are configured, you can call the NavPathStack API to navigate between pages. As mentioned above, there is only one NavPathStack object in a Navigation container. To perform routing operations on a subpage, you need to obtain the NavPathStack object in either of the following ways:

Method 1: Use AppStorage to store and obtain the object.

@Entry
@Component
struct NavigationPage {
  navStack: NavPathStack = new NavPathStack();

  aboutToAppear(): void {
    AppStorage.setOrCreate<NavPathStack>('basicNavigationStack', this.navStack);
    // ...
  }

  build() {
    Navigation(this.navStack) {
      // ...
    }
  }
}

NavigationPage.ets

@Builder
export function BasicNavDestinationBuilder() {
  BasicNavDestination();
}

@Component
struct BasicNavDestination {
  // Obtain the navigation controller in NavDestination.
  stack: NavPathStack = AppStorage.get<NavPathStack>('basicNavigationStack')!;

  build() {
    NavDestination() {
      // ...
    }
    .title('BasicNavDestination')
  }
}

BasicNavDestination.ets

Method 2: Use the NavDestination.onReady lifecycle callback to obtain the object.

@Builder
export function PageOneBuilder(name: string, param: string) {
  PageOne({ name: name, value: param });
}

@Component
export struct PageOne {
  navPathStack: NavPathStack = new NavPathStack();
  name: string = '';
  @State value: string = '';
  context = this.getUIContext().getHostContext();

  build() {
    NavDestination() {
      // ...
    }.title(`${this.name}`)
    .onReady((ctx: NavDestinationContext) => {
      // Obtain the navigation controller of the current page through NavDestinationContext.
      this.navPathStack = ctx.pathStack;
    })
  }
}

NavigationExampleOne.ets

Basic Operations

Since API version 12, the navigation controller can be inherited. You can customize attributes and methods in derived classes or override methods of the parent class. Objects of the derived class can be used as NavPathStack objects of the base class. For details about the sample code for overriding NavPathStack, see Defining a Derived Class of NavPathStack. The following describes the basic routing APIs provided by NavPathStack.

Page navigation

NavPathStack uses push-related APIs (such as pushPath, pushPathByName, pushDestination, and pushDestinationByName) to implement page navigation. Page navigation can be classified into the following types:

Normal navigation: Navigation is conducted by page name and allows for carrying parameters.

this.pageStack.pushPath({ name: 'pageOne', param: 'PageOne Param' });

Index.ets

this.pageStack.pushPathByName('pageTwo', 'PageTwo Param');

Page Routing

Creating a Navigation Page

Creating a Navigation Root Container

Building a Subpage

Configuring a Routing Table

Routing Operations

Navigation Stack Acquisition

Basic Operations

Singleton Navigation

Parameter Acquisition

Route Interception

Examples

Creating a Navigation Home Page

Creating a Navigation Subpage

Creating a Routing Table