鸿蒙后台定时提醒开发：用ReminderAgentManager实现系统级闹钟

做鸿蒙应用开发，最容易被问到也最容易翻车的，就是后台任务里的定时提醒。我看到不少新手的第一反应是“开个 setTimeout、丢一个 Worker 线程”，结果 App 一退到后台，或者用户一锁屏，提醒就石沉大海。这其实不是代码写得不对，而是没有理解鸿蒙对后台任务的管控逻辑。

这篇内容打算把“鸿蒙后台任务里的定时提醒”讲透：先用大白话讲清楚为什么不能自己“偷着跑”，再给一份可以直接抄的代码，把提醒发布、取消、跳转、重启恢复这些环节全部串起来。不管你是正在做闹钟、日程、待办，还是吃药提醒、抢菜提醒，都值得花几分钟看完。

1. 为什么鸿蒙定时提醒要交给“系统托管”

1.1 定时提醒的典型场景与真实需求

定时提醒这类需求，看起来就是“到点弹个通知”，但实际落在不同场景里，要求差别很大。

最典型的是闹钟提醒。用户设置了早上 8 点起床，可能前一天晚上就把 App 划掉了，甚至手机重启过。这种情况下，提醒任务必须脱离 App 进程独立存在，否则应用都死了谁来触发？

其次是日程和待办提醒。这类提醒通常在当天某个时间点触发，比如“下午 3 点开会”，用户希望手机弹一条通知、响一声，最好还能直接点进应用看详情。

还有一类是周期性提醒，比如“每天上午 9 点喝水”“每周一早上同步账单”。这里涉及的不只是到点弹通知，还牵扯到后台数据准备。

这些场景共同的痛点是：定时器的生命周期必须比 App 进程长，触发时机要可靠，并且不能靠开发者自己保活。

1.2 鸿蒙后台任务机制：为什么不能无脑开线程

很多人第一次在鸿蒙上写提醒功能，下意识就用 setTimeout 或者自己 setInterval 轮询。应用在前台时没问题，但一旦退到后台，鸿蒙的资源管控就会介入。为了省电、为了流畅度，系统会挂起后台应用的 CPU 执行，甚至直接回收进程。

你不是代码写得有问题，而是系统根本不允许你“偷偷活着”。

鸿蒙把后台任务分了几个层级，每一层的定位和限制都不一样。我整理了一张表：

定时提醒这件事，应该走的是第一类：后台代理提醒。它的核心思想是“你把提醒规范交给我，到点了我来替你执行”。这样即使应用进程被回收，系统也能准时把提醒弹出来。

1.3 方案选型：提醒走代理，数据准备走延迟任务

我见过不少同学把“定时提醒”和“后台任务”混为一谈，觉得只要后台任务能跑，就什么都能干。实际上正确的做法是拆开看：

• 需要准点提醒用户的部分，交给 ReminderAgentManager。
• 需要提前准备数据的部分，比如每天早上 8 点从服务器拉取当天待办再弹提醒，如果对秒级精度不敏感，可以用 WorkScheduler 在系统空闲时段执行，而不是在闹钟响的瞬间才临时请求网络。

一句话总结：提醒要做成“托管式”的，后台准备要做成“可延迟的”，不要把所有东西都塞进一个自定义线程里熬着。

2. 环境准备与工程基础

2.1 开发环境和目标版本

要在鸿蒙上实现定时提醒，我默认你用的是 Stage 模型 + DevEco Studio 4.0 及以上，目标 API 版本建议是 9 及以上。如果你的同事还在用 FA 模型的老工程，建议尽早迁移到 Stage，官方新特性基本都在 Stage 模型上优先支持。

API 9 和 API 10 在提醒接口上差别不大，核心的 reminderAgentManager 模块一直很稳定。如果你的工程用的是 API 12 或更新版本，也兼容，只是新 SDK 里有些模块被封装到了 Kit 里，比如 @kit.RemoteNotificationKit，但底层能力一致。短期做 demo 用 @ohos.reminderAgentManager 就够了。

2.2 模块配置与权限申请

在 HarmonyOS 工程里新增提醒能力，需要在 module.json5 里做权限声明。

打开模块的 module.json5，找到 requestPermissions 字段，如果没有就按下面这样加：

json5复制{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.PUBLISH_AGENT_REMINDER",
        "reason": "$string:reminder_permission_reason",
        "usedScene": {
          "abilities": ["EntryAbility"]
        }
      }
    ]
  }
}

这个权限属于普通权限，在配置里声明即可，不需要像定位、相机那样弹窗申请。它表示允许应用发布后台代理提醒。

但要注意，提醒发出来之后，最终展示在用户面前的是一条系统通知。如果用户在系统设置里把应用的通知开关关闭了，提醒就只剩下声音和横幅的“静默”效果，甚至完全没有表现。所以仅声明权限还不够，还要在代码里主动请求通知授权。

我在 EntryAbility 的 onWindowStageCreate 里做了通知权限申请：

typescript复制import notificationManager from '@ohos.notificationManager';

notificationManager.requestEnableNotification().then(() => {
  console.info('用户已授权通知');
}).catch((err) => {
  console.error('通知授权失败：' + JSON.stringify(err));
});

这段代码弹出来的是系统标准的通知授权弹窗，用户点“允许”之后，后续提醒才能正常展示。

2.3 真机与模拟器的差异

我最早在这块踩过一个坑：模拟器上发布提醒一切正常，一换真机就完全没反应。后来发现是模拟器默认把通知都放行了，而真机上部分国产 ROM 对通知有额外管控。所以做提醒功能，建议从一开始就在真机上调试。

另外模拟器的系统时间容易和宿主机不一致，倒计时类提醒容易算错时间，排查起来很头疼。

3. 核心实现：定时提醒的完整落地

3.1 发布提醒的三种方式

reminderAgentManager 提供了三种提醒类型，分别对应不同场景。

其中闹钟和日历最常用，倒计时适合用于“番茄钟”这类场景。下面我分别给示例。

3.2 创建闹钟提醒的完整代码

先看闹钟。我拿“每个工作日早上 9 点提醒晨会”举例。

typescript复制import reminderAgentManager from '@ohos.reminderAgentManager';
import wantAgent from '@ohos.app.ability.wantAgent';

async function publishWorkdayReminder() {
  // 1. 先构造一个 WantAgent，用于用户点击提醒后跳转到应用页面
  const wantAgentInfo = {
    wants: [
      {
        bundleName: 'com.example.reminderdemo',
        abilityName: 'EntryAbility'
      }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
  };

  const wantAgentObj = await wantAgent.getWantAgent(wantAgentInfo);

  // 2. 构造闹钟提醒对象
  const reminder: reminderAgentManager.ReminderRequestAlarm = {
    reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM,
    hour: 9,
    minute: 0,
    // 注意：1 表示周日，2 表示周一，依次类推，7 表示周六
    // 所以周一到周五用 [2, 3, 4, 5, 6]
    daysOfWeek: [2, 3, 4, 5, 6],
    title: '晨会提醒',
    content: '该去参加晨会了',
    ringDuration: 30,
    snoozeTimes: 3,
    timeInterval: 10,
    wantAgent: wantAgentObj,
    actionButton: [
      {
        title: '完成',
        type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
      },
      {
        title: '再睡一会',
        type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
      }
    ]
  };

  // 3. 发布提醒
  try {
    const reminderId = await reminderAgentManager.publishReminder(reminder);
    console.info('发布成功，提醒 ID = ' + reminderId);
    // 这里建议把 reminderId 持久化，后面取消时会用到
  } catch (err) {
    console.error('发布失败：' + JSON.stringify(err));
  }
}

这段代码有几个细节需要展开说。

ringDuration 是响铃时长，单位是秒。30 秒比较适中，如果设成 0 或负数会报参数错误。snoozeTimes 是“稍后提醒”次数，timeInterval 是稍后提醒的间隔时间，单位是分钟。上面代码里“再睡一会”按钮，点了之后会间隔 10 分钟再响，最多 3 次。

daysOfWeek 数组是很多初学者的重灾区。HarmonyOS 里它是从周日开始计数的，1 代表周日，2 代表周一，以此类推，7 代表周六。这和国内“周一是一周开始”的直觉正好相反，非常容易配错。我之前就见过有人写 [1,2,3,4,5] 想做周一到周五，结果变成了周日到周四。

wantAgent 的作用是让用户点击提醒通知后，能拉起应用。如果你不需要点击跳转，这个字段可以不传，但用户体验会差一截。实际项目中，我建议跳过 setWantAgent 打开 App 还能顺带做一个深链跳转，直接定位到提醒详情页。

3.3 单次日历提醒与倒计时提醒

日历提醒适合“某一天某个时刻执行一次”的场景，比如“明天下午 4 点预约取快递”。

typescript复制import reminderAgentManager from '@ohos.reminderAgentManager';

async function publishCalendarReminder() {
  const reminder: reminderAgentManager.ReminderRequestCalendar = {
    reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR,
    dateTime: {
      year: 2025,
      month: 6,
      day: 18,
      hour: 16,
      minute: 0,
      second: 0
    },
    title: '取快递',
    content: '记得去快递柜取包裹',
    ringDuration: 10
  };

  try {
    const reminderId = await reminderAgentManager.publishReminder(reminder);
    console.info('日历提醒已发布，ID = ' + reminderId);
  } catch (err) {
    console.error('日历提醒发布失败：' + JSON.stringify(err));
  }
}

注意 dateTime 里 month 是从 1 开始的 1 到 12，不是从 0 开始，这点和 Date 对象的月份逻辑不一样。

倒计时提醒则更像一个“定时器”：

typescript复制async function publishTimerReminder(seconds: number) {
  const timer: reminderAgentManager.ReminderRequestTimer = {
    reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
    triggerTimeInSeconds: seconds,
    title: '倒计时结束',
    content: '时间到了，休息一下吧',
    ringDuration: 15
  };

  const reminderId = await reminderAgentManager.publishReminder(timer);
  console.info('倒计时提醒已发布，ID = ' + reminderId);
}

这里 triggerTimeInSeconds 是从当前时刻起算，比如传 60，就是 60 秒后提醒。注意它不像闹钟那样需要 hour/minute，也不要同时传多个时间字段，否则可能报参数校验错误。

3.4 查询与取消提醒

提醒一旦发布，就归系统管了。但用户在设置页可能想关掉这个提醒，或者你已经不需要这个提醒了，这时候就要通过提醒 ID 取消它。

发布时会返回一个 reminderId，我们要把它存下来。我习惯用 Preferences 持久化，存成 Map<业务Key, reminderId> 的形式。取消时调用：

typescript复制import reminderAgentManager from '@ohos.reminderAgentManager';

async function cancelReminder(reminderId: number) {
  try {
    await reminderAgentManager.cancelReminder(reminderId);
    console.info('提醒已取消：' + reminderId);
  } catch (err) {
    console.error('取消提醒失败：' + JSON.stringify(err));
  }
}

如果你忘了存 ID，或者 App 里的 ID 丢失了，可以通过 getValidReminders 把所有当前有效的提醒拉出来看看：

typescript复制async function getAllReminders() {
  const reminders = await reminderAgentManager.getValidReminders();
  reminders.forEach((item) => {
    console.info('当前有效提醒 ID：' + item.reminderId + '，标题：' + item.title);
  });
}

这个接口在需要做“提醒列表管理”的时候很关键。比如用户在同一页面添加了 5 个提醒，重启 App 后想查看哪些仍然有效，通过它就能恢复展示。

3.5 用延迟任务补充后台数据准备

有些提醒触发前需要准备数据。比如每天早上 8 点提醒用户“今日股市开盘了”，但 8 点的数据最好在 7 点 50 就开始拉取，避免提醒弹出来瞬间还转圈加载。

这种任务不需要精确到秒，可以用 WorkScheduler。它是系统级的延迟调度，会在合适的时机统一批量执行任务，对性能和功耗更友好。

简单示例：

typescript复制import workScheduler from '@ohos.workScheduler';

const workInfo = {
  workId: 1001,
  bundleName: 'com.example.reminderdemo',
  abilityName: 'PreloadWorkAbility',
  isPersisted: true,
  networkType: workScheduler.NetworkType.NETWORK_TYPE_WIFI,
  repeatCycleTime: 24 * 60 * 60 * 1000,
  repeatCount: 365
};

workScheduler.startWork(workInfo).then(() => {
  console.info('延迟任务已启动');
}).catch((err) => {
  console.error('启动延迟任务失败：' + JSON.stringify(err));
});

要注意两点。第一，repeatCycleTime 单位是毫秒，最小周期我记得是 20 分钟，想做到每 5 分钟执行一次是不现实的。第二，WorkScheduler 不适合做“准点提醒”，因为系统可能为了省电把任务延后到某个“合适时机”再执行。提醒的准点性要求，必须依赖 ReminderAgentManager，两者互补。

3.6 提醒通知样式与点击行为

提醒发布后，弹出来的通知在锁屏界面、通知中心、横幅里的表现，由系统根据应用的通知渠道和系统设置决定。开发者能控制的是标题、内容、动作按钮和点击跳转行为。

actionButton 是贴心的设计，尤其闹钟场景。系统支持两种按钮类型：

• ACTION_BUTTON_TYPE_CLOSE：关闭提醒。
• ACTION_BUTTON_TYPE_SNOOZE：稍后提醒，点击后按照 snoozeTimes 和 timeInterval 设置的次数和时间间隔再次提醒。

如果你想要“贪睡”功能，一定要用系统提供的 SNOOZE 类型按钮，而不是自己在应用里弹按钮。自己计数的方式在应用退到后台后就不可靠了。

点击整条通知跳转，用 WantAgent 实现。跳转目标可以是应用主页面，也可以带参数直接定位详情页。比如构造 wants 时给 want 添加 parameters：

typescript复制const wantAgentInfo = {
  wants: [
    {
      bundleName: 'com.example.reminderdemo',
      abilityName: 'EntryAbility',
      parameters: {
        reminderId: 10086
      }
    }
  ],
  operationType: wantAgent.OperationType.START_ABILITY,
  requestCode: 0,
  wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};

然后在应用入口 onCreate 或页面 onNewWant 里读取 parameters.reminderId，就能精准跳转到详情页。这个技巧在做待办列表、日程管理时很实用。

4. 常见问题与排查技巧实录

4.1 高频问题速查表

我把团队和社区里反馈比较多的问题整理成了表格，方便你遇到时快速对照。

4.2 提醒 ID 的持久化与重启恢复

提醒发布后，如果应用被用户手动杀掉，提醒本身不会跟随应用一起消失，因为它是系统托管的。但有一个问题：应用再次启动时，你手里没有这个提醒的 ID，就没法对它做取消或修改操作。

我的做法是发布成功后立刻把 ID 存到 Preferences 里，同时存一个业务标记，比如“早会提醒”或者“取快递提醒”。这样用户关掉一个提醒时，可以直接根据标记查 ID 并取消。

如果本地数据也没了，就调 getValidReminders 把系统里还活着的提醒遍历一遍，再通过 title 或 content 反向匹配恢复。这套逻辑在提醒管理页里几乎是必备的。

4.3 提醒不响的排查流程

如果用户反馈“提醒不响”，不要只盯着代码。我建议按这个顺序排查：

第一，先确认权限。在系统设置里看应用通知开关是否打开。第二，确认提醒是否真的发布成功，打日志看 reminderId。第三，确认时间参数是否正确。尤其时区和系统时间，如果用户手动改变了系统时间，已发布的提醒触发时间也会跟着变。

第四，确认是否重复取消过。有些操作逻辑里先取消后发布，如果取消的 ID 写死，可能把刚发布的新提醒也取消了。第五，确认是不是测试方式的问题。倒计时测试用 60 秒没问题，但闹钟测试建议把时间设置到 2 分钟后，而不是你看表的时候已经过了 1 分 59 秒。

4.4 几个容易忽略的细节

• 提醒标题最长不要超过系统限制，过长会被截断，影响观感。
• daysOfWeek 不要和 hour/minute 混着不传。闹钟必须有时分，日历必须有完整的日期时间。
• 创建提醒后，系统可能不会立即展示“剩余时间”，尤其在 API 9 上，不要尝试在应用侧倒计时等待提醒，那会失真。
• 在元服务里做提醒要更谨慎，部分接口能力受限，商业项目建议先在 App 模型下验证。

5. 回顾一下我踩过的坑

最后说两个我印象最深的坑吧。

第一个是 daysOfWeek 的坑。我当时按照直觉写了周一到周五，也就是 [1,2,3,4,5]，结果发布的提醒到了周日下午开始响，用户在周末被闹醒，直接给了个一星差评。后来仔细翻文档才知道鸿蒙里 1 是周日。建议你拿到任何 SDK 的时间字段，都先打印出来对照日历真实验证一遍，不要想当然。

第二个是想偷懒用“常驻通知 + 后台长时任务”来实现定时提醒。确实，申请到长时任务权限后，应用能在后台存活一段时间，自己在应用里定时触发通知，看起来也能实现类似效果。但长时任务需要显示常驻通知，还有严格的时间配额限制，用户在系统里可以看到你“一直在后台运行”，很容易被手动杀掉。系统级的 ReminderAgentManager 才是做定时提醒的正确姿势，也最省电。

鸿蒙的后台任务体系，本质上是在“功能可用”和“系统资源可控”之间找平衡。定时提醒这种需求，能托管给系统就托管给系统，不要把用户的手机当成你自己的服务器来跑任务。把提醒发布出去，把 ID 存好，把取消逻辑做对，剩下的交给系统，它能做得比你好得多。