文章导读

• 路由地址集中定义在 Routes，页面不再手写散落的字符串常量。
• RouteParams 用具名字段承载 id 和 query，让 ArkTS 严格模式下的跳转参数更可控。
• Nav.push / replace / back / getParams 把底层 router API 包成项目可复用的导航入口。

页面效果

这套封装不是为了“多包一层”，而是为了保证两个高频场景都稳定：一是从首页、收藏页、搜索页进入详情时，id 一定能传到详情页；二是搜索页重新进入时，query 能恢复到输入框和结果列表里。

实战拆解

如果页面少，直接写 router.pushUrl({ url, params }) 看起来最省事；但一旦详情页、列表页、搜索页、收藏页都开始互相跳转，路径字符串和参数对象就会迅速散开。羽球联盟把这个问题提前收口：所有页面地址统一放在 Routes，参数统一放在 RouteParams，页面层只表达“去哪个页面”和“带什么业务参数”。

RouteParams 目前只保留 id 和 query 两个字段，看上去很简单，但这个形状其实覆盖了大多数核心场景：文章详情、装备详情、球员详情使用 id，搜索页使用 query。后续如果要扩展 tab、来源页、埋点信息，也是在同一个参数实体上继续长，而不是去追踪几十处对象字面量。

更关键的是 Nav.getParams() 的兜底。它没有把 router.getParams() 直接扔给页面，而是统一转成 RouteParams，拿不到参数时返回一个空对象。这样详情页就可以先处理默认值，再决定展示空态、查默认数据还是提示用户返回。

关键代码

export class RouteParams {
  id: string = '';
  query: string = '';

  constructor(id: string = '', query: string = '') {
    this.id = id;
    this.query = query;
  }
}

export class Nav {
  static push(url: string, params?: RouteParams): void {
    router.pushUrl({ url, params }).catch((e: Error) => {
      console.error('Nav.push error', e.message);
    });
  }

  static replace(url: string, params?: RouteParams): void {
    router.replaceUrl({ url, params }).catch((e: Error) => {
      console.error('Nav.replace error', e.message);
    });
  }

  static getParams(): RouteParams {
    const p = router.getParams() as RouteParams;
    if (p) {
      return p;
    }
    return new RouteParams();
  }
}

这个封装最有价值的地方，在于把错误处理和参数默认值前置了。页面不需要每次都重复写一遍 catch 和空值分支，业务跳转也更容易全文搜索和统一替换。

取舍分析

集中路由的代价，是需要维护一层看似“多余”的工具文件；但这层文件一旦存在，收益会不断放大。你可以在一个地方审查全部路由地址，也可以在一个地方决定参数结构。相比之下，如果每个页面都直接调用底层 API，短期轻巧，长期却最容易出现地址改了半套、参数字段名字不一致、页面兜底策略各写各的情况。

这里没有去设计一个很重的路由中台，而是停在项目当前需要的粒度：一个 Routes 常量表，一个 RouteParams 实体，一个 Nav 工具类。对中小型 ArkTS 应用来说，这个规模刚好够用，而且容易继续迭代。

设计落点

• 页面地址统一收敛到 Routes，避免硬编码分散在业务页和组件里。
• 参数对象统一收敛到 RouteParams，避免对象字面量越写越散。
• 导航工具统一处理错误和默认值，页面层只关心业务跳转。
• 搜索、详情、收藏、历史等多个入口共享同一套路由协议。

易踩坑

• 不要让不同页面偷偷约定不同的参数字段名，今天叫 id，明天叫 articleId，后期很难收敛。
• 不要假设 router.getParams() 一定有值。应用从通知、历史记录或异常返回恢复时，参数缺失并不罕见。
• 如果某个页面需要复杂对象，优先传主键或查询条件，尽量不要直接传大对象副本。

验证方式

• 从首页资讯卡片、收藏页和历史页分别进入文章详情，确认 id 都能定位到正确内容。
• 在搜索页输入关键字后跳走再返回，确认 query 能恢复搜索框和结果列表。
• 人为构造无参数进入详情页，检查页面是展示空态、默认内容还是返回上页，而不是直接报错。

参考资料

• [页面路由（官方文档）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-routing)
• [学习 ArkTS 语言（官方文档）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-more-cases-V5)

小结

这篇真正要解决的问题不是“怎么跳一次页面”，而是“怎么让几十次跳转保持同一套协议”。当路由地址、参数结构和错误兜底都被收进统一入口后，页面代码会明显干净很多，后续加新页面或改页面路径时也更安全。