HarmonyOS Router 基本使用详解：从代码示例到实战要点

HarmonyOS Router 基本使用详解：从代码示例到实战要点

**

在 HarmonyOS 应用开发中，页面间的跳转与导航是核心功能之一，而 Router（路由） 正是实现这一功能的关键工具。它负责管理页面栈的切换，支持多种跳转模式，满足不同场景下的导航需求。本文将结合实际代码示例，从核心概念、方法解析、模式对比到注意事项，全面讲解 HarmonyOS Router 的基本使用。

一、Router 核心概念：理解页面栈与导航逻辑

在学习具体用法前，首先需要明确 Router 的核心工作原理 ——基于页面栈（Stack）的管理机制：

• 页面栈：系统用栈结构存储已打开的页面，遵循 “先进后出” 原则。例如，从首页（Index）跳转到 PageA，首页会压入栈底，PageA 成为栈顶页面；当从 PageA 返回时，PageA 出栈，首页重新成为栈顶并显示。

• 核心作用：Router 通过 push（入栈）、replace（替换栈顶）、back（出栈）等操作，实现页面间的灵活切换，同时可传递参数、控制返回行为。

二、代码示例解析：Router 基本用法实战

以下结合你提供的参考代码，逐行拆解 Router 的核心 API 与使用场景，帮助你快速上手。

1. 第一步：导入 Router 模块

使用 Router 前，需先从 HarmonyOS 的 ArkUI 工具包中导入 router 模块，这是所有路由操作的基础：

import { router } from '@kit.ArkUI'

• 说明：@kit.ArkUI 是 HarmonyOS 提供的核心 UI 工具包，router 是其中专门用于页面导航的子模块，无需额外安装依赖。

2. 第二步：通过 Button 触发路由跳转

在 Index 组件的 build 方法中，通过两个 Button 分别演示了 pushUrl 跳转、带路由模式的 pushUrl 跳转，以及注释中的 replaceUrl 跳转。

场景 1：基础 pushUrl 跳转（支持返回上一页）

Button('跳转到 PageA')

.onClick(() => {

// pushUrl：将目标页面（PageA）压入页面栈，原页面（Index）保留在栈底

router.pushUrl({

url: 'pages/PageA' // 目标页面的路径，需与项目目录结构一致

})

// 注释的 replaceUrl：替换当前栈顶页面（Index）为 PageA，原页面被销毁

// router.replaceUrl({

// url: 'pages/PageA'

// })

})

• 关键逻辑：

• • router.pushUrl()：最常用的跳转方式，保留当前页面（Index）并将目标页面（PageA）压入栈顶。跳转后，在 PageA 中可通过 “返回键” 或 router.back() 回到 Index 页面，适合 “层级跳转” 场景（如 “首页→详情页”）。

• • url 参数：必须是目标页面的相对路径，格式为 pages/页面名（需确保页面已在 main_pages.json 中注册，否则会报错）。

• • 注释的 router.replaceUrl()：与 pushUrl 核心区别是销毁当前页面（Index），用 PageA 替换栈顶位置。跳转后，在 PageA 中无法返回 Index 页面（原页面已被销毁），适合 “流程跳转” 场景（如 “登录页→首页”，登录后无需返回登录页）。

场景 2：指定路由模式的 pushUrl 跳转

Button("路由模式")

.onClick(() => {

router.pushUrl(

{ url: 'pages/PageA' }, // 目标页面配置

router.RouterMode.Standard // 指定路由模式为 Standard

)

})

• 路由模式（RouterMode）解析：

HarmonyOS Router 提供两种核心模式，用于控制页面栈的创建规则，默认模式为 Standard：

1. 1. router.RouterMode.Standard（标准模式）：

• • • 每次调用 pushUrl 都会创建一个新的目标页面实例并压入栈中。例如，多次点击 “路由模式” 按钮，会创建多个 PageA 实例，页面栈中会存在 “Index→PageA→PageA→PageA”，返回时需依次退出每个 PageA。

• • • 适用场景：需要保留同一页面的多个状态（如 “商品列表页→商品详情页”，多次点击不同商品，需保留每个详情页的独立状态）。

1. 1. router.RouterMode.SingleTop（单顶模式）：

• • • 若目标页面已在栈顶，则不会创建新实例，直接复用当前栈顶页面；若目标页面不在栈顶，则创建新实例并压入栈。例如，若当前栈顶是 PageA，调用 pushUrl 且模式为 SingleTop 时，不会新建 PageA，而是复用已有实例。

• • • 适用场景：避免同一页面在栈顶重复创建（如 “消息通知页→详情页”，多次点击同一通知，无需重复创建详情页）。

三、路由跳转的关键注意事项

掌握基本用法后，需注意以下细节，避免开发中出现异常：

1. 页面路径必须正确且已注册

• 路径格式：url 必须严格匹配项目的目录结构，例如页面放在 src/main_pages/pages/PageA.ets，则路径为 pages/PageA（无需加 .ets 后缀）。

• 页面注册：所有需要通过 Router 跳转的页面，必须在项目根目录的 main_pages.json 中注册（默认创建页面时会自动注册，手动创建需手动添加），示例：

{

"src": [

"pages/Index",

"pages/PageA" // 注册 PageA 页面

]

}

若未注册，调用 pushUrl 会抛出 “页面未找到” 的错误。

2. pushUrl 与 replaceUrl 的核心区别（必分清）

对比维度	router.pushUrl()	router.replaceUrl()
页面栈行为	新增页面到栈顶，保留原页面	替换栈顶页面，销毁原页面
是否支持返回	支持（目标页面可返回原页面）	不支持（原页面已销毁，无法返回）
适用场景	层级跳转（首页→详情、列表→详情）	流程跳转（登录→首页、引导页→首页）

3. 路由参数传递（扩展功能）

你的代码中未涉及参数传递，但实际开发中 “跳转时传值” 非常常用，这里补充基础用法：

• 跳转时传参：在 pushUrl 的配置中添加 params 属性，传递键值对参数：

router.pushUrl({

url: 'pages/PageA',

params: {

goodsId: '123', // 商品ID

goodsName: 'HarmonyOS 手机' // 商品名称

}

})

• 目标页面接收参数：在 PageA 中通过 router.getParams() 获取传递的参数：

import { router } from '@kit.ArkUI'

@Entry

@Component

struct PageA {

private goodsId: string = ''

private goodsName: string = ''

aboutToAppear() {

// 页面即将显示时，获取路由参数

const params = router.getParams()

this.goodsId = params.goodsId as string

this.goodsName = params.goodsName as string

}

build() {

Column() {

Text(`商品ID：${this.goodsId}`)

Text(`商品名称：${this.goodsName}`)

}

}

}

四、总结

本文通过代码示例，详细讲解了 HarmonyOS Router 的核心用法：

1. 导入 router 模块是基础，所有路由操作依赖该模块；

1. pushUrl 适合需返回的层级跳转，replaceUrl 适合无需返回的流程跳转；

1. 路由模式 Standard 与 SingleTop 控制页面实例的创建规则，需根据场景选择；

1. 需注意页面路径的正确性、注册状态，以及参数传递的用法。

掌握这些基础后，你可以进一步学习 Router 的高级功能（如页面返回时传值、清空页面栈等），满足更复杂的导航需求。如果在实际开发中遇到具体问题（如参数传递异常、页面跳转失败），可以结合本文内容排查，或进一步扩展学习。