DEV Community: skyrejer

Native Hongmeng Router-Navigation Summary

skyrejer — Thu, 29 May 2025 15:14:43 +0000

Navigation route navigation
Use Navigation to replace all route jumps

The concept is: the entire application has only one page, and the rest are components [Huawei recommends using Navigation route navigation]

The first routing method
The outermost layer of the root component must be wrapped by Navigation
The component to be redirected must be wrapped by NavDestination
The redirection object is the NavPathStack object
NavPathStack must be bound to Navigation
The lower-level components use various methods to obtain the upper-level NavPathStack for redirection
The redirection maintenance is implemented by .navDestination
Navigation is bound to NavPathStack, and it is best to use Provide to provide it to child components for use
Route management — bind .navDestination(builder) to Navigation — builder cannot write bracket mode

import { Friend } from './Friend'
import { Live } from './Live'
import { Shake } from './Shake'

@Entry
@Component
struct NavigationCase {
@Provide
stackPath: NavPathStack = new NavPathStack()

@builder
getRouterBuilder (name: string) {
// name is the identifier to jump to
if(name === 'friend') {
Friend()
}
else if(name === "live") {
Live()
}
else if(name === "shake") {
Shake()
}
}

build() {
// 1. Use Navigation to wrap the entire root component
Navigation(this.stackPath) {
List() {
ListItem(){
Text("朋友圈")
.fontSize(20)
.width("100%")
}
.height(50)
.width("100%")
.padding({
left: 20
})
.onClick(() => {
this.stackPath.pushPath({
name: 'friend'
})
})

ListItem(){
Text("直播")
.fontSize(20)
.width("100%")
}
.height(50)
.width("100%")
.padding({
left: 20
})
.onClick(() => {
this.stackPath.pushPath({
name: 'live'
})
})
ListItem(){
Text("摇一摇")
.fontSize(20)
.width("100%")
}
.height(50)
.width("100%")
.padding({
left: 20
})
.onClick(() => {
this.stackPath.pushPath({
name: 'shake'
})
})
}
.divider({
strokeWidth: 2,
color: "#ccc"
})
}
.navDestination(this.getRouterBuilder)
.mode(NavigationMode.Auto)

}
}
import { IParams } from "./NavigationCase"

@Component
export struct NavigationCase_friend {
@Consume navStackPath: NavPathStack
@State age: number = 0
@State name: string = ''

build() {
NavDestination() {
Text("朋友圈")
Button("点我返回上一页")
.onClick(() => {
this.navStackPath.pop()
})

Text(this.name + this.age)

}.onWillAppear(() => {
const params = this.navStackPath.getParamByName('friend') as IParams[]
this.age = params[params.length - 1]?.age
this.name = params[params.length - 1]?.name
AlertDialog.show({ message: JSON.stringify(params, null, 2) })
})
}
}
The second way: WrapBuilder
wrapBuilder can wrap a global builder, which will not be rendered immediately, and needs to run the builder method directly

Subcomponents need to export the global builder separately

WrapBuilder

wrapBuilder is a global function

It will return a type of WrapBuilder<[]>, the empty array is the type of the parameter

map.get(name).builder()
import { FriendPageBuilder } from "./NavigationCase_friend"
import { LivePageBuilder } from "./NavigationCase_live"
import { LookPageBuilder } from "./NavigationCase_look"

export const RouterMap: Map> = new Map()

RouterMap.set("look", wrapBuilder(LookPageBuilder))
RouterMap.set("live", wrapBuilder(LivePageBuilder))
RouterMap.set("friend", wrapBuilder(FriendPageBuilder))
@Component
export struct NavigationCase_look {
@Consume navStackPath: NavPathStack

build() {
NavDestination() {
Text("看一看")
Button("点我去到live")
.onClick(() => {
this.navStackPath.pushPath({ name: 'live' })
})

Button("返回到根首页")
.onClick(() => this.navStackPath.clear())
}
}
}

@builder
export function LookPageBuilder() {
NavigationCase_look()
}

import { RouterMap } from './NavigationCase_WrapBuilder'

export interface IParams {
name: string
age: number
}

@Entry
@Component
struct NavigationCase {
@Provide navStackPath: NavPathStack = new NavPathStack()

@builder
getBuilder(name: string) {
RouterMap.get(name)?.builder()
}

build() {
Navigation(this.navStackPath) {
List({ space: 20 }) {
ListItem() {
Text("朋友圈")
.width("100%")
.height(60)
.backgroundColor(Color.Pink)
}.onClick(() => {
this.navStackPath.pushPath({ name: 'friend', param: { name: 'aaa', age: 18 } as IParams })
})

ListItem() {
Text("直播")
.width("100%")
.height(60)
.backgroundColor(Color.Brown)
}
.onClick(() => {
this.navStackPath.pushPath({ name: 'live' })
})

ListItem() {
Text("看一看")
.width("100%")
.height(60)
.backgroundColor(Color.Orange)
}
.onClick(() => {
this.navStackPath.pushPathByName('look', null)
})
}
}
.mode(NavigationMode.Auto)
.navDestination(this.getBuilder)
}
}
The third method: configuration routing
The root component must be wrapped by Navigation
Must be bound to NavStackPath
Subcomponents must be wrapped by NavDestination
There must be a global builder to render subcomponents
No need to configure .navDestination
A routerMap json file [“routerMap”: “$profile:router_map”] needs to be configured in the project’s module.json5
Configure three contents in the routerMap file — name-builder-file path
The route map mode can only be tested in the simulator

{
"routerMap": [
{
"name": "main",
"buildFunction": "MainPageBuilder",
"pageSourceFile": "src/main/ets/pages/AgainNavigation/MainPage.ets"
},
{
"name": "detail",
"buildFunction": "PageDetailBuilder",
"pageSourceFile": "src/main/ets/pages/AgainNavigation/PageDetail.ets"
}
]
}
Navigation parameter — Return — Return to the first page
this.stackPath.getParamByName(“当前页的name”)

.onWillAppear(() => {
const params = this.stackPath.getParamByName("detail") as Params[]
this.age = params[params.length - 1]?.age
console.log("onWillAppear")
})
If no parameters are passed, the array still has a length, but the content is undefined
Return to home page: this.stackPath.popToIndex(-1)
Return to previous page: this.stackPath.pop()
// Return to the previous PageOne page // this.pageStack.popToName(“PageOne”)
// Return to the root home page (clear all pages in the stack) // this.pageStack.clear()

pushPath (append)/replacePath (replace), unlimited layers
router-32 layers
pushPath({ name: ‘’, param: 123 }), assuming that the object to be passed must be of a specific type, such as interface/class/Record/Map
receive parameter this.stackPath.getParamByName(“xx”) — xx is the name value of the current component
the parameter type obtained is an unknown[], forcing developers to perform as specific type[]
to take the last parameter — if no parameter is passed, the array still exists, but the content is undfined

Some common properties of the Navigation component
.title() // Title, you can set a custom builder
.titleMode() // Set the page title bar display mode, common properties: NavigationTitleMode.Mini
.hideTitleBar(true) // Hide the title bar
.mode() // Set the display mode of the navigation bar, commonly used Stack, no column display
.navDestination() // Create a NavDestination component. Use the builder function to construct a NavDestination component based on name and param. There can only be one root node under the builder. The builder allows a layer of custom components outside the NavDestination component, but custom components are not allowed to set properties and events, otherwise they will only display blank.

Recommendations for NavDestination Components
It is not recommended to set layout-related properties such as position and size, as this may cause abnormal page display.

router route jump

skyrejer — Thu, 29 May 2025 15:12:51 +0000

Routing Mode
Routing provides two different jump modes, and different modes determine whether the page will create multiple instances.
Standard: Multi-instance mode, which is also the default jump mode. The target page is added to the top of the page stack, regardless of whether there is a page with the same URL.
Single: Single instance mode. If the URL of the target page already exists in the page stack, the page with the same URL closest to the top of the stack will be moved to the top of the stack, and the page will become a new page. If the URL of the target page does not exist in the page stack, it will jump according to the default multi-instance mode.
In short:
Standard: Regardless of whether it has been added before, it will always be added to the page stack [Common] [Default]
Single: If a page has been added before, the previously added page will be used [Use depending on the situation]

router.pushUrl(options, mode?) // router.pushUrl(options, router.RouterMode.Standard)
router.replaceUrl(option, mode?)
Page jump and back
Normal jump (can return)

router.pushUrl({
url: 'Page address' // page/Index
})
Replace jump (cannot return)

router.replaceUrl({
url: "Page address"
})
return

router.back()
Both router.pushUrl() and router.replaceUrl can jump to the page, the difference is: whether to replace the current page

router.pushUrl(): The target page will not replace the current page, but will be pushed into the page stack. This can preserve the state of the current page, and you can return to the current page by pressing the back key or calling the router.back() method
router.replaceUrl(): The target page will replace the current page and destroy the current page. This can release the resources of the current page, and you cannot return to the current page

Page Stack
The page stack is a data structure used to store program runtime pages, following the first-in-last-out principle

Router mode jump routing, the maximum capacity of the page stack is 32 pages

router.clear() // Clear the page stack
router.getLength() // Returns the current length of the page stack
router.getState() // Get page status
let page = router.getState()
console.log("current Index = " + page.index)
console.log("current name = " + page.name)
console.log("current path = " + page.path)
parameter
pushUrl

router.pushUrl({
url: "url string",
params: {
// Passing parameters as objects
}
})

router.getParams() as object // Receiving route parameters
replaceUrl

router.replaceUrl({
url: "URL",
params: {
// Passing parameters as objects
}
})
back

router.back({
url: 'URL',
params: {
// Passing parameters as objects
}

// Parameters can be passed when back is returned, but generally no parameters are required for back
})
Cross-package jump in router mode
Navigation route jump — cross-package: hap -> hsp / hsp -> hsp

Navigation naturally supports cross-package jump

By path

Rule: @bundle:package name/module name/ets/pages/xx page // The prefix can be encapsulated into a constant: @bundle:package name

router.pushUrl({
url: '@bundle:com.itheima.sz.new.content/home/ets/pages/Index'
})
By name (compared to the path method, it is more troublesome)

Modify the page to jump to @Entry ==> @Entry({routerName: ‘xxx’ })
Add dependencies, add the hsp module to jump to in oh-package.json
Import(“module name/path file”) in the page you want to jump to
router.pushNamedRoute

import { router } from '@kit.ArkUI';

import("home/src/main/ets/pages/Index")

@Entry
@Component
struct IndexPage {
build() {
RelativeContainer() {
Button("Cross-package jump 1-path method")
.alignRules({
center: { anchor: 'container', align: VerticalAlign.Center },
middle: { anchor: 'container', align: HorizontalAlign.Center }
})
.onClick(() => {
router.pushUrl({
url: @bundle:com.itheima.sz.new.content/home/ets/pages/Index
})
// Rule - @bundle:package name/module name/ets/pages/xxx page
})
.id("btn1")
Button("Cross-package jump 2-name method")
.alignRules({
top: { anchor: 'btn1', align: VerticalAlign.Bottom },
middle: { anchor: 'container', align: HorizontalAlign.Center }
})
.margin({
top: 20
})
.onClick(() => {
// router.pushUrl({
// url: @bundle:com.itheima.sz.new.content/home/ets/pages/Index
// })
// Rule - @bundle:package name/module name/ets/pages/xxx page
router.pushNamedRoute({
name: 'homePage'
})
})
}
.height('100%')
.width('100%')
}
}

A brief introduction to V1 and V2 decorators in HarmonyOS development

skyrejer — Thu, 29 May 2025 15:09:29 +0000

To use the V1 decorator, you need to decorate the component with the @Component decorator, while V2 needs to use @ComponentV2
V1 Decorator
@State: Components manage their own states. Adding @State allows ordinary variables to become state variables. When variables are updated, the UI is automatically refreshed.
@prop: Commonly used for parent-child transmission, one-way data flow, parent components are passed to child components, and the transmission is irreversible.
The difference between @prop and @State, parent-child transmission can also use @State, but @prop one-way data flow is more semantic and can avoid component state disorder
@link: Parent-child two-way communication
@ObjectLink/@Observed/@Track: Partially refresh the UI, better performance, can be used to prevent image flickering
@Provide/@Consume: Although the official said it is a two-way communication, in fact, it can only pass values from @Provide to @Consume, and cannot be passed in the reverse direction

V2 Decorator
@local is equivalent to @State

@param: from parent to child, from parent component to child component, child component cannot modify the value of parent component, if modified, error will be reported, if you want to modify, you need to use @ Once + @ Param

Note:

Once once is used, the parent component only passes the value to the child component for the first time, and the subsequent child component data is maintained by itself
@ Param [non-@ Once] way to pass the value, if the child component modifies the value of the parent component through callback, then this modification will not be synchronized to the child component
@ Require: whether it must be passed
@ ObservedV2 + @ Tace: local refresh can be achieved, @ Tace adds properties that need to set state variables
@provider() / @Consumer(): This version truly realizes two-way communication, and its functions are more powerful than V1

@ Provider() isScale: boolean = false
@ Consumer() isScale: booean = false
Other decorators
@ Event: callback function used to implement parent-child component communication

// Parent Component
getState = (state: string) => { console.log("状态：", state) }

// From father to son
TSMTest({
getState: this.getState
})

// Subcomponents
@ Event getState: (state: string) => void = (state: string) => {}Watch
Watch

V1 version: @ Watch
@ Watch is used to monitor state variables. If the developer needs to pay attention to whether the value of a state variable has changed, @Watch can be used to set a callback function for the state variable.
Decorator parameter: required. Constant string, the string needs to be quoted. It is a reference to the method of (string) => void custom member function.

If other state variables are changed in the @ Watch method, it will also cause state changes and @ Watch execution;

During the first initialization, the @ Watch decorated method will not be called, that is, the initialization is not considered to be a change in the state variable. The @ Watch callback method will only be called when the state changes subsequently.

To avoid the generation of loops, it is recommended not to modify the current decorated state variable in the @ Watch callback method;

The property value update function will delay the re-rendering of the component, so the callback function should only perform fast operations;

V2 version: @ Monitor

@ Monitor("isScale")
getShowScale() {
if(this.isScale) {
console.log("Size recovery")
}
}
The @ Monitor decorator has the ability to monitor deeply, and can monitor changes in specified items in nested classes, multi-dimensional arrays, and object arrays. Monitoring changes in member attributes in nested classes and object arrays requires that the class be decorated with @ ObservedV2 and the attribute be decorated with @trace.
Only updates to state variables can trigger the callback function of @ Monjtor
A single @ Monitor decorator can monitor changes in multiple attributes at the same time. When these attributes change together in an event, the callback method of @ Monitor will only be triggered once.
In the inheritance class scenario, @ Monitor can be defined in the parent and child components for the same attribute to monitor. When the attribute changes, the @ Monitor callback defined in the parent and child components will be called.
@ Monitor supports monitoring items in arrays, including multi-dimensional arrays and object arrays. @ Monitor cannot monitor changes caused by API calls of built-in types (Array, Map, Date, Set). When @ Monitor monitors the entire array, it can only observe the assignment of the entire array. You can determine whether the array has changes such as insertion and deletion by monitoring the length change of the array. Currently, only the “.” method is supported to express monitoring of deep attributes and array items.
If the properties monitored by @ Monitor are changed multiple times in one event, the last modification will prevail.

Column() {
Button("change count to 1000")
.onClick(() => {
for (let i = 1; i <= 1000; i++) {
this.frequence.count = i;
}
})
Button("change count to 0 then to 1000")
.onClick(() => {
for (let i = 999; i >= 0; i--) {
this.frequence.count = i;
}
// The onCountChange method is not triggered in the end
this.frequence.count = 1000;
})
}
After clicking the button “change count to 1000”, the onCountChange method is triggered once and the log “count change from 0 to 1000” is output. After clicking the button “change count to 0 then to 1000”, the value of the attribute count does not change before and after the event and is 1000, so the onCountChange method is not triggered.

limit
When there are multiple monitoring methods for a property in a class, only the last defined monitoring method will take effect.
The target property monitored by @ Monitor is determined at initialization and cannot be changed dynamically. It is not recommended for developers to use variables as parameters for @ Monitor initialization.
Developers are advised to avoid changing the monitored property again in @ Monitor, which will cause an infinite loop.

Summarize
@ Watch can only monitor a single state variable and follow the state variable observation capability (one level).

@ Monitor can monitor multiple state variables at the same time and follow the state variable observation capability (deep level) [requires
Takudzwa Bouy Tace Jangah
.

AppStorage
The V1 version of AppStorage can be directly decorated with @ StorageProp + @ StorageLink. The V2 decorator is slightly more complicated, but the benefits are more obvious. The V1 decorator shares one AppStorage, while the V2 decorator can implement multiple AppStorages.

@ ObservedV2
class AppStorageKey {
@ Tace
isScale: boolean = false
textController: TextController = new TextController()
}

@ Local appStorage: AppStorageKey = AppStorageV2.connect(AppStorageKey, () => new AppStorageKey())!

// use
this.appStorage.isScale = true
Custom component mix scenarios
V2 decorators cannot be used in V1’s custom components, otherwise compilation errors will occur.

When there is no variable transfer between components, V2’s custom components can be used in V1’s custom components, including custom components decorated with @ ComponentV2 imported from a third party.

When there is variable transfer between components, V1’s variables are passed to V2’s custom components, with the following restrictions:

Variables in V1 that are not decorated with decorators (hereinafter referred to as ordinary variables): V2 can only receive them using @ Param.

Variables in V1 that are decorated with decorators (hereinafter referred to as state variables): V2 can only receive them using @ Param decorators, and are limited to simple data types such as boolean, number, enum, string, undefined, and null.

V1 decorators cannot be used in V2’s custom components, otherwise compilation errors will occur.

When there is no variable transfer between components, V2’s custom components can use V1’s custom components, including custom components decorated with @ Component imported from a third party.

When there is variable transfer between components, the variables of V2 are passed to the custom components of V1, with the following restrictions:

Variables in V2 that are not decorated by decorators (hereinafter referred to as ordinary variables): If V1 uses decorators to decorate the received data, it can only be passed through @State, @prop, and @Provide.
Variables in V2 that are decorated by decorators (hereinafter referred to as state variables): If V1 uses decorators to decorate the received data, built-in type data is not supported: Array, Set, Map, Date.

How to migrate from V1 to V2 decorators
https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V14/arkts-v1-v2-migration-V14