第3篇｜Want 参数一传就丢：把跳转协议和接收边界写清楚

第3篇｜Want 参数一传就丢：把跳转协议和接收边界写清楚

摘要：实际项目里，页面跳转最怕的不是不能跳，而是“看起来跳过去了，参数却没了”。列表点详情、消息点订单、外部 Ability 拉起业务页，只要参数名、类型和接收时机没有统一，问题就会变成随机出现。我的做法是把 Want 当成一份工程协议来写：发起端只表达意图，协议层统一字段，接收端只消费解析后的安全值。

做 HarmonyOS 项目时，我遇到过一个很典型的问题：用户从首页卡片进入详情页没问题，从通知入口进入同一个详情页却空白；日志里没有明显异常，页面也确实创建了，最后发现只是courseId在不同入口被写成了id、targetId和course_id三种名字。

这篇文章解决四件事：

1. 如何把 Want 参数从“临时拼字段”变成稳定协议。
2. 发起端、接收端、页面层各自应该负责什么。
3. 参数缺失、类型错误、入口不一致时怎么兜底。
4. 如何用一套清单复查跳转链路。

先把问题定性：这不是页面问题，而是协议问题

如果详情页拿不到参数，很多人第一反应是改页面：加默认值、补空态、在aboutToAppear里多判几层。短期能遮住空白，长期会让问题越来越散。

更稳的定性是：只要多个入口能进入同一个业务页，就必须有一份跳转协议。协议里至少写清楚：

页面不应该猜“别人可能传了什么”。页面只应该拿到已经整理过的安全值。

把参数名集中到 RouteContract

实际项目里，Want 参数最容易坏在字段名。一个入口写id，另一个入口写courseId，页面临时兼容几次后，后续维护就没人敢动。

我会先建一个很薄的协议文件，把参数名集中起来：

// common/route/RouteContract.etsexportconstCourseDetailRoute={abilityName:'EntryAbility',page:'pages/CourseDetailPage',params:{courseId:'courseId',source:'source',fromNotification:'fromNotification'}}asconstexporttypeCourseSource='home_card'|'search_result'|'notification'

这段代码不复杂，关键是边界清晰：字段名不再散落在按钮、卡片、通知回调里；后面改参数名时，只需要先看协议文件。source不是为了展示，而是为了排查入口差异。线上出现参数缺失时，它能告诉你问题来自首页、搜索还是通知。

发起端只表达业务意图

发起端不要关心接收页内部怎么渲染，它只要把“我要打开哪个课程”说清楚。下面是首页课程卡片的写法：

// pages/HomePage.etsimport{CourseDetailRoute,CourseSource}from'../common/route/RouteContract'functionbuildCourseDetailWant(courseId:string,source:CourseSource):Want{return{bundleName:'com.example.learning',abilityName:CourseDetailRoute.abilityName,parameters:{targetPage:CourseDetailRoute.page,[CourseDetailRoute.params.courseId]:courseId,[CourseDetailRoute.params.source]:source}}}asyncfunctionopenCourseDetail(context:common.UIAbilityContext,courseId:string){constwant=buildCourseDetailWant(courseId,'home_card')awaitcontext.startAbility(want)}

这里有两个工程意图：第一，Want 的构造函数只暴露业务参数，不让调用方随便塞字段；第二，targetPage和业务参数一起交给统一入口，让 Ability 可以按协议分发。这样入口多起来以后，通知、搜索、卡片都能复用同一套构造方式。

接收端不要直接把 Want 塞给页面

接收端最容易偷懒：拿到want.parameters后直接写入全局状态，页面再从全局状态里读。这样做的问题是，脏数据会扩散到页面层，后面每个页面都要自己补防御。

更稳的做法是在 Ability 里先做解析：

// entryability/EntryAbility.etsimport{CourseDetailRoute}from'../common/route/RouteContract'import{CourseRouteParser}from'../common/route/CourseRouteParser'onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{constrouteResult=CourseRouteParser.parse(want)if(!routeResult.ok){console.error(`[route] invalid course detail want:${routeResult.reason}`)AppStorage.setOrCreate('pendingRoute',{page:'pages/HomePage',reason:routeResult.reason})return}AppStorage.setOrCreate('pendingRoute',{page:CourseDetailRoute.page,courseId:routeResult.courseId,source:routeResult.source})}

这段代码的重点不是AppStorage，而是“先解析，再交给页面”。接收端只把安全结果写出去，页面不再面对各种可能的 Want 形态。失败时也不要静默回首页，要把失败原因留下来，方便后续排查。

Parser 负责把不可信输入变成安全结果

Want 是跨入口传来的数据，不能默认可信。尤其是通知、系统入口、外部 Ability 拉起时，参数可能缺失、类型不对，甚至是旧版本留下的字段。

// common/route/CourseRouteParser.etsimport{CourseDetailRoute,CourseSource}from'./RouteContract'typeCourseRouteResult=|{ok:true;courseId:string;source:CourseSource}|{ok:false;reason:string}exportclassCourseRouteParser{staticparse(want:Want):CourseRouteResult{constparams=want.parameters??{}constrawCourseId=params[CourseDetailRoute.params.courseId]constrawSource=params[CourseDetailRoute.params.source]if(typeofrawCourseId!=='string'||rawCourseId.trim().length===0){return{ok:false,reason:'missing_course_id'}}constsource=this.normalizeSource(rawSource)return{ok:true,courseId:rawCourseId.trim(),source}}privatestaticnormalizeSource(value:Object|undefined):CourseSource{if(value==='search_result'||value==='notification'){returnvalue}return'home_card'}}

这里的输入边界很明确：Parser 信任的是解析后的结果，不信任原始parameters。必需参数缺失时直接失败；可选来源字段可以给默认值。页面拿到的永远是稳定结构，而不是一包松散对象。

页面只读取安全路由状态

页面层不要再关心 Want 的原始字段名。它只读取接收端整理好的pendingRoute，然后决定渲染详情、空态或返回入口。

// pages/CourseDetailPage.ets@Entry@Componentstruct CourseDetailPage{@StorageLink('pendingRoute')pendingRoute:Record<string,Object>={}@StatecourseId:string=''aboutToAppear():void{constvalue=this.pendingRoute['courseId']if(typeofvalue==='string'&&value.length>0){this.courseId=value}}build(){Column(){if(this.courseId.length>0){CourseDetailContent({courseId:this.courseId})}else{RouteErrorView({message:'课程入口参数不完整，请返回后重试'})}}}}

页面仍然做了一层保护，但这层保护只负责 UI 安全，不负责修复协议。这样职责不会倒挂：协议层解决参数可信问题，页面层解决展示问题。

通知入口要复用同一个构造函数

通知入口最容易绕开页面里的公共方法，因为它经常写在另一个服务或工具文件里。只要这里重新拼一次 Want，字段漂移就会回来。

// service/NotificationJumpService.etsimport{buildCourseDetailWant}from'../pages/HomePage'exportclassNotificationJumpService{staticasyncopenCourseFromNotice(context:common.UIAbilityContext,courseId:string){constwant=buildCourseDetailWant(courseId,'notification')awaitcontext.startAbility(want)}}

如果项目不适合从页面文件导出函数，就把buildCourseDetailWant移到common/route/CourseWantFactory.ets。重点是：每个入口都要走同一份工厂，而不是各写各的。

我会怎样复查这条链路

复查时不要只点一个入口。至少按下面顺序走一轮：

1. 首页卡片进入详情，确认courseId正确。
2. 搜索结果进入详情，确认来源字段不是默认值。
3. 通知入口进入详情，确认页面不是空态。
4. 手动删掉必需参数，确认会进入兜底页。
5. 切后台再回来，确认路由状态没有被覆盖。

这套复查的价值在于，它覆盖了发起端、Ability 接收端、Parser 和页面渲染四个边界。

常见问题和处理方式

小结：把 Want 当协议，不要当临时参数包

Want 跳转稳定的关键，不是每个页面都多写几层判断，而是把协议边界提前立住。字段名集中、构造函数统一、接收端先解析、页面只读安全值，这四步做完以后，跳转问题会从“到处猜参数”变成“按链路定位”。这才是多入口页面长期可维护的写法。