前言在 HarmonyOS 多页面应用中页面间传参是最常见的需求之一。从列表页跳转到详情页时携带 ID、从游戏页跳转到排行榜时携带分数——这些数据通过router.pushUrl/replaceUrl的params参数传递目标页通过router.getParams()接收。本文以「猫猫大作战」的排行榜详情页为锚点全面讲解router.getParams的参数类型约束、接收时机、类型收窄技巧、与生命周期配合的最佳实践以及向 Navigation 参数的迁移方案。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–80 篇。本篇是阶段三第 81 篇。一、getParams 基本用法1.1 接口定义import { router } from kit.ArkUI; router.getParams(): Object;1.2 发送与接收// 发送方 — Index.ets router.pushUrl({ url: pages/Leaderboard, params: { playerId: 1001, playerName: 猫猫侠, highScore: 88888, isNewRecord: true } }); // 接收方 — Leaderboard.ets Entry Component struct Leaderboard { aboutToAppear() { const params router.getParams() as Recordstring, Object; const id params[playerId] as number; const name params[playerName] as string; const score params[highScore] as number; const isNew params[isNewRecord] as boolean; } }二、参数类型收窄2.1 类型断言的问题// 问题直接断言可能导致运行时崩溃 const score (params as Recordstring, number)[highScore]; // 如果 params 中没有 highScorescore 为 undefined2.2 安全的参数提取// ✅ 安全方式默认值 类型收窄 interface LeaderboardParams { playerId: number; playerName: string; highScore: number; isNewRecord: boolean; } function parseLeaderboardParams(): LeaderboardParams { const params router.getParams() as Recordstring, Object; return { playerId: typeof params[playerId] number ? params[playerId] : 0, playerName: typeof params[playerName] string ? params[playerName] : 未知玩家, highScore: typeof params[highScore] number ? params[highScore] : 0, isNewRecord: typeof params[isNewRecord] boolean ? params[isNewRecord] : false }; }2.3 推荐使用泛型封装// 通用参数解析工具 function getRouterParamT(key: string, defaultValue: T): T { const params router.getParams() as Recordstring, Object; const value params?.[key]; return (value ! undefined value ! null) ? (value as T) : defaultValue; } // 使用 const playerId getRouterParamnumber(playerId, 0); const playerName getRouterParamstring(playerName, 匿名); const highScore getRouterParamnumber(highScore, 0);三、参数接收时机3.1 在 aboutToAppear 中接收Entry Component struct Leaderboard { State playerId: number 0; State playerName: string ; aboutToAppear() { // ✅ 组件创建时接收参数 — 最推荐 const params router.getParams() as Recordstring, Object; this.playerId (params?.[playerId] as number) ?? 0; // 使用参数加载数据 this.loadPlayerData(this.playerId); } loadPlayerData(id: number) { // http 请求或本地查询 } }3.2 在 build 中接收// ⚠️ 不推荐在 build 中直接调用 getParams build() { // build 可能被多次调用getParams 每次返回相同值 const params router.getParams(); // 没问题但不推荐 }建议统一在aboutToAppear中接收并存储到State变量中。四、参数类型对照表4.1 支持的参数类型TypeScript 类型传递示例接收后类型stringcatstringnumber100numberbooleantruebooleanObject{ a: 1 }ObjectArray[1,2,3]ArrayDatenew Date()string被序列化Map/Set—❌ 不传递Function—❌ 被丢弃Date对象会被自动序列化为 ISO 字符串接收方需用new Date(value)还原。4.2 复杂对象传递// 发送方 — 序列化复杂对象 const gameState { score: 88888, cats: [ { id: 1, level: 3, x: 1, y: 2 }, { id: 2, level: 5, x: 3, y: 4 } ], combo: { count: 3, multiplier: 2 } }; router.pushUrl({ url: pages/GameOver, params: { gameState: JSON.stringify(gameState) } }); // 接收方 — 反序列化 aboutToAppear() { const params router.getParams() as Recordstring, string; if (params?.[gameState]) { const state JSON.parse(params[gameState]); this.score state.score; this.cats state.cats; } }五、参数 vs AppStorage5.1 选型对比对比维度router.getParamsAppStorage作用域单次页面跳转全局生命周期页面销毁后清除应用进程存活期间适合场景页面间瞬时数据全局设置、用户信息类型安全需手动断言自动类型推断传递时机跳转时任意时刻写入/读取5.2 组合使用// 跳转到详情页 — 轻量参数用 params重量数据用 AppStorage goToDetail(record: GameRecord) { // 将完整数据放入 AppStorage避免序列化大对象 AppStorage.setOrCreate(currentRecord, record); // params 只传引用 ID router.pushUrl({ url: pages/Detail, params: { recordId: record.id } }); } // 详情页接收 aboutToAppear() { const params router.getParams() as Recordstring, Object; const id params[recordId] as number; // 从 AppStorage 读取完整数据 const record AppStorage.getGameRecord(currentRecord); if (record record.id id) { this.displayRecord(record); } }六、从 getParams 迁移到 Navigation在 Navigation 路由方案中参数传递方式类似但更类型安全// Navigation 方式 interface DetailParam { recordId: number; fromPage: string; } this.stack.pushPathDetailParam(pages/Detail, { recordId: 1001, fromPage: Leaderboard }); // NavDestination 中接收 Builder NavDestination() { DetailPage() } Component struct DetailPage { State recordId: number 0; aboutToAppear() { // 通过 NavPathStack 获取参数需要保存 stack 引用 } }七、常见踩坑7.1 坑一参数不存在时未提供默认值// 错误没有默认值 aboutToAppear() { const name (router.getParams() as Recordstring, string)[playerName]; this.name name; // ❌ 如果没有传 playerNamethis.name undefined } // ✅ 正确提供默认值 aboutToAppear() { const params router.getParams() as Recordstring, string; this.name params?.[playerName] ?? 匿名玩家; }7.2 坑二参数名拼写不一致// 发送方 { params: { playerId: 1001 } } // 接收方写成大写 P const id params[PlayerId]; // ❌ undefined八、总结router.getParams()是 HarmonyOSrouter路由方案中页面接收参数的标准 API在aboutToAppear中调用并用类型收窄 默认值安全地提取数据。核心要点在aboutToAppear中调用getParams()接收参数类型string/number/boolean/Object/ArrayFunction 和 Date 需特殊处理使用类型收窄 默认值确保参数安全大对象推荐存入 AppStorageparams 只传 IDNavigation 方案中通过NavPathStack.pushPath传参下一篇预告第 82 篇将深入Navigation容器——官方推荐的新一代路由架构。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源router.getParams API 参考router.pushUrl API 参考页面路由与生命周期AppStorage 全局存储router 到 Navigation 迁移开源鸿蒙跨平台社区第 80 篇router.replaceUrl第 82 篇Navigation 容器