1# 代理提醒 2 3## 概述 4 5### 功能介绍 6 7应用退到后台或进程终止后，仍然有一些提醒用户的定时类任务，例如购物类应用抢购提醒等，为满足此类功能场景，系统提供了代理提醒（reminderAgentManager）的能力。当应用退至后台或进程终止后，系统会代理应用做相应的提醒。当前支持的提醒类型包括：倒计时、日历和闹钟。 8 9- 倒计时类：基于倒计时的提醒功能。 10 11- 日历类：基于日历的提醒功能。 12 13- 闹钟类：基于时钟的提醒功能。 14 15### 约束与限制 16 17- **个数限制**：一个三方应用支持最多30个有效提醒（有效即发布成功），一个系统应用支持最多10000个有效提醒，整个系统最多支持12000个有效提醒。 18 19- **跳转限制**：点击提醒通知后跳转的应用必须是申请代理提醒的本应用。 20 21 22## 接口说明 23 24**表1** 主要接口 25 26以下是代理提醒的相关接口，下表均以Promise形式为例，更多接口及使用方式请见后台代理提醒文档。 27| 接口名 | 描述 | 28| -------- | -------- | 29| publishReminder(reminderReq: ReminderRequest): Promise<number> | 发布一个定时提醒类通知 | 30| cancelReminder(reminderId: number): Promise<void> | 取消一个指定的提醒类通知 | 31| getValidReminders(): Promise<Array<ReminderRequest>> | 获取当前应用设置的所有有效的提醒 | 32| cancelAllReminders(): Promise<void> | 取消当前应用设置的所有提醒 | 33| addNotificationSlot(slot: NotificationSlot): Promise<void> | 注册一个提醒类需要使用的通知通道（NotificationSlot） | 34| removeNotificationSlot(slotType: notification.SlotType): Promise<void> | 删除指定的通知通道（NotificationSlot） | 35 36 37## 开发步骤 38 391. 申请ohos.permission.PUBLISH_AGENT_REMINDER权限，配置方式请参阅[配置文件权限声明](../security/accesstoken-guidelines.md#配置文件权限声明)。 40 412. [使能通知开关](../notification/notification-enable.md)。获得用户授权后，才能使用代理提醒功能。 42 433. 导入模块。 44 45 ```js 46 import reminderAgentManager from '@ohos.reminderAgentManager'; 47 import notificationManager from '@ohos.notificationManager'; 48 ``` 49 504. 定义目标提醒代理。开发者根据实际需要，选择定义如下类型的提醒。 51 52 - 定义倒计时实例。 53 54 ```js 55 let targetReminderAgent: reminderAgentManager.ReminderRequestTimer = { 56 reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, // 提醒类型为倒计时类型 57 triggerTimeInSeconds: 10, 58 actionButton: [ // 设置弹出的提醒通知信息上显示的按钮类型和标题 59 { 60 title: 'close', 61 type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE 62 } 63 ], 64 wantAgent: { // 点击提醒通知后跳转的目标UIAbility信息 65 pkgName: 'com.example.myapplication', 66 abilityName: 'EntryAbility' 67 }, 68 maxScreenWantAgent: { // 全屏显示提醒到达时自动拉起的目标UIAbility信息 69 pkgName: 'com.example.myapplication', 70 abilityName: 'EntryAbility' 71 }, 72 title: 'this is title', // 指明提醒标题 73 content: 'this is content', // 指明提醒内容 74 expiredContent: 'this reminder has expired', // 指明提醒过期后需要显示的内容 75 notificationId: 100, // 指明提醒使用的通知的ID号，相同ID号的提醒会覆盖 76 slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // 指明提醒的Slot类型 77 } 78 ``` 79 80 - 定义日历实例。 81 82 ```js 83 let targetReminderAgent: reminderAgentManager.ReminderRequestCalendar = { 84 reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, // 提醒类型为日历类型 85 dateTime: { // 指明提醒的目标时间 86 year: 2023, 87 month: 1, 88 day: 1, 89 hour: 11, 90 minute: 14, 91 second: 30 92 }, 93 repeatMonths: [1], // 指明重复提醒的月份 94 repeatDays: [1], // 指明重复提醒的日期 95 actionButton: [ // 设置弹出的提醒通知信息上显示的按钮类型和标题 96 { 97 title: 'close', 98 type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE 99 }, 100 { 101 title: 'snooze', 102 type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE 103 }, 104 ], 105 wantAgent: { // 点击提醒通知后跳转的目标UIAbility信息 106 pkgName: 'com.example.myapplication', 107 abilityName: 'EntryAbility' 108 }, 109 maxScreenWantAgent: { // 全屏显示提醒到达时自动拉起的目标UIAbility信息 110 pkgName: 'com.example.myapplication', 111 abilityName: 'EntryAbility' 112 }, 113 ringDuration: 5, // 指明响铃时长（单位：秒） 114 snoozeTimes: 2, // 指明延迟提醒次数 115 timeInterval: 5, // 执行延迟提醒间隔（单位：秒） 116 title: 'this is title', // 指明提醒标题 117 content: 'this is content', // 指明提醒内容 118 expiredContent: 'this reminder has expired', // 指明提醒过期后需要显示的内容 119 snoozeContent: 'remind later', // 指明延迟提醒时需要显示的内容 120 notificationId: 100, // 指明提醒使用的通知的ID号，相同ID号的提醒会覆盖 121 slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // 指明提醒的Slot类型 122 } 123 ``` 124 125 - 定义闹钟实例。 126 127 ```js 128 let targetReminderAgent: reminderAgentManager.ReminderRequestAlarm = { 129 reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, // 提醒类型为闹钟类型 130 hour: 23, // 指明提醒的目标时刻 131 minute: 9, // 指明提醒的目标分钟 132 daysOfWeek: [2], // 指明每周哪几天需要重复提醒 133 actionButton: [ // 设置弹出的提醒通知信息上显示的按钮类型和标题 134 { 135 title: 'close', 136 type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE 137 }, 138 { 139 title: 'snooze', 140 type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE 141 }, 142 ], 143 wantAgent: { // 点击提醒通知后跳转的目标UIAbility信息 144 pkgName: 'com.example.myapplication', 145 abilityName: 'EntryAbility' 146 }, 147 maxScreenWantAgent: { // 全屏显示提醒到达时自动拉起的目标UIAbility信息 148 pkgName: 'com.example.myapplication', 149 abilityName: 'EntryAbility' 150 }, 151 ringDuration: 5, // 指明响铃时长（单位：秒） 152 snoozeTimes: 2, // 指明延迟提醒次数 153 timeInterval: 5, // 执行延迟提醒间隔（单位：秒） 154 title: 'this is title', // 指明提醒标题 155 content: 'this is content', // 指明提醒内容 156 expiredContent: 'this reminder has expired', // 指明提醒过期后需要显示的内容 157 snoozeContent: 'remind later', // 指明延迟提醒时需要显示的内容 158 notificationId: 99, // 指明提醒使用的通知的ID号，相同ID号的提醒会覆盖 159 slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // 指明提醒的Slot类型 160 } 161 ``` 162 1635. 发布相应的提醒代理。代理发布后，应用即可使用后台代理提醒功能。 164 165 ```js 166 try { 167 reminderAgentManager.publishReminder(targetReminderAgent).then(res => { 168 console.info('Succeeded in publishing reminder. '); 169 let reminderId: number = res; // 发布的提醒ID 170 }).catch(err => { 171 console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`); 172 }) 173 } catch (err) { 174 console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`); 175 } 176 ``` 177 1786. 根据需要删除提醒任务。 179 180 ```js 181 try { 182 // reminderId的值从发布提醒代理成功之后的回调中获得 183 reminderAgentManager.cancelReminder(reminderId).then(() => { 184 console.log('Succeeded in canceling reminder.'); 185 }).catch(err => { 186 console.error(`Failed to cancel reminder. Code: ${err.code}, message: ${err.message}`); 187 }); 188 } catch (err) { 189 console.error(`Failed to cancel reminder. Code: ${err.code}, message: ${err.message}`); 190 } 191 ``` 192 193## 相关实例 194 195基于代理提醒，有以下相关实例可供参考： 196 197- [后台代理提醒（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-3.2-Release/code/BasicFeature/TaskManagement/ReminderAgentManager) 198 199- [翻页闹钟（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-3.2-Release/code/Solutions/Tools/FlipClock) 200 201- [闹钟（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/CommonEventAndNotification/AlarmClock)