HarmonyOS NEXT Application Development: In - Depth Analysis of the Navigation Component for Page Navigation and Routing Management

I'm Feri, a programmer with over 12 years of experience. I've engaged in development work, led teams, and started businesses. I specialize in Hongmeng development, embedded systems, Java programming, and artificial intelligence. My focus lies in the growth of programmers, and I hope to accompany you on this journey of growth! Where there is a will, there is a way!

---

I. Introduction

In HarmonyOS application development, page navigation is a core aspect of building user experience. How to achieve smooth cross - page navigation, efficient page stack management, and multi - device adaptive layout are key technologies that developers must master. As the official routing solution provided by HarmonyOS, the Navigation component offers a complete set of page navigation solutions through a standardized component model and a flexible configuration system. This article will provide an in - depth analysis of the core features and application scenarios of the Navigation component from the perspectives of technical principles, implementation steps, and best practices.

II. Core Concepts and Architectural Design of the Navigation Component

2.1 Component Positioning: The Core Carrier for Full - Scenario Navigation

The Navigation component is the root view container responsible for page routing and navigation management in HarmonyOS, undertaking the following core responsibilities:

• Cross - Page Navigation: Supports page navigation within and across modules, and realizes page mapping relationships through routing table configuration.

• Page Stack Management: Maintains the page stack through the NavPathStack object, supporting stack operations such as push and pop.

• Multi - Device Adaptation: Automatically identifies the device screen size and achieves optimal layout on mobile phones (single - column Stack mode), tablets (two - column Split mode), and foldable devices (Auto adaptive mode).

• Title Bar Customization: Provides title bar style configuration (title text, menu buttons, hiding the navigation bar, etc.), and supports the hideNavBa property to achieve an immersive experience.

Its architecture consists of two core elements:

1. Navigation Page (Navigation Container): As the entry page of the application (marked with @Entry), it carries the entire navigation stack structure, including the title bar, content area, and toolbar (optional).

2. Sub - Page (NavDestination Component): As a specific business page, it is embedded in the navigation stack after being registered in the routing table, and supports independent title bar configuration and back - navigation logic.

2.2 Analysis of Three Display Modes

III. Practical Demonstration: Implementing Basic Page Navigation in Three Steps

3.1 Project Preparation and Page Structure Design

Project Skeleton Setup

src
├── main
│   └── ets
│       ├── pages
│       │   ├── Index.ets         # Navigation Page (Entry Page)
│       │   ├── OnePage.ets       # Sub - Page 1
│       │   └── TwoPage.ets       # Sub - Page 2
│       └── app
│           └── router            # Routing Configuration Directory
│               └── router_map.json # System Routing Table
├── resources
│   └── base
│       └── profile
│           └── module.json5      # Module Configuration File

Page Component Design

• Index.ets (Navigation Page): Contains jump buttons and operates the page stack through NavPathStack.

• OnePage.ets/TwoPage.ets (Sub - Pages): Contain back buttons and declare routing nodes through NavDestination.

3.2 Implementing the Navigation Page: Building the Routing Entry

@Entry
@Component
struct Index {
  // Initialize the page stack object to maintain navigation history
  private pageStack: NavPathStack = new NavPathStack();

  @State welcomeMsg: string = "我是导航页";

  build() {
    Navigation(this.pageStack)  // Bind the page stack instance
      .title("首页")            // Set the navigation page title
      .hideNavBa(false)         // Display the title bar (true by default)
    {
      Column({ space: 30 })
        .width("100%")
        .height("100%")
        .justifyContent(FlexAlign.Center)
      {
        Text(this.welcomeMsg)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)

        // Jump to Sub - Page 1
        Button("跳转第一个页面")
          .onClick(() => {
            // Push operation, the name corresponds to the configuration in the routing table
            this.pageStack.pushPath({ name: "page1" });
          })

        // Jump to Sub - Page 2
        Button("跳转第二个页面")
          .onClick(() => {
            this.pageStack.pushPath({ name: "page2" });
          })
      }
    }
  }
}

Key Technical Points:

• The NavPathStack instance manages the page stack, and the pushPath method triggers page navigation and pushes the page onto the stack.

• The Navigation component must be the root container of the entry page and accept the page stack instance as a parameter.

• Title bar configuration supports dynamic styles and can be customized through modifiers such as .title() and .backgroundColor().

3.3 Implementing Sub - Pages: Defining Routing Nodes

// OnePage.ets
@Builder
export function buildPage1() {  // Export the build function for routing table calls
  return new OnePage().build();
}

@Component
struct OnePage {
  private pageStack: NavPathStack = new NavPathStack();

  build() {
    NavDestination()  // Declare the current page as a routing node
      .title("第一个页面")  // Independent title for the sub - page
    {
      Column({ space: 30 })
        .width("100%")
        .height("100%")
        .justifyContent(FlexAlign.Center)
      {
        Text("子页-OnePage")
          .fontSize(40)
          .fontWeight(FontWeight.Bold)

        // Return to the previous page (pop operation)
        Button("点击返回上一级")
          .onClick(() => {
            this.pageStack.pop();  // Equivalent to popPath()
          })
      }
    }
  }
}

Development Specification Instructions:

1. Sub - pages must export the build function (such as buildPage1) through the @Builder decorator for reflection calls by the routing table.

2. The NavDestination component, as the root container of the sub - page, is responsible for interacting with the navigation stack.

3. The title bar of the sub - page is configured independently, and the current page title is automatically displayed during navigation.

3.4 System Routing Table Configuration: Establishing Page Mapping Relationships

1. Routing Table Definition (resources/base/profile/router_map.json)

{
  "routerMap": [
    {
      "name": "page1",            // Routing Name (Unique Identifier)
      "pageSourceFile": "src/main/ets/pages/OnePage.ets",  // Page File Path
      "buildFunction": "buildPage1",  // Build Function Name
      "data": {
        "description": "第一个子页的元数据"  // Optional Parameters (Support Passing Initialization Data)
      }
    },
    {
      "name": "page2",
      "pageSourceFile": "src/main/ets/pages/TwoPage.ets",
      "buildFunction": "buildPage2",
      "data": { "description": "第二个子页的元数据" }
    }
  ]
}

2. Module Configuration (module.json5)

{
  "module": {
    // ... Other Configurations
    "routerMap": "$profile:router_map"  // Reference the routing table resource
  }
}

Routing Resolution Mechanism:

• The system loads the routerMap configuration during startup and creates page instances through the reflection mechanism.

• The name field serves as the routing identifier and must strictly match the parameter in pushPath.

• The data field supports passing page initialization parameters, which can be retrieved through router.getParams().

IV. Advanced Features and Best Practices

4.1 Advanced Page Stack Operations

// Clear the stack and navigate to the home page
this.pageStack.clear();
this.pageStack.pushPath({ name: "home" });

4.2 Passing Routing Parameters

1. Passing Parameters During Navigation

// Pass parameters from the navigation page
this.pageStack.pushPath({ 
  name: "page1", 
  params: { userId: "123", timestamp: Date.now() } 
});

// Receive parameters in the sub - page
import router from '@ohos.router';

@Builder
export function buildPage1() {
  let params = router.getParams();  // Get routing parameters
  return Column() { Text(`用户ID: ${params.userId}`) };
}

2. Pre - defined Parameters in the Routing Table

{
  "routerMap": [
    {
      "name": "page1",
      "data": { "defaultColor": "#FF0000" },  // Pre - defined default parameters
      // ... Other Configurations
    }
  ]
}

4.3 Navigation Bar Customization Techniques

Navigation(this.pageStack)
  .title("自定义标题")
  .titleColor(Color.White)
  .backgroundColor(Color('#007DFF'))
  .hideNavBa(true)  // Hide the navigation bar (suitable for full - screen pages)
  .menu(MenuItem({  // Add a menu button in the upper right corner
    icon: $r('app.media.menu_icon'),
    onClick: () => { /* Menu click logic */ }
  }))

4.4 Multi - Device Adaptation Optimization

// Dynamically switch the navigation mode according to the device type
let isTablet = DeviceInfo.getDeviceType() === DeviceType.Tablet;

Navigation(this.pageStack)
  .mode(isTablet ? NavigationMode.Split : NavigationMode.Stack)

V. Common Problems and Solutions

5.1 Route Not Found Exception

Phenomenon: When clicking the navigation button, an error message "Route not found" is displayed.
Reasons:

1. The name in the routing table does not match the parameter in pushPath.

2. The build function is not correctly exported (missing the @Builder decorator).

3. The pageSourceFile path is incorrect (pay attention to case - sensitivity and file extensions).
   Solutions: Check the routing table configuration to ensure that the exported name of the build function matches the configuration.

5.2 Page Stack Disorder

Phenomenon: The back button logic is abnormal after multiple navigations.
Best Practices:

• Use a unified navigation stack instance (avoid multiple NavPathStack instances).

• In complex scenarios, use getPageCount() to obtain the stack depth and avoid out - of - bounds popping.
  -优先使用pushPath/pop组合进行导航，避免直接操作栈数组。

5.3 Title Bar Style Conflicts

Solutions:

• Set independent titles for the navigation page and sub - pages through .title() respectively.

• Use hideNavBa to uniformly control the display status of the navigation bar.

• Define common navigation bar styles in the App.less file for global styles.

VI. Conclusion

As the core solution for HarmonyOS application navigation, the Navigation component greatly simplifies the development of complex page navigation scenarios through standardized routing configuration, flexible page stack management, and powerful multi - device adaptation capabilities.

In practical projects, the following points should be noted:

1. Design the routing table structure reasonably to avoid redundant configurations.

2. Manage the NavPathStack instance uniformly to ensure the atomicity of page stack operations.

3. Make full use of the Auto adaptive mode to achieve unified multi - device layout.

4. Combine with animation components (such as Animate) to optimize the page transition experience.

With the continuous improvement of the HarmonyOS ecosystem, the Navigation component will continue to evolve with more advanced features (such as routing guards, dynamic route loading, etc.).

It is recommended to follow updates in the official documentation, master the latest navigation management techniques, and create a more seamless full - scenario application experience.

Through the practices in this article, you can quickly master the core usage of the Navigation component, achieving the entire development process from basic page navigation to complex navigation scenarios, laying a solid foundation for building high - performance HarmonyOS applications.

Well, that's all for this article. I hope it's helpful to you. Keep it up!