044-reminderAgent代理提醒

044 — reminderAgent 代理提醒定时记账通知的实现方案简介记账应用的核心挑战之一是培养用户的持续记账习惯。MoneyTrack 通过reminderAgent代理提醒能力实现了每日定时记账通知——用户在每天设定的时间收到系统级提醒点击提醒后直接跳转到记账页面。这项能力依赖于PUBLISH_AGENT_REMINDER权限声明和reminderAgentManager的发布/取消接口是提升用户留存率的关键基础设施。reminderAgentManager 完整参数发布代理提醒时reminder 对象支持以下完整参数配置参数类型必填说明reminderTypeReminderType是提醒类型TIMER / ALARM / CALENDARtriggerTimeInSecondsnumber是触发时间距当前秒数TIMER 类型triggerDateTimenumber否触发日期时间戳ALARM/CALENDAR 类型wantAgentWantAgent否点击提醒后跳转的 WantAgenttitlestring是提醒标题contentstring是提醒内容文本ringDurationnumber否响铃时长秒默认 30 秒notificationIdnumber否指定通知 ID用于更新或取消特定通知actionButtonActionButton[]否提醒通知上的操作按钮列表snoozeContentstring否稍后提醒的内容文本snoozeIntervalnumber否稍后提醒的间隔时间分钟maxSnoozeCountnumber否最大稍后提醒次数import{reminderAgentManager}fromkit.ReminderAgentKit;import{wantAgent}fromkit.AbilityKit;asyncfunctionpublishRichReminder(){constwantAgentObjawaitwantAgent.getWantAgent({wants:[{bundleName:com.moneytrack,abilityName:AddBillAbility}],operationType:wantAgent.OperationType.START_ABILITY});constreminder{reminderType:reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,triggerTimeInSeconds:3600,wantAgent:wantAgentObj,title:记账提醒,content:别忘了记录今天的收支哦,ringDuration:45,notificationId:1001,actionButton:[{title:立即记账,wantAgent:wantAgentObj,type:0},{title:稍后提醒,type:1// 稍后提醒类型}],snoozeContent:已推迟提醒记得记账哦,snoozeInterval:15,maxSnoozeCount:3};constreminderIdawaitreminderAgentManager.publishReminder(reminder);returnreminderId;}提醒类型对比reminderAgentManager 支持三种提醒类型适用于不同场景对比维度REMINDER_TYPE_TIMERREMINDER_TYPE_ALARMREMINDER_TYPE_CALENDAR触发方式倒计时距当前秒数指定时刻日期时间绑定日历事件重复设置不支持自动重复支持每日/每周重复按日历事件规则重复跨天处理自动处理需手动计算时间差自动根据日历处理典型场景倒计时、稍后提醒每日记账提醒、闹钟会议提醒、生日提醒参数关键字段triggerTimeInSecondstriggerDateTimeeventId系统优先级普通较高可响铃中等定时提醒的跨天处理当用户在晚上设置次日早上提醒时triggerTimeInSeconds必须正确跨越零点计算。错误的计算会导致提醒立即触发或永不到期staticgetNextTriggerSeconds(hour:number,minute:number):number{constnownewDate();consttargetnewDate();target.setHours(hour,minute,0,0);letdiffMath.floor((target.getTime()-now.getTime())/1000);// 如果目标时间已过设为次日同一时间if(diff0){target.setDate(target.getDate()1);diffMath.floor((target.getTime()-now.getTime())/1000);}returndiff;}// 每日重复提醒使用 ALARM 类型staticasyncpublishDailyAlarm(hour:number,minute:number){constnownewDate();consttargetnewDate();target.setHours(hour,minute,0,0);// 如果目标已过推到明天if(target.getTime()now.getTime()){target.setDate(target.getDate()1);}constreminder{reminderType:reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM,triggerDateTime:target.getTime(),title:每日记账提醒,content:已到${hour}:${minute}记得记账,ringDuration:30,notificationId:1001};returnawaitreminderAgentManager.publishReminder(reminder);}权限说明发布代理提醒需要声明ohos.permission.PUBLISH_AGENT_REMINDER权限。该权限为 system_basic 级别需在应用市场审核通过后生效。在module.json5中声明{module:{requestPermissions:[{name:ohos.permission.PUBLISH_AGENT_REMINDER,reason:用于发布每日记账提醒,usedScene:{abilities:[AddBillAbility],when:always}}]}}注意事项system_basic 级别权限要求应用通过华为应用市场审核上架后才能获得授权。调试阶段可在设备上通过bm set -signDebugInfo开启调试模式绕过权限校验。此外提醒功能还依赖ohos.permission.NOTIFICATION_CONTROLLER用于发送通知和后台任务权限。提醒生命周期流程目标页面系统通知栏reminderAgentManagerMoneyTrack用户目标页面系统通知栏reminderAgentManagerMoneyTrack用户等待触发可能跨天用户关闭提醒设置每日记账提醒20:00计算 triggerTimeInSecondspublishReminder(reminder)返回 reminderId提示提醒已设置时间到达发送通知显示通知栏提醒点击提醒通知解析 WantAgent启动 Ability打开记账页面关闭每日提醒开关cancelReminder(reminderId)取消成功提示提醒已关闭最佳实践优先使用 ALARM 类型实现每日提醒TIMER 类型每次需要重新计算倒计时而 ALARM 类型支持每日重复更适合每日 X 点提醒的场景。提前检查权限状态在发布提醒前通过reminderAgentManager.checkReminderPermission()检查权限是否已授予。保存 reminderId 用于后续管理发布的提醒返回唯一 ID应存储到本地数据库供取消、更新操作使用。避免重复发布提醒在设置新提醒前先取消之前同类型的提醒防止多条重复提醒同时触发。合理设置 ringDuration响铃时长不宜过短用户可能未及时查看也不宜过长打扰用户建议 30-45 秒。跨天场景充分测试特别关注深夜 23:00 后设置次日提醒的场景确保时间计算正确。项目代码案例文件路径lib_reminder/ReminderUtil.etsimport{reminderAgentManager}fromkit.ReminderAgentKit;import{wantAgent}fromkit.AbilityKit;exportclassReminderUtil{privatestaticsavedReminderId:number-1;staticasyncpublishDailyReminder(hour:number,minute:number){// 先取消已有提醒if(this.savedReminderId0){awaitthis.cancelReminder(this.savedReminderId);}constwantAgentInfo{wants:[{bundleName:com.moneytrack,abilityName:AddBillAbility}],operationType:wantAgent.OperationType.START_ABILITY};constwantAgentObjawaitwantAgent.getWantAgent(wantAgentInfo);constnownewDate();consttargetnewDate();target.setHours(hour,minute,0,0);if(target.getTime()now.getTime()){target.setDate(target.getDate()1);}constreminder{reminderType:reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM,triggerDateTime:target.getTime(),wantAgent:wantAgentObj,title:记账提醒,content:别忘了记录今天的收支哦当前时间${hour}:${String(minute).padStart(2,0)},ringDuration:30,notificationId:1001};this.savedReminderIdawaitreminderAgentManager.publishReminder(reminder);returnthis.savedReminderId;}staticasynccancelReminder(reminderId:number){awaitreminderAgentManager.cancelReminder(reminderId);this.savedReminderId-1;}staticasynccheckPermission():Promiseboolean{returnawaitreminderAgentManager.checkReminderPermission();}}推荐参考文档后台任务与代理提醒指南reminderAgentManager API 参考kit.ReminderAgentKit API 参考