HarmonyOS Development Tutorial: Detailed Explanation of Router Navigation

Hello everyone, today we will learn about a very important concept in HarmonyOS development – Page Router.

In actual application development, navigating between different pages is the most basic requirement. Let’s take a look at how to use the Router to achieve elegant page navigation.

What is Router?

Router acts like a “navigation system” within the application, responsible for navigating between pages. For example, jumping from the home page to the detail page, or from the login page to the main page, all require the Router. It’s like a map navigation in our lives, telling the application how to get from point A to point B.

Basic Usage of Router

1. Page Declaration

First, we need to declare that this is a routable page in the entry file:

// pages/Home.ets
@Entry
@Component
struct HomePage {
    @State message: string = 'Home Page'

    build() {
        Column() {
            Text(this.message)
                .fontSize(30)
            Button('Go to Detail')
                .onClick(() => {
                    router.pushUrl({
                        url: 'pages/Detail' // Jump to detail page
                    })
                })
        }
    }
}

2. Common Router Methods

Page Jump (pushUrl)

// Basic jump
router.pushUrl({
    url: 'pages/Detail'
})

// Jump with parameters
router.pushUrl({
    url: 'pages/Detail',
    params: {
        id: '123',
        title: 'Detail Page'
    }
})

Return to Previous Page (back)

router.back()

Replace Current Page (replaceUrl)

router.replaceUrl({
    url: 'pages/NewPage'
})

3. Receiving Router Parameters

In the target page, we can use router.getParams() to retrieve the passed parameters:

// pages/Detail.ets
@Entry
@Component
struct DetailPage {
    @State params: any = router.getParams() // Get router parameters

    build() {
        Column() {
            Text(`ID: ${this.params?.id}`)
            Text(`Title: ${this.params?.title}`)
            Button('Return')
                .onClick(() => {
                    router.back()
                })
        }
    }
}

Router Configuration and Management

1. Router Declaration

Configure router information in app.ets:

{
    "module": {
        "pages": [
            "pages/Index",
            "pages/Home",
            "pages/Detail"
        ]
    }
}

2. Router Interception

We can add router guards to control page access permissions:

router.beforeEach((to, from, next) => {
    // Check if user is logged in
    if (needLogin && !isLoggedIn) {
        // Jump to login page if not logged in
        next({
            url: 'pages/Login'
        })
    } else {
        // Allow jump
        next()
    }
})

Tips

1.Naming Convention: Page paths usually start with pages, e.g., ‘pages/Home’2.Parameter Passing: Do not pass excessively large data objects, only essential information should be passed3.Return Handling: When using router.back(), consider the page stack situation4.Path Writing: URL paths are case-sensitive, it is recommended to use lowercase consistently

Practical Exercise

Create a small application with the following features:

1.Display a list of multiple items on the home page2.Click an item to jump to the detail page3.Detail page displays the passed parameters4.Implement return functionality

Code Example

Below is a complete example:

// pages/Home.ets
@Entry
@Component
struct HomePage {
    @State itemList: Array<Object> = [
        {id: '1', title: 'Project 1'},
        {id: '2', title: 'Project 2'}
    ]

    build() {
        Column() {
            List() {
                ForEach(this.itemList, (item) => {
                    ListItem() {
                        Text(item.title)
                            .onClick(() => {
                                router.pushUrl({
                                    url: 'pages/Detail',
                                    params: item
                                })
                            })
                    }
                })
            }
        }
    }
}

// pages/Detail.ets
@Entry
@Component
struct DetailPage {
    @State params: any = router.getParams()

    build() {
        Column() {
            Text(`Project ID: ${this.params.id}`)
            Text(`Project Title: ${this.params.title}`)
            Button('Return to Home')
                .onClick(() => {
                    router.back()
                })
        }
    }
}

Summary Points

•Router is the core mechanism for implementing page navigation in HarmonyOS•Common router methods include pushUrl, back, replaceUrl, etc.•Parameters can be passed between pages using params•Router guards can be used to control page access permissions•Pay attention to the correct configuration of page paths•Use router parameters wisely to pass data

Friends, that’s all for today’s Harmony learning journey! Remember to code and feel free to ask questions in the comments!

Wish everyone a happy learning experience, and may you truly master Harmony from beginner to advanced!

HarmonyOS Development Guide: Detailed Explanation of Router Navigation