HarmonyOS应用开发实战：猫猫大作战-ReminderRequest 的使用

前言ReminderRequest是 HarmonyOS 的提醒服务能力支持创建定时提醒、日历提醒和倒计时提醒。在「猫猫大作战」中我们可以通过提醒功能让玩家每天定时回来领取签到奖励、通知活动开始、或者在体力回满时收到提醒。与workScheduler后台任务不同ReminderRequest 的提醒会在系统通知栏以“实况通知“形式显示用户可以看到醒目的提醒卡片点击后跳转到游戏。本文以「猫猫大作战」的每日游戏提醒为锚点讲解 ReminderRequest 的完整使用方法。提示本系列不讲 ArkTS 基础语法与环境搭建。本篇是阶段五第 164 篇。一、ReminderRequest 基础1.1 三种提醒类型import { reminderAgent } from kit.ReminderKit; // 类型 1定时提醒每日固定时间 const alarmReminder: reminderAgent.ReminderRequestAlarm { reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, hour: 20, minute: 0, daysOfWeek: [1, 2, 3, 4, 5, 6, 7], // 每天 title: 猫猫大作战, content: 猫咪们等你回来合并呢, notificationId: 2001, wantAgent: { /* 点击跳转 */ }, }; // 类型 2日历提醒指定日期 const calendarReminder: reminderAgent.ReminderRequestCalendar { reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, dateTime: { year: 2026, month: 8, day: 1, hour: 10, minute: 0 }, title: 夏日活动开启, content: 双倍积分活动开始了, notificationId: 2002, }; // 类型 3倒计时提醒多久之后 const countdownReminder: reminderAgent.ReminderRequestTimer { reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, triggerTimeInSeconds: 3600, // 1 小时后 title: 体力恢复提醒, content: 体力已回满继续游戏吧, notificationId: 2003, };类型枚举值用途触发方式AlarmREMINDER_TYPE_ALARM每日定时提醒hourminutedaysOfWeekCalendarREMINDER_TYPE_CALENDAR指定日期提醒dateTime对象TimerREMINDER_TYPE_TIMER倒计时提醒triggerTimeInSeconds提示notificationId必须唯一用于更新或取消提醒。建议使用模块前缀区分不同提醒类型如 2xxx 段。二、创建提醒2.1 每日定时提醒async function createDailyReminder(context: Context): Promisenumber { const reminder: reminderAgent.ReminderRequestAlarm { reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, hour: 20, minute: 0, daysOfWeek: [1, 2, 3, 4, 5, 6, 7], // 每天 title: 猫猫大作战, content: 猫咪们等你回来合并呢快来领取每日奖励, notificationId: 2001, wantAgent: { pkgName: com.maomaodazuozhan.game, abilityName: EntryAbility, // 附加参数可在 EntryAbility 中读取 parameters: { action: daily_reminder }, }, maxScreenWantAgent: { pkgName: com.maomaodazuozhan.game, abilityName: EntryAbility, }, expiredContent: 今日提醒已过期, snoozeTimes: 2, // 最多推迟 2 次 timeInterval: 10, // 每 10 分钟推迟一次 }; const reminderId await reminderAgent.publishReminder(reminder); console.info(每日提醒已创建ID: ${reminderId}); return reminderId; }2.2 参数详解参数类型说明示例值hournumber提醒小时 (0-23)20minutenumber提醒分钟 (0-59)0daysOfWeeknumber[]每周天数 (1周日, 2周一…)[1,2,3,4,5,6,7]titlestring提醒标题显示在通知栏‘猫猫大作战’contentstring提醒内容‘来合并猫咪吧’notificationIdnumber唯一 ID用于更新/取消2001wantAgentobject点击提醒后的跳转配置{ pkgName, abilityName }snoozeTimesnumber推迟次数上限2timeIntervalnumber推迟间隔分钟10三、点击提醒跳转3.1 WantAgent 配置// 点击提醒后跳转到游戏并自动进入活动页面 const wantAgent: reminderAgent.WantAgent { pkgName: com.maomaodazuozhan.game, abilityName: EntryAbility, parameters: { action: open_activity, activityId: summer_2026, from: reminder, }, };3.2 在 EntryAbility 中接收// 来源entry/src/main/ets/entryability/EntryAbility.ets import { UIAbility, Want } from kit.AbilityKit; export default class EntryAbility extends UIAbility { onNewWant(want: Want): void { // 处理从提醒点击传入的参数 const action want.parameters?.action as string; const from want.parameters?.from as string; if (from reminder) { switch (action) { case daily_reminder: // 打开签到页面 this.openSignInPage(); break; case open_activity: // 打开活动页面 const activityId want.parameters?.activityId as string; this.openActivityPage(activityId); break; } } } private openSignInPage(): void { // 路由到签到页 console.info(从提醒跳转到签到页); } private openActivityPage(id: string): void { console.info(从提醒跳转到活动页: ${id}); } }四、提醒的增删改查4.1 取消提醒async function cancelReminder(reminderId: number): Promisevoid { try { await reminderAgent.cancelReminder(reminderId); console.info(提醒 ${reminderId} 已取消); } catch (err) { console.error(取消提醒失败: ${err.message}); } } // 取消所有提醒 async function cancelAllReminders(context: Context): Promisevoid { const reminders await reminderAgent.queryReminders(context); for (const r of reminders) { await reminderAgent.cancelReminder(r.reminderId); } console.info(已取消 ${reminders.length} 个提醒); }4.2 查询提醒async function listAllReminders(context: Context): Promisevoid { const reminders await reminderAgent.queryReminders(context); console.info(当前有 ${reminders.length} 个活跃提醒:); for (const r of reminders) { console.info( ID${r.reminderId}, type${r.reminderType}, title${r.title}, content${r.content} ); } } async function getReminderById(reminderId: number): PromisereminderAgent.ReminderRequest | null { try { const reminders await reminderAgent.queryReminders(getContext() as Context); return reminders.find(r r.reminderId reminderId) ?? null; } catch { return null; } }操作API参数说明创建publishReminder(reminder)Reminder 对象返回 reminderId取消cancelReminder(id)提醒 ID取消单个提醒查询queryReminders(context)Context返回所有提醒列表更新先取消再创建原 ID 失效Reminder 不支持直接修改五、游戏中的应用场景5.1 每日签到提醒async function setupSignInReminder(context: Context): Promisevoid { // 用户设置提醒时间从 Preferences 读取 const prefs await preferences.getPreferences(context, game_prefs); const reminderHour prefs.get(reminder_hour, 20) as number; const reminderMinute prefs.get(reminder_minute, 0) as number; const reminder: reminderAgent.ReminderRequestAlarm { reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, hour: reminderHour, minute: reminderMinute, daysOfWeek: [1, 2, 3, 4, 5, 6, 7], title: 猫猫大作战 - 每日签到, content: 签到领取免费猫咪和金币, notificationId: 2001, wantAgent: { pkgName: com.maomaodazuozhan.game, abilityName: EntryAbility, parameters: { action: sign_in }, }, }; await reminderAgent.publishReminder(reminder); }5.2 活动开始提醒async function createEventReminder( context: Context, eventDate: Date, eventName: string ): Promisenumber { const reminder: reminderAgent.ReminderRequestCalendar { reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, dateTime: { year: eventDate.getFullYear(), month: eventDate.getMonth() 1, day: eventDate.getDate(), hour: eventDate.getHours(), minute: eventDate.getMinutes(), }, title: ${eventName}, content: 限时活动已开始登录领取奖励, notificationId: 3001, wantAgent: { pkgName: com.maomaodazuozhan.game, abilityName: EntryAbility, parameters: { action: open_event }, }, }; return await reminderAgent.publishReminder(reminder); }5.3 体力恢复提醒倒计时async function createEnergyReminder(context: Context): Promisenumber { // 假设体力每 30 分钟恢复 1 点满 5 点需要 2.5 小时 const ENERGY_FULL_TIME 150; // 分钟 const seconds ENERGY_FULL_TIME * 60; const reminder: reminderAgent.ReminderRequestTimer { reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, triggerTimeInSeconds: seconds, title: ⚡ 体力恢复, content: 体力已回满继续挑战高分吧, notificationId: 3002, wantAgent: { pkgName: com.maomaodazuozhan.game, abilityName: EntryAbility, parameters: { action: open_game }, }, }; return await reminderAgent.publishReminder(reminder); }六、提醒样式6.1 系统通知样式// ReminderRequest 在系统通知栏显示为实况通知样式 // 包含应用图标、标题、内容、时间、点击跳转提示 // 提醒显示效果 ┌─────────────────────────────────┐ │ 猫猫大作战 │ │ ─────────────────────── │ │ 猫咪们等你回来合并呢 │ │ 20:00 │ │ [推迟] [确定] │ └─────────────────────────────────┘6.2 自定义参数const reminder: reminderAgent.ReminderRequestAlarm { // ... 基础参数 // 提醒内容在锁屏上的展示策略 maxScreenWantAgent: { pkgName: com.maomaodazuozhan.game, abilityName: EntryAbility, }, // 过期内容提醒触发后未操作时显示 expiredContent: 今日提醒已过期点击查看活动详情, // 推迟行为 snoozeTimes: 2, // 最多推迟 2 次 timeInterval: 10, // 每次推迟间隔 10 分钟 };七、权限与限制7.1 权限声明// module.json5 中声明 { module: { requestPermissions: [ { name: ohos.permission.PUBLISH_AGENT_REMINDER, reason: $string:reminder_permission_reason, }, ], }, }7.2 运行时权限async function ensureReminderPermission(context: Context): Promiseboolean { const atManager abilityAccessCtrl.createAtManager(); try { const result await atManager.requestPermissionsFromUser(context, [ ohos.permission.PUBLISH_AGENT_REMINDER, ]); return result.authResults[0] 0; } catch (err) { console.error(提醒权限获取失败: ${err.message}); return false; } }7.3 限制限制项说明最大提醒数单应用最多 50 个活跃提醒最小倒计时triggerTimeInSeconds 60至少 1 分钟重复间隔repeatCycleTime 60 * 60 * 1000至少 1 小时权限必须声明PUBLISH_AGENT_REMINDER实况通知仅 Alarm 和 Calendar 类型支持提示提醒数量建议控制在 10 个以内过多会影响系统性能和用户体验。八、调试与测试// 在模拟器中测试提醒 // 1. 创建提醒后等待触发 // 2. 使用 hdc 修改系统时间加速测试 // hdc shell date -s 2026-07-28 19:59:50 // 3. 等待 10 秒触发提醒 // 代码内验证提醒是否生效 async function verifyReminderCreated(context: Context): Promiseboolean { const reminders await reminderAgent.queryReminders(context); const targetReminder reminders.find(r r.title.includes(猫猫大作战)); if (targetReminder) { console.info(提醒已生效: ID${targetReminder.reminderId}); return true; } console.warn(未找到提醒请检查创建逻辑); return false; }九、常见问题问题原因解决方法提醒未触发权限未授予检查 PUBLISH_AGENT_REMINDER 权限点击提醒未跳转WantAgent 配置错误检查 pkgName 和 abilityName提醒多次触发重复创建未清理创建前先取消旧提醒倒计时不准系统休眠限制使用 Alarm 定时间而非 Timer推送栏不显示notificationId 冲突使用唯一 ID十、最佳实践提醒数量精简最多 3-5 个活跃提醒避免骚扰用户提供推迟功能设置snoozeTimes和timeInterval给用户灵活性跳转带参数在parameters中传 action区分不同场景用户可配置让用户可以设置提醒时间和类型销毁时清理应用卸载或用户退出时取消所有提醒测试覆盖每种提醒类型至少测试一次触发和跳转// 用户设置提醒偏好 async function updateReminderSettings( context: Context, enabled: boolean, hour?: number, minute?: number ): Promisevoid { // 先取消所有旧提醒 const reminders await reminderAgent.queryReminders(context); for (const r of reminders) { await reminderAgent.cancelReminder(r.reminderId); } if (enabled hour ! undefined minute ! undefined) { // 创建新提醒 await createDailyReminder(context); console.info(提醒已更新: ${hour}:${minute}); } else { console.info(提醒已关闭); } }总结ReminderRequest 提供三种提醒类型——定时、日历、倒计时适用于游戏中的每日签到提醒、活动通知和体力恢复提醒。核心要点Alarm 定时每日提醒、 Calendar 指定日期活动、 Timer 倒计时提醒、 WantAgent 点击跳转带参数、 snoozeTimes 推迟机制、 notificationId 唯一标识。下一篇将深入 LiveViewKit——实况窗与锁屏得分展示。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源ReminderAgent API 参考ReminderRequest 官方指南WantAgent 跳转配置通知栏与提醒最佳实践BACKGROUNDTASKS_KIT 权限定时提醒设计规范开源鸿蒙跨平台社区HarmonyOS 开发者官方文档第 163 篇workScheduler第 165 篇LiveViewKit