网站导航
> 技术文档 > 鸿蒙API14开发【@ohos.reminderAgentManager (后台代理提醒)】后台任务开发_鸿蒙应用开发中提醒任务的全部删除

鸿蒙API14开发【@ohos.reminderAgentManager (后台代理提醒)】后台任务开发_鸿蒙应用开发中提醒任务的全部删除

网友: 技术文档 2025-08-15 17:09:15

本模块提供后台代理提醒的能力，即当应用被冻结或应用退出时，计时和提醒的功能将被系统服务代理。开发者可以调用本模块接口创建定时提醒，提醒类型支持倒计时、日历、闹钟三种。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { reminderAgentManager } from \'@kit.BackgroundTasksKit\';ts

reminderAgentManager.publishReminder

publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback): void

发布后台代理提醒。使用callback异步回调。

说明：

该接口需要申请通知弹窗权限[NotificationManager.requestEnableNotification]后调用。

需要权限： ohos.permission.PUBLISH_AGENT_REMINDER

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 reminderReq [ReminderRequest] 是 需要发布的代理提醒实例。 callback AsyncCallback 是 回调函数，返回当前发布提醒的id。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700001 Notification is not enabled. 1700002 The number of reminders exceeds the limit.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';let timer: reminderAgentManager.ReminderRequestTimer = { reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, triggerTimeInSeconds: 10}reminderAgentManager.publishReminder(timer, (err: BusinessError, reminderId: number) => { if (err.code) { console.error(\"callback err code:\" + err.code + \" message:\" + err.message); } else { console.log(\"callback, reminderId = \" + reminderId); }});ts

reminderAgentManager.publishReminder

publishReminder(reminderReq: ReminderRequest): Promise

发布后台代理提醒。使用promise异步回调。

说明：

该接口需要申请通知弹窗权限[NotificationManager.requestEnableNotification]后调用。

需要权限： ohos.permission.PUBLISH_AGENT_REMINDER

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 reminderReq [ReminderRequest] 是 需要发布的代理提醒实例。

返回值：

类型 说明 Promise Promise对象，返回当前发布提醒的id。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700001 Notification is not enabled. 1700002 The number of reminders exceeds the limit.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';let timer: reminderAgentManager.ReminderRequestTimer = { reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, triggerTimeInSeconds: 10}reminderAgentManager.publishReminder(timer).then((reminderId: number) => { console.log(\"promise, reminderId = \" + reminderId);}).catch((err: BusinessError) => { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

reminderAgentManager.cancelReminder

cancelReminder(reminderId: number, callback: AsyncCallback): void

取消指定id的代理提醒。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 reminderId number 是 需要取消的代理提醒的id。 callback AsyncCallback 是 回调函数，取消代理提醒成功，err为undefined，否则返回err信息。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700003 The reminder does not exist. 1700004 The bundle name does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';let reminderId: number = 1;reminderAgentManager.cancelReminder(reminderId, (err: BusinessError) => { if (err.code) { console.error(\"callback err code:\" + err.code + \" message:\" + err.message); } else { console.log(\"cancelReminder callback\"); }});ts

reminderAgentManager.cancelReminder

cancelReminder(reminderId: number): Promise

取消指定id的代理提醒。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 reminderId number 是 需要取消的代理提醒的id。

返回值：

类型 说明 Promise 无返回结果的Promise对象。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700003 The reminder does not exist. 1700004 The bundle name does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';let reminderId: number = 1;reminderAgentManager.cancelReminder(reminderId).then(() => { console.log(\"cancelReminder promise\");}).catch((err: BusinessError) => { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

reminderAgentManager.getValidReminders

getValidReminders(callback: AsyncCallback): void

获取当前应用设置的所有[有效（未过期）的代理提醒]。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 callback AsyncCallback<Array> 是 回调函数，返回当前应用设置的所有有效（未过期）的代理提醒。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700004 The bundle name does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';reminderAgentManager.getValidReminders((err: BusinessError, reminders: Array) => { if (err.code) { console.error(\"callback err code:\" + err.code + \" message:\" + err.message); } else { console.log(\"callback, getValidReminders length = \" + reminders.length); for (let i = 0; i < reminders.length; i++) { console.log(\"getValidReminders = \" + reminders[i]); console.log(\"getValidReminders, reminderType = \" + reminders[i].reminderType); const actionButton = reminders[i].actionButton || []; for (let j = 0; j < actionButton.length; j++) { console.log(\"getValidReminders, actionButton.title = \" + actionButton[j]?.title); console.log(\"getValidReminders, actionButton.type = \" + actionButton[j]?.type); } console.log(\"getValidReminders, wantAgent.pkgName = \" + reminders[i].wantAgent?.pkgName); console.log(\"getValidReminders, wantAgent.abilityName = \" + reminders[i].wantAgent?.abilityName); console.log(\"getValidReminders, ringDuration = \" + reminders[i].ringDuration); console.log(\"getValidReminders, snoozeTimes = \" + reminders[i].snoozeTimes); console.log(\"getValidReminders, timeInterval = \" + reminders[i].timeInterval); console.log(\"getValidReminders, title = \" + reminders[i].title); console.log(\"getValidReminders, content = \" + reminders[i].content); console.log(\"getValidReminders, expiredContent = \" + reminders[i].expiredContent); console.log(\"getValidReminders, snoozeContent = \" + reminders[i].snoozeContent); console.log(\"getValidReminders, notificationId = \" + reminders[i].notificationId); console.log(\"getValidReminders, slotType = \" + reminders[i].slotType); } }});ts

reminderAgentManager.getValidReminders

getValidReminders(): Promise

获取当前应用设置的所有[有效（未过期）的代理提醒]。使用promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

返回值：

类型 说明 Promise<Array> Promise对象，返回当前应用设置的所有有效（未过期）的代理提醒。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700004 The bundle name does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';reminderAgentManager.getValidReminders().then((reminders: Array) => { console.log(\"promise, getValidReminders length = \" + reminders.length); for (let i = 0; i < reminders.length; i++) { console.log(\"getValidReminders = \" + reminders[i]); console.log(\"getValidReminders, reminderType = \" + reminders[i].reminderType); const actionButton = reminders[i].actionButton || []; for (let j = 0; j  { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);}); ts

reminderAgentManager.cancelAllReminders

cancelAllReminders(callback: AsyncCallback): void

取消当前应用设置的所有代理提醒。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 callback AsyncCallback 是 回调函数，取消代理提醒成功，err为undefined，否则为错误对象。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700004 The bundle name does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';reminderAgentManager.cancelAllReminders((err: BusinessError) =>{ if (err.code) { console.error(\"callback err code:\" + err.code + \" message:\" + err.message); } else { console.log(\"cancelAllReminders callback\") }});ts

reminderAgentManager.cancelAllReminders

cancelAllReminders(): Promise

取消当前应用设置的所有代理提醒。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

返回值：

类型 说明 Promise 无返回结果的Promise对象。 错误码ID 错误信息 401 If the input parameter is not valid parameter. 1700004 The bundle name does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';reminderAgentManager.cancelAllReminders().then(() => { console.log(\"cancelAllReminders promise\")}).catch((err: BusinessError) => { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

reminderAgentManager.addNotificationSlot

addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback): void

添加通知槽。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 slot [NotificationSlot] 是 notificationManager.slot实例，仅支持设置其notificationType属性。 callback AsyncCallback 是 回调函数，添加NotificationSlot成功时，err为undefined，否则err为错误对象。 错误码ID 错误信息 401 If the input parameter is not valid parameter.

示例：

import { notificationManager } from \'@kit.NotificationKit\';import { BusinessError } from \'@kit.BasicServicesKit\';let mySlot: notificationManager.NotificationSlot = { notificationType: notificationManager.SlotType.SOCIAL_COMMUNICATION}reminderAgentManager.addNotificationSlot(mySlot, (err: BusinessError) => { if (err.code) { console.error(\"callback err code:\" + err.code + \" message:\" + err.message); } else { console.log(\"addNotificationSlot callback\"); }});ts

reminderAgentManager.addNotificationSlot

addNotificationSlot(slot: NotificationSlot): Promise

添加通知槽。使用promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 slot [NotificationSlot] 是 notificationManager.slot实例，仅支持设置其notificationType属性。

返回值：

类型 说明 Promise 无返回结果的Promise对象。 错误码ID 错误信息 401 If the input parameter is not valid parameter.

示例：

import { notificationManager } from \'@kit.NotificationKit\';import { BusinessError } from \'@kit.BasicServicesKit\';let mySlot: notificationManager.NotificationSlot = { notificationType: notificationManager.SlotType.SOCIAL_COMMUNICATION}reminderAgentManager.addNotificationSlot(mySlot).then(() => { console.log(\"addNotificationSlot promise\");}).catch((err: BusinessError) => { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

reminderAgentManager.removeNotificationSlot

removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback): void

删除目标通知槽，使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 slotType [notification.SlotType] 是 通知渠道类型。 callback AsyncCallback 是 回调函数，当删除成功时，err为undefined，否则为错误对象。 错误码ID 错误信息 401 If the input parameter is not valid parameter.

示例：

import { notificationManager } from \'@kit.NotificationKit\';import { BusinessError } from \'@kit.BasicServicesKit\';reminderAgentManager.removeNotificationSlot(notificationManager.SlotType.CONTENT_INFORMATION, (err: BusinessError) => { if (err.code) { console.error(\"callback err code:\" + err.code + \" message:\" + err.message); } else { console.log(\"removeNotificationSlot callback\"); }});ts

reminderAgentManager.removeNotificationSlot

removeNotificationSlot(slotType: notification.SlotType): Promise

删除目标通知槽，使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 slotType [notification.SlotType] 是 通知渠道类型。

返回值：

类型 说明 Promise 无返回结果的Promise对象。 错误码ID 错误信息 401 If the input parameter is not valid parameter.

示例：

import { notificationManager } from \'@kit.NotificationKit\';import { BusinessError } from \'@kit.BasicServicesKit\';reminderAgentManager.removeNotificationSlot(notificationManager.SlotType.CONTENT_INFORMATION).then(() => { console.log(\"removeNotificationSlot promise\");}).catch((err: BusinessError) => { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

reminderAgentManager.getAllValidReminders12+

getAllValidReminders(): Promise

获取当前应用设置的所有[有效（未过期）的代理提醒]。使用promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

返回值：

类型 说明 Promise<Array> Promise对象，返回当前应用设置的所有有效（未过期）的代理提醒。 错误码ID 错误信息 201 Permission denied.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';reminderAgentManager.getAllValidReminders().then((reminders: Array) => { console.log(\"promise, getAllValidReminders length = \" + reminders.length); for (let i = 0; i < reminders.length; i++) { console.log(\"getAllValidReminders, reminderId = \" + reminders[i].reminderId); console.log(\"getAllValidReminders, reminderType = \" + reminders[i].reminderReq.reminderType); const actionButton = reminders[i].reminderReq.actionButton || []; for (let j = 0; j  { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);}); ts

reminderAgentManager.addExcludeDate12+

addExcludeDate(reminderId: number, date: Date): Promise

为指定id的周期性的日历提醒，添加不提醒日期（如每天提醒的日历，设置周二不提醒）。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 reminderId number 是 需要添加不提醒日期的周期性日历id。 date Date 是 不提醒的日期。

返回值：

类型 说明 Promise 无返回结果的Promise对象。 错误码ID 错误信息 201 Permission denied. 401 If the input parameter is not valid parameter. 1700003 The reminder does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';let reminderId: number = 1;let date = new Date();reminderAgentManager.addExcludeDate(reminderId, date).then(() => { console.log(\"addExcludeDate promise\");}).catch((err: BusinessError) => { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

reminderAgentManager.deleteExcludeDates12+

deleteExcludeDates(reminderId: number): Promise

为指定id的周期性的日历提醒，删除设置的所有不提醒日期。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 reminderId number 是 需要删除不提醒日期的周期性日历id。

返回值：

类型 说明 Promise 无返回结果的Promise对象。 错误码ID 错误信息 201 Permission denied. 1700003 The reminder does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';let reminderId: number = 1;reminderAgentManager.deleteExcludeDates(reminderId).then(() => { console.log(\"deleteExcludeDates promise\");}).catch((err: BusinessError) => { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

reminderAgentManager.getExcludeDates12+

getExcludeDates(reminderId: number): Promise

为指定id的周期性的日历提醒，查询设置的所有不提醒日期。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明 reminderId number 是 需要查询不提醒日期的周期性日历id。

返回值：

类型 说明 Promise Promise对象。返回特定日历设置的所有不提醒日期。 错误码ID 错误信息 201 Permission denied. 1700003 The reminder does not exist.

示例：

import { BusinessError } from \'@kit.BasicServicesKit\';let reminderId: number = 1;reminderAgentManager.getExcludeDates(reminderId).then((dates) => { console.log(\"getExcludeDates promise length: \" + dates.length); for (let i = 0; i  { console.error(\"promise err code:\" + err.code + \" message:\" + err.message);});ts

ActionButtonType

提醒上的按钮的类型。

系统能力：SystemCapability.Notification.ReminderAgent

名称 值 说明 ACTION_BUTTON_TYPE_CLOSE 0 表示关闭提醒的按钮。 ACTION_BUTTON_TYPE_SNOOZE 1 表示延时提醒的按钮，提醒次数和间隔通过 [ReminderRequest]中snoozeTimes和timeInterval设置。

ReminderType

提醒的类型。

系统能力：SystemCapability.Notification.ReminderAgent

名称 值 说明 REMINDER_TYPE_TIMER 0 表示提醒类型：倒计时。 REMINDER_TYPE_CALENDAR 1 表示提醒类型：日历。 REMINDER_TYPE_ALARM 2 表示提醒类型：闹钟。

ActionButton

弹出的提醒中按钮的类型和标题。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 title string 是 按钮显示的标题。 titleResource11+ string 否 标题的资源ID，用于切换系统语言后读取对应标题信息。 type [ActionButtonType] 是 按钮的类型。

WantAgent

跳转目标的ability信息。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 pkgName string 是 指明跳转目标的包名。 abilityName string 是 指明跳转目标的ability名称。 parameters12+ Record 否 需要传递到目标的参数。 uri12+ string 否 指明跳转目标的uri信息。

MaxScreenWantAgent

通知中心弹出提醒时，全屏显示自动拉起目标的ability信息。该接口为预留接口，暂不支持使用。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 pkgName string 是 指明提醒到达时自动拉起的目标包名（如果设备在使用中，则只弹出通知横幅框）。 abilityName string 是 指明提醒到达时自动拉起的目标ability名（如果设备在使用中，则只弹出通知横幅框）。

ReminderRequest

代理提醒对象，用于设置提醒类型、响铃时长等具体信息。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 reminderType [ReminderType] 是 指明代理提醒类型。 actionButton [[ActionButton?, ActionButton?, ActionButton?]] 否 弹出的提醒通知中显示的按钮。 -普通应用：最多支持两个按钮。 -系统应用：API9最多支持两个按钮，在API10开始最多支持三个按钮。 wantAgent [WantAgent] 否 点击通知后需要跳转的目标ability信息。 maxScreenWantAgent [MaxScreenWantAgent] 否 提醒到达时，全屏显示自动拉起目标的ability信息。如果设备正在使用中，则弹出一个通知横幅框。 说明：该接口为预留接口，暂不支持使用。 ringDuration number 否 指明响铃时长（单位：秒），默认1秒。 snoozeTimes number 否 指明延时提醒次数，默认0次(不适用于倒计时提醒类型)。 timeInterval number 否 执行延时提醒间隔（单位：秒），最少5分钟(不适用于倒计时提醒类型)。 title string 否 指明提醒标题。 content string 否 指明提醒内容。 expiredContent string 否 指明提醒过期后需要显示的内容。 snoozeContent string 否 指明延时提醒时需要显示的内容(不适用于倒计时提醒类型)。 notificationId number 否 指明提醒使用的通知的id号，需开发者传入，相同id号的提醒会覆盖。 groupId11+ string 否 指明提醒使用相同的组id。相同组id中，一个提醒被点击不在提醒后，组内其他提醒也会被取消。 slotType [notification.SlotType] 否 指明提醒的通道渠道类型。 tapDismissed10+ boolean 否 通知是否自动清除。 autoDeletedTime10+ number 否 自动清除的时间。 snoozeSlotType11+ [notification.SlotType] 否 指明延时提醒的通道渠道类型(不适用于倒计时提醒类型)。 customRingUri11+ string 否 指明自定义提示音的uri，提示音文件必须放在resources/rawfile目录下，支持m4a、aac、mp3、ogg、wav、flac、amr等格式。

ReminderRequestCalendar

ReminderRequestCalendar extends ReminderRequest

日历实例对象，用于设置提醒的时间。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 dateTime [LocalDateTime] 是 指明提醒的目标时间。 repeatMonths Array 否 指明重复提醒的月份。 repeatDays Array 否 指明重复提醒的日期。 daysOfWeek11+ Array 否 指明每周哪几天需要重复提醒。范围为周一到周日，对应数字为1到7。 endDateTime12+ [LocalDateTime] 否 指明提醒的结束时间。

ReminderRequestAlarm

ReminderRequestAlarm extends ReminderRequest

闹钟实例对象，用于设置提醒的时间。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 hour number 是 指明提醒的目标时刻。 minute number 是 指明提醒的目标分钟。 daysOfWeek Array 否 指明每周哪几天需要重复提醒。范围为周一到周日，对应数字为1到7。

ReminderRequestTimer

ReminderRequestTimer extends ReminderRequest

倒计时实例对象，用于设置提醒的时间。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 triggerTimeInSeconds number 是 指明倒计时的秒数。

LocalDateTime

用于日历类提醒设置时指定时间信息。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明 year number 是 年 month number 是 月，取值范围是[1, 12]。 day number 是 日，取值范围是[1, 31]。 hour number 是 时，取值范围是[0, 23]。 minute number 是 分，取值范围是[0, 59]。 second number 否 秒，取值范围是[0, 59]。

ReminderInfo12+

代理提醒信息，包含 ReminderRequest 和 ReminderId。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 只读 可选 说明 reminderId number 否 否 发布提醒后返回的id。 reminderReq [ReminderRequest] 否 否 代理提醒对象。

加入鸿蒙学习阵营！

除了本文，面费领《HarmonyOS应用开发》+《鸿蒙openharmony系统开发大全》 等入门进阶资料！关注我的CSDN主页，持续获取：
在这里插入图片描述

最新鸿蒙技术文章
独家项目实战教程
免费直播/训练营信息
👉 下方资源区已为你备好！

网络标签：

相关问题