鸿蒙应用开发实战【73】— 页面参数传递：params 对比 AppStorage

鸿蒙应用开发实战【73】— 页面参数传递params 对比 AppStorage本文是「号码助手全栈开发系列」第 73 篇持续更新中…开源社区https://openharmonycrossplatform.csdn.net前言在号码助手项目中页面间参数传递有两种主流方式路由 paramsrouter.pushUrl传参和全局/局部存储AppStorage/LocalStorage。错误的选型会导致参数丢失、状态污染、耦合度升高等问题。本篇从源码层面对比这两种方式的适用场景和最佳实践。本文涵盖router.pushUrl params 传参详解、getUIContext().getRouter().getParams() 接收参数、AppStorage 全局状态管理、StorageProp/StorageLink 装饰器、LocalStorage 页面级共享、两种方式的选型决策树、常见坑与解决方案。一、路由 params 传参1.1 发送方pushUrl 传参使用router.pushUrl的params字段传递参数// CardListPage.ets — 跳转时传递参数asynconCardClick(card:CardEntity):Promisevoid{router.pushUrl({url:pages/CardDetailPage,params:{cardId:card.id,cardPhone:card.phone_number,source:CardListPage,},}).catch((error:Error){promptAction.showToast({message:跳转失败});});}1.2 接收方getParams()在目标页面的aboutToAppear生命周期中获取参数// CardDetailPage.ets — 接收路由参数import{router}fromkit.ArkUI;EntryComponentstruct CardDetailPage{StatecardId:number0;StatecardPhone:string;Statesource:string;aboutToAppear():void{constparamsrouter.getParams()asRecordstring,Object;if(params){// 类型安全解析if(typeofparams[cardId]number){this.cardIdparams[cardId]asnumber;}if(typeofparams[cardPhone]string){this.cardPhoneparams[cardPhone]asstring;}if(typeofparams[source]string){this.sourceparams[source]asstring;}}// 加载数据this.loadCardDetail();}asyncloadCardDetail():Promisevoid{if(this.cardId0)return;try{this.cardawaitthis.cardDao.findById(this.cardId);}catch(error){this.loadError加载卡号详情失败;}}}1.3 getUIContext 方式在子组件中也可以通过getUIContext()获取路由参数// 子组件中获取参数Componentstruct CardInfoSection{StatecardId:number0;aboutToAppear():void{constparamsthis.getUIContext().getRouter().getParams()asRecordstring,Object;if(paramstypeofparams[cardId]number){this.cardIdparams[cardId]asnumber;}}}二、AppStorage 全局状态2.1 定义全局状态AppStorage是应用级的全局状态存储所有页面都可以读写// AppStorage.ets — 定义全局状态// 在 EntryAbility 或 AppScope 中初始化AppStorage.setOrCreate(currentUser,);AppStorage.setOrCreate(isLoggedIn,false);AppStorage.setOrCreate(selectedCardId,0);AppStorage.setOrCreateCardEntity|null(editingCard,null);2.2 StorageProp 装饰器通过StorageProp读取 AppStorage 中的值数据变更时自动刷新 UI// HomePage.ets — 使用 StoragePropEntryComponentstruct HomePage{StorageProp(isLoggedIn)isLoggedIn:booleanfalse;StorageProp(currentUser)currentUser:string;build(){Column(){if(!this.isLoggedIn){// 未登录状态Button(登录).onClick((){router.pushUrl({url:pages/LoginPage});});}else{Text(欢迎,${this.currentUser});}}}}2.3 StorageLink 双向绑定StorageLink是双向绑定版本修改组件的值会同步回AppStorage// LoginPage.ets — 使用 StorageLinkEntryComponentstruct LoginPage{StorageLink(currentUser)currentUser:string;StorageLink(isLoggedIn)isLoggedIn:booleanfalse;onLoginSuccess(userName:string):void{// 修改会同步到 AppStorage其他页面自动刷新this.currentUseruserName;this.isLoggedIntrue;router.back();}}三、LocalStorage 页面级共享3.1 在页面中共享父子组件间可以通过LocalStorage共享状态// 父页面 — 创建 LocalStorageEntryComponentstruct CardManagePage{privatelocalStorage:LocalStoragenewLocalStorage({filterStatus:全部,searchKeyword:,});build(){Column(){StatCardList(this.localStorage)SearchPanel(this.localStorage)}}}// 子组件 — 读取 LocalStorageComponentstruct StatCardList{LocalStorageProp(filterStatus)filterStatus:string全部;build(){Text(当前筛选:${this.filterStatus});}}3.2 与 State 组合使用Componentstruct FilterPanel{LocalStorageLink(filterStatus)filterStatus:string全部;LocalStorageLink(searchKeyword)searchKeyword:string;StateselectedCategories:string[][];applyFilter():void{// 修改 filterStatus 会通知所有关联组件this.filterStatus使用中;}}四、两种方式的详细对比4.1 核心特性对比特性路由 paramsAppStorage / LocalStorage数据生命周期页面导航期间应用运行期间作用域单次路由跳转全局App或页面Local数据类型可序列化的 Object任意类型含对象引用双向绑定不支持StorageLink/LocalStorageLink页面刷新需手动获取自动刷新 UI跨页面通讯不支持支持AppStorage 全局持久化不持久化默认不持久化隐私安全参数在路由栈可见仅在组件树中可见4.2 装饰器对比装饰器数据来源是否双向作用域State组件内部自更新当前组件Prop父组件传入单向父→子子组件Link父组件传入双向子组件StoragePropAppStorage单向Store→组件全局StorageLinkAppStorage双向全局LocalStoragePropLocalStorage单向Store→组件页面级LocalStorageLinkLocalStorage双向页面级4.3 选型决策矩阵场景推荐方案原因详情页传 ID路由 params一次性参数无需跨页面登录状态AppStorage全局需要多个页面读取编辑页回传数据路由 params callBack数据流向明确筛选条件共享LocalStorage页面内子组件共享主题/颜色设置AppStorage全局生效表单多步骤LocalStorage步骤间共享不污染全局五、常见坑与解决方案5.1 参数类型丢失params 传递时number类型可能被序列化为string// 错误参数类型丢失router.pushUrl({url:pages/DetailPage,params:{id:123,// 传递后可能变为 123},});// 正确接收时做类型断言和校验aboutToAppear():void{constparamsrouter.getParams()asRecordstring,Object;if(paramstypeofparams[id]number){this.idparams[id]asnumber;}elseif(paramstypeofparams[id]string){this.idparseInt(params[id]asstring,10);}}5.2 AppStorage 值未初始化// 错误未初始化就读取StorageProp(selectedCardId)selectedCardId:number0;// 如果 selectedCardId 从未通过 setOrCreate 初始化读取可能为 undefined// 正确在 Ability 中统一初始化onCreate():void{AppStorage.setOrCreate(selectedCardId,0);AppStorage.setOrCreate(isLoggedIn,false);}5.3 参数透传过多// 不推荐传递太多参数router.pushUrl({url:pages/AppDetailPage,params:{appId:app.id,appName:app.name,appCategory:app.category,cardId:app.card_id,cardLabel:app.cardLabel,cardPhone:app.cardPhone,status:app.status,// ... 更多参数},});// 推荐只传 ID页面自行查询router.pushUrl({url:pages/AppDetailPage,params:{appId:app.id,// 只传 IDDetailPage 根据 ID 查询完整数据},});六、选型决策树需要传递什么数据 ├── 页面导航的标识参数ID、类型 │ └── 路由 params ✅ ├── 全局共享状态登录、主题 │ └── AppStorage ✅ ├── 页面内子组件共享筛选条件 │ └── LocalStorage ✅ └── 编辑回传数据 ├── 简单数据 → router.back() callBack ✅ └── 复杂数据 → AppStorage 临时存 ✅小结要点说明典型场景路由 paramspushUrl传递getParams()接收详情页传 IDAppStorage全局单例StorageProp/StorageLink登录状态、主题LocalStorage页面级共享LocalStorageProp/LocalStorageLink多步骤表单类型安全params 接收时需typeof校验避免 number 变 string最少参数原则只传必要标识由页面自行查询减少耦合初始化检查AppStorage 使用前必须setOrCreate避免 undefined如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源openHarmony 跨平台社区https://openharmonycrossplatform.csdn.netHarmonyOS 页面路由官方文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-routing-0000001820880697AppStorage LocalStorage 官方文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-appstorage-0000001821000733