行业资讯
HarmonyOs应用《重要日》开发第14篇 - WantAgent 实现通知点击跳转应用
本文聚焦 ImportantDays 项目中通知点击跳转的核心技术WantAgent深入解析其概念、配置参数、工作原理以及在鸿蒙通知系统中的具体应用方式。一、什么是 WantAgentWantAgent是 HarmonyOS 中的一个重要概念它封装了一个意图Intent描述了在特定条件下要执行的操作。在通知系统中使用WantAgent可以实现用户点击通知后自动执行预设操作最常见的就是打开应用的指定页面。WantAgent vs Want概念说明Want描述做什么的对象如启动某个 AbilityWantAgent封装了Want的可执行代理描述何时做、做什么简单理解Want是一张任务卡片WantAgent是把这张卡片交给系统让系统在合适时机执行。二、Importingimport{wantAgent,WantAgent}fromkit.AbilityKit;wantAgent是操作模块WantAgent是类型。三、WantAgentInfo 配置constwantAgentInfo:wantAgent.WantAgentInfo{wants:[{bundleName:com.importantdays.app,abilityName:EntryAbility,action:action.system.home}],actionType:wantAgent.OperationType.START_ABILITY,requestCode:0,wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]};字段详解wantswants:[{bundleName:com.importantdays.app,// 应用包名abilityName:EntryAbility,// 目标 Ability 名称action:action.system.home// 启动动作}]bundleName在app.json5中定义的应用包名abilityName在module.json5中定义的 Ability 名称actionaction.system.home表示从桌面启动会打开应用主界面actionTypeactionType:wantAgent.OperationType.START_ABILITYOperationType枚举值值说明START_ABILITY启动 AbilitySTART_ABILITIES启动多个 AbilitySTART_SERVICE启动服务SEND_COMMON_EVENT发送公共事件项目选择START_ABILITY因为需要打开应用界面。requestCoderequestCode:0请求码用于区分不同的 WantAgent 请求。项目中只使用一个 WantAgent所以固定为 0。wantAgentFlagswantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]WantAgentFlags常用值值说明UPDATE_PRESENT_FLAG更新已有的 WantAgentONE_TIME_FLAG只执行一次NO_BUILD_FLAG不创建新的 WantAgentCANCEL_AFTER_PRESENT_FLAG触发后取消选择UPDATE_PRESENT_FLAG确保每次获取的是最新的 WantAgent。四、创建 WantAgentstaticasyncgetDefaultWantAgent():PromiseWantAgent{constwantAgentInfo:wantAgent.WantAgentInfo{wants:[{bundleName:com.importantdays.app,abilityName:EntryAbility,action:action.system.home}],actionType:wantAgent.OperationType.START_ABILITY,requestCode:0,wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]};returnawaitwantAgent.getWantAgent(wantAgentInfo);}方法设计异步方法wantAgent.getWantAgent()是异步操作默认配置方法名getDefaultWantAgent表示使用默认配置封装复用封装在NotificationUtil中多处调用五、在通知中使用 WantAgentconstrequest:notificationManager.NotificationRequest{id:notificationId,content:{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,normal:{title:title,text:content,additionalText:}},wantAgent:agent,// ← 关键将 WantAgent 附加到通知notificationSlotType:notificationManager.SlotType.SOCIAL_COMMUNICATION};awaitnotificationManager.publish(request);wantAgent字段将意图绑定到通知当用户点击通知时系统自动触发 WantAgent 执行预设操作。六、跳转流程详解┌──────────────────────────────────────────┐ │ 1. 发布通知携带 WantAgent │ │ notificationManager.publish(request) │ └──────────────────┬───────────────────────┘ ↓ ┌──────────────────────────────────────────┐ │ 2. 通知显示在通知栏 │ │ 标题即将到来妈妈生日 │ │ 内容还有 3 天 │ └──────────────────┬───────────────────────┘ ↓ ┌──────────────────────────────────────────┐ │ 3. 用户点击通知 │ │ 系统读取 WantAgent │ └──────────────────┬───────────────────────┘ ↓ ┌──────────────────────────────────────────┐ │ 4. 触发 WantAgent │ │ actionType: START_ABILITY │ │ bundleName: com.importantdays.app │ │ abilityName: EntryAbility │ └──────────────────┬───────────────────────┘ ↓ ┌──────────────────────────────────────────┐ │ 5. 系统启动 EntryAbility │ │ 如果应用已在后台 → 带到前台 │ │ 如果应用未运行 → 启动应用 │ └──────────────────┬───────────────────────┘ ↓ ┌──────────────────────────────────────────┐ │ 6. 生命周期回调 │ │ onNewWant (如果应用已存在) │ │ onForeground (如果从后台恢复) │ │ → checkAndSendReminders() │ └──────────────────────────────────────────┘七、应用配置验证app.json5{app:{bundleName:com.importantdays.app,...}}module.json5{module:{abilities:[{name:EntryAbility,srcEntry:./ets/entryability/EntryAbility.ets,...skills:[{entities:[entity.system.home],actions:[action.system.home]}]}]}}配置一致性WantAgent 中的bundleName和abilityName必须与配置文件中的一致WantAgent 参数配置文件值bundleNameapp.json5→app.bundleNamecom.importantdays.appabilityNamemodule.json5→abilities[0].nameEntryAbilityactionmodule.json5→abilities[0].skills[0].actionsaction.system.homeskills 配置的作用skills:[{entities:[entity.system.home],actions:[action.system.home]}]skills声明了 Ability 能响应的意图。action.system.home表示该 Ability 可以响应从桌面启动的意图这也是 WantAgent 中使用action: action.system.home能正确跳转的基础。八、EntryAbility 的生命周期处理exportdefaultclassEntryAbilityextendsUIAbility{asynconCreate(want:Want,launchParam:AbilityConstant.LaunchParam):Promisevoid{// 应用首次创建时调用PreferenceUtil.init(this.context);ImportantDayManager.getInstance().init();// ...}onNewWant(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 应用已在运行通过 WantAgent 再次启动时调用console.info(EntryAbility onNewWant);}onForeground():void{// 应用回到前台时调用ImportantDayManager.getInstance().checkAndSendReminders();}}两种启动场景场景1应用未运行冷启动点击通知 → onCreate → onWindowStageCreate → onForeground ↓ 初始化数据 检查提醒场景2应用在后台热启动点击通知 → onNewWant → onForeground ↓ 检查提醒onNewWant在应用已存在实例时触发可以在此处理 Want 携带的额外数据如跳转到特定日期。九、扩展携带数据的 WantAgent当前项目的 WantAgent 只打开应用主页未来可以扩展为携带日期参数直接跳转到特定日期// 概念性扩展代码constwantAgentInfo:wantAgent.WantAgentInfo{wants:[{bundleName:com.importantdays.app,abilityName:EntryAbility,action:action.system.home,parameters:{targetDate:day.targetDate.getTime(),// 携带目标日期dayID:day.dayID// 携带重要日ID}}],// ...};然后在onNewWant中解析参数onNewWant(want:Want,launchParam:AbilityConstant.LaunchParam):void{consttargetDatewant.parameters?.targetDate;if(targetDate){CalendarVM.getInstance().changeDate(dayjs(targetDate));}}十、常见问题问题1点击通知无反应可能原因bundleName或abilityName与配置文件不匹配skills配置缺失应用被系统杀死后无法恢复排查方法检查日志中的错误信息确认配置一致性。问题2通知不显示可能原因未获取通知权限SlotType设置不当通知内容为空排查方法先调用checkPermission()确认权限。问题3重复创建 WantAgent解决方案使用UPDATE_PRESENT_FLAG标志确保复用已有 WantAgent。十一、总结WantAgent是鸿蒙通知系统的核心组件意图封装将打开应用的意图封装为可执行对象配置驱动通过WantAgentInfo精确控制跳转行为生命周期联动触发onCreate或onNewWantonForeground可扩展性支持携带参数实现精确跳转掌握WantAgent是实现通知交互的关键它让通知从只读信息变为可交互入口。
郑州网站建设
网页设计
企业官网
