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