多页面路由系统封装实战：构建可维护的大型鸿蒙应用路由结构 HarmonyOS 5.0.0或以上

本文链接：https://blog.csdn.net/2501_92049284/article/details/147924017

当你的鸿蒙项目页面数量逐渐增加，从首页 → 详情页 → 编辑页 → 设置页……你会发现：

页面跳转混乱，找不到入口？
参数传递不规范，丢三落四？
想统一处理登录校验/权限检查，根本无从下手？

解决这些问题的核心，就是封装一个统一路由系统。

本篇就教你如何封装鸿蒙项目中的 Router 跳转工具，支持：

路由注册与路径常量统一管理
参数强类型校验与默认值处理
支持中间件（登录拦截）机制
统一返回数据处理逻辑

✅ 为什么不直接用 `Router.push()`？

ArkTS 原生提供了 Router.push() / Router.replaceUrl() 接口，但：

Router.push({
  url: 'pages/Detail',
  params: { userId: 123 }
})

这种写法：

路径是字符串，容易拼错；
参数没有统一类型；
返回值处理混乱；
无法统一加入拦截逻辑。

所以我们要抽象出一个更稳定的“路由系统”。

📦 Step1：统一页面路径管理

创建 src/constants/routes.ts

export const Routes = {
  HOME: 'pages/Home',
  DETAIL: 'pages/Detail',
  LOGIN: 'pages/Login'
}

后续所有页面跳转都使用 Routes.DETAIL，避免路径硬编码。

📦 Step2：封装通用跳转方法

`src/utils/router.ts`

import { Routes } from '../constants/routes'

type RouteParams = Record<string, any>

export async function navigateTo(url: string, params: RouteParams = {}) {
  // 登录拦截示例
  if (url !== Routes.LOGIN && !await isLoggedIn()) {
    return Router.push({ url: Routes.LOGIN })
  }

  Router.push({ url, params })
}

export function replaceTo(url: string, params: RouteParams = {}) {
  Router.replaceUrl({ url, params })
}

function isLoggedIn(): Promise<boolean> {
  // 可替换为真实鉴权逻辑
  return Promise.resolve(true)
}

📦 Step3：支持返回数据的导航（回调）

在页面 A：

navigateTo(Routes.DETAIL, {
  userId: 123,
  callback: (result) => {
    console.log('返回结果：', result)
  }
})

在页面 B 获取：

@Entry
@Component
struct DetailPage {
  userId: number = 0
  callback: (result: any) => void = () => {}

  aboutToAppear() {
    const params = getContext(this).params
    this.userId = params.userId
    this.callback = params.callback
  }

  onClickSave() {
    this.callback({ updated: true })
    Router.back()
  }

  build() {
    // 页面内容...
  }
}

📦 Step4：添加路由参数类型定义（可选）

定义 types/route-params.d.ts：

export interface DetailPageParams {
  userId: number
  callback?: (res: { updated: boolean }) => void
}

再在跳转时使用类型提示：

navigateTo(Routes.DETAIL, {
  userId: 123
} satisfies DetailPageParams)

🧩 小结

通过本篇你学会了：

能力	实现方式
路由路径统一管理	使用 `Routes` 常量定义路径
页面跳转封装	封装 `navigateTo()` 工具方法
登录拦截 / 中间件	在跳转前添加校验函数
回调函数传值	使用 `params.callback()` 实现
参数类型校验（进阶）	TypeScript + satisfies 实现