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