1# @ohos.reminderAgent (Reminder Agent) 2 3The **reminderAgent** module provides APIs for publishing scheduled reminders through the reminder agent. 4 5You can use the APIs to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background when your application is frozen or exits. 6 7> **NOTE** 8> 9> This module is deprecated since API version 9. You are advised to use [@ohos.reminderAgentManager](js-apis-reminderAgentManager.md) instead. 10> 11> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 12 13 14## Modules to Import 15 16```ts 17import reminderAgent from'@ohos.reminderAgent'; 18``` 19 20 21## reminderAgent.publishReminder 22 23```ts 24publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void 25``` 26 27Publishes a reminder through the reminder agent. This API uses an asynchronous callback to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8). 28 29**Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER 30 31**System capability**: SystemCapability.Notification.ReminderAgent 32 33**Parameters** 34 35 | Name| Type| Mandatory| Description| 36 | -------- | -------- | -------- | -------- | 37 | reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.| 38 | callback | AsyncCallback\<number\> | Yes| Callback used to return the published reminder's ID.| 39 40**Example** 41```ts 42 let timer = { 43 reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, 44 triggerTimeInSeconds: 10 45 } 46 47 reminderAgent.publishReminder(timer, (err, reminderId) => { 48 console.log("callback, reminderId = " + reminderId); 49 }); 50``` 51 52 53## reminderAgent.publishReminder 54 55```ts 56publishReminder(reminderReq: ReminderRequest): Promise<number> 57``` 58 59Publishes a reminder through the reminder agent. This API uses a promise to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8). 60 61**Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER 62 63**System capability**: SystemCapability.Notification.ReminderAgent 64 65**Parameters** 66 | Name| Type| Mandatory| Description| 67 | -------- | -------- | -------- | -------- | 68 | reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.| 69 70**Return value** 71 | Type| Description| 72 | -------- | -------- | 73 | Promise\<number\> | Promise used to return the published reminder's ID.| 74 75**Example** 76```ts 77 let timer = { 78 reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, 79 triggerTimeInSeconds: 10 80 } 81 82 reminderAgent.publishReminder(timer).then((reminderId) => { 83 console.log("promise, reminderId = " + reminderId); 84 }); 85``` 86 87 88## reminderAgent.cancelReminder 89 90```ts 91cancelReminder(reminderId: number, callback: AsyncCallback<void>): void 92``` 93 94Cancels the reminder with the specified ID. This API uses an asynchronous callback to return the cancellation result. 95 96**System capability**: SystemCapability.Notification.ReminderAgent 97 98**Parameters** 99 100| Name| Type| Mandatory| Description| 101| -------- | -------- | -------- | -------- | 102| reminderId | number | Yes| ID of the reminder to cancel. The value is obtained by calling [publishReminder](#reminderagentpublishreminder).| 103| callback | AsyncCallback\<void\> | Yes| Asynchronous callback used to return the result.| 104 105**Example** 106 107```ts 108reminderAgent.cancelReminder(1, (err, data) => { 109 console.log("cancelReminder callback"); 110}); 111``` 112 113 114## reminderAgent.cancelReminder 115 116```ts 117cancelReminder(reminderId: number): Promise<void> 118``` 119 120Cancels the reminder with the specified ID. This API uses a promise to return the cancellation result. 121 122**System capability**: SystemCapability.Notification.ReminderAgent 123 124**Parameters** 125 126| Name| Type| Mandatory| Description| 127| -------- | -------- | -------- | -------- | 128| reminderId | number | Yes| ID of the reminder to cancel. The value is obtained by calling [publishReminder](#reminderagentpublishreminder).| 129 130**Return value** 131 132| Type| Description| 133| -------- | -------- | 134| Promise\<void\> | Promise used to return the result.| 135 136**Example** 137 138```ts 139reminderAgent.cancelReminder(1).then(() => { 140 console.log("cancelReminder promise"); 141}); 142``` 143 144## reminderAgent.getValidReminders 145 146```ts 147getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void 148``` 149 150Obtains all valid (not yet expired) reminders set by the current application. This API uses an asynchronous callback to return the reminders. 151 152**System capability**: SystemCapability.Notification.ReminderAgent 153 154**Parameters** 155 156| Name| Type| Mandatory| Description| 157| -------- | -------- | -------- | -------- | 158| callback | AsyncCallback\<Array\<[ReminderRequest](#reminderrequest)\>\> | Yes| Asynchronous callback used to return an array of all valid reminders set by the current application.| 159 160**Example** 161 162```ts 163reminderAgent.getValidReminders((err, reminders) => { 164 console.log("callback, getValidReminders length = " + reminders.length); 165 for (let i = 0; i < reminders.length; i++) { 166 console.log("getValidReminders = " + reminders[i]); 167 console.log("getValidReminders, reminderType = " + reminders[i].reminderType); 168 for (let j = 0; j < reminders[i].actionButton.length; j++) { 169 console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title); 170 console.log("getValidReminders, actionButton.type = " + reminders[i].actionButton[j].type); 171 } 172 console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent.pkgName); 173 console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent.abilityName); 174 console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent.pkgName); 175 console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent.abilityName); 176 console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration); 177 console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes); 178 console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval); 179 console.log("getValidReminders, title = " + reminders[i].title); 180 console.log("getValidReminders, content = " + reminders[i].content); 181 console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent); 182 console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent); 183 console.log("getValidReminders, notificationId = " + reminders[i].notificationId); 184 console.log("getValidReminders, slotType = " + reminders[i].slotType); 185 } 186}) 187``` 188 189 190## reminderAgent.getValidReminders 191 192```ts 193getValidReminders(): Promise<Array<ReminderRequest>> 194``` 195 196Obtains all valid (not yet expired) reminders set by the current application. This API uses a promise to return the reminders. 197 198**System capability**: SystemCapability.Notification.ReminderAgent 199 200**Return value** 201 202| Type| Description| 203| -------- | -------- | 204| Promise\<Array\<[ReminderRequest](#reminderrequest)\>\> | Promise used to return an array of all valid reminders set by the current application.| 205 206**Example** 207 208```ts 209reminderAgent.getValidReminders().then((reminders) => { 210 console.log("promise, getValidReminders length = " + reminders.length); 211 for (let i = 0; i < reminders.length; i++) { 212 console.log("getValidReminders = " + reminders[i]); 213 console.log("getValidReminders, reminderType = " + reminders[i].reminderType); 214 for (let j = 0; j < reminders[i].actionButton.length; j++) { 215 console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title); 216 console.log("getValidReminders, actionButton.type = " + reminders[i].actionButton[j].type); 217 } 218 console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent.pkgName); 219 console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent.abilityName); 220 console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent.pkgName); 221 console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent.abilityName); 222 console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration); 223 console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes); 224 console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval); 225 console.log("getValidReminders, title = " + reminders[i].title); 226 console.log("getValidReminders, content = " + reminders[i].content); 227 console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent); 228 console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent); 229 console.log("getValidReminders, notificationId = " + reminders[i].notificationId); 230 console.log("getValidReminders, slotType = " + reminders[i].slotType); 231 } 232}) 233``` 234 235 236## reminderAgent.cancelAllReminders 237 238```ts 239cancelAllReminders(callback: AsyncCallback<void>): void 240``` 241 242Cancels all reminders set by the current application. This API uses an asynchronous callback to return the cancellation result. 243 244**System capability**: SystemCapability.Notification.ReminderAgent 245 246**Parameters** 247 248| Name| Type| Mandatory| Description| 249| -------- | -------- | -------- | -------- | 250| callback | AsyncCallback\<void\> | Yes| Asynchronous callback used to return the result.| 251 252**Example** 253 254```ts 255reminderAgent.cancelAllReminders((err, data) =>{ 256 console.log("cancelAllReminders callback") 257}) 258``` 259 260 261## reminderAgent.cancelAllReminders 262 263```ts 264cancelAllReminders(): Promise<void> 265``` 266 267Cancels all reminders set by the current application. This API uses a promise to return the cancellation result. 268 269**System capability**: SystemCapability.Notification.ReminderAgent 270 271**Return value** 272 273| Type| Description| 274| -------- | -------- | 275| Promise\<void\> | Promise used to return the result.| 276 277**Example** 278 279```ts 280reminderAgent.cancelAllReminders().then(() => { 281 console.log("cancelAllReminders promise") 282}) 283``` 284 285## reminderAgent.addNotificationSlot 286 287```ts 288addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void 289``` 290 291Adds a notification slot. This API uses an asynchronous callback to return the result. 292 293**System capability**: SystemCapability.Notification.ReminderAgent 294 295**Parameters** 296 297| Name| Type| Mandatory| Description| 298| -------- | -------- | -------- | -------- | 299| slot | [NotificationSlot](js-apis-notification.md#notificationslot) | Yes| Notification slot, whose type can be set.| 300| callback | AsyncCallback\<void\> | Yes| Asynchronous callback used to return the result.| 301 302**Example** 303 304```ts 305import notification from '@ohos.notification' 306 307let mySlot = { 308 type: notification.SlotType.SOCIAL_COMMUNICATION 309} 310reminderAgent.addNotificationSlot(mySlot, (err, data) => { 311 console.log("addNotificationSlot callback"); 312}); 313``` 314 315 316## reminderAgent.addNotificationSlot 317 318```ts 319addNotificationSlot(slot: NotificationSlot): Promise<void> 320``` 321 322Adds a notification slot. This API uses a promise to return the result. 323 324**System capability**: SystemCapability.Notification.ReminderAgent 325 326**Parameters** 327 328| Name| Type| Mandatory| Description| 329| -------- | -------- | -------- | -------- | 330| slot | [NotificationSlot](js-apis-notification.md#notificationslot) | Yes| Notification slot, whose type can be set.| 331 332**Return value** 333 334| Type| Description| 335| -------- | -------- | 336| Promise\<void\> | Promise used to return the result.| 337 338**Example** 339 340```ts 341import notification from '@ohos.notification' 342 343let mySlot = { 344 type: notification.SlotType.SOCIAL_COMMUNICATION 345} 346reminderAgent.addNotificationSlot(mySlot).then(() => { 347 console.log("addNotificationSlot promise"); 348}); 349``` 350 351 352## reminderAgent.removeNotificationSlot 353 354```ts 355removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void 356``` 357 358Removes a notification slot of a specified type. This API uses an asynchronous callback to return the result. 359 360**System capability**: SystemCapability.Notification.ReminderAgent 361 362**Parameters** 363 364| Name| Type| Mandatory| Description| 365| -------- | -------- | -------- | -------- | 366| slotType | [notification.SlotType](js-apis-notification.md#slottype) | Yes| Type of the reminder notification slot to remove.| 367| callback | AsyncCallback\<void\> | Yes| Asynchronous callback used to return the result.| 368 369**Example** 370 371```ts 372import notification from '@ohos.notification' 373 374reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION, (err, data) => { 375 console.log("removeNotificationSlot callback"); 376}); 377``` 378 379 380## reminderAgent.removeNotificationSlot 381 382```ts 383removeNotificationSlot(slotType: notification.SlotType): Promise<void> 384``` 385 386Removes a notification slot of a specified type. This API uses a promise to return the result. 387 388**System capability**: SystemCapability.Notification.ReminderAgent 389 390**Parameters** 391 392| Name| Type| Mandatory| Description| 393| -------- | -------- | -------- | -------- | 394| slotType | [notification.SlotType](js-apis-notification.md#slottype) | Yes| Type of the reminder notification slot to remove.| 395 396**Return value** 397 398| Type| Description| 399| -------- | -------- | 400| Promise\<void\> | Promise used to return the result.| 401 402**Example** 403 404```ts 405import notification from '@ohos.notification' 406 407reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION).then(() => { 408 console.log("removeNotificationSlot promise"); 409}); 410``` 411 412 413## ActionButtonType 414 415Enumerates button types. 416 417**System capability**: SystemCapability.Notification.ReminderAgent 418 419| Name| Value| Description| 420| -------- | -------- | -------- | 421| ACTION_BUTTON_TYPE_CLOSE | 0 | Button for closing the reminder.| 422| ACTION_BUTTON_TYPE_SNOOZE | 1 | Button for snoozing the reminder.| 423 424 425## ReminderType 426 427Enumerates reminder types. 428 429**System capability**: SystemCapability.Notification.ReminderAgent 430 431| Name| Value| Description| 432| -------- | -------- | -------- | 433| REMINDER_TYPE_TIMER | 0 | Countdown reminder.| 434| REMINDER_TYPE_CALENDAR | 1 | Calendar reminder.| 435| REMINDER_TYPE_ALARM | 2 | Alarm reminder.| 436 437 438## ActionButton 439 440Defines a button displayed in the reminder notification. 441 442**System capability**: SystemCapability.Notification.ReminderAgent 443 444| Name| Type| Mandatory| Description| 445| -------- | -------- | -------- | -------- | 446| title | string | Yes| Text on the button.| 447| type | [ActionButtonType](#actionbuttontype) | Yes| Button type.| 448 449 450## WantAgent 451 452Sets the package and ability that are redirected to when the reminder notification is clicked. 453 454**System capability**: SystemCapability.Notification.ReminderAgent 455 456| Name| Type| Mandatory| Description| 457| -------- | -------- | -------- | -------- | 458| pkgName | string | Yes| Name of the HAP that is redirected to when the reminder notification is clicked.| 459| abilityName | string | Yes| Name of the ability that is redirected to when the reminder notification is clicked.| 460 461 462## MaxScreenWantAgent 463 464Provides the information about the target package and ability to start automatically when the reminder is displayed in full-screen mode. This API is reserved. 465 466**System capability**: SystemCapability.Notification.ReminderAgent 467 468| Name| Type| Mandatory| Description| 469| -------- | -------- | -------- | -------- | 470| pkgName | string | Yes| Name of the HAP that is automatically started when the reminder arrives and the device is not in use.| 471| abilityName | string | Yes| Name of the ability that is automatically started when the reminder arrives and the device is not in use.| 472 473 474## ReminderRequest 475 476Defines the reminder to publish. 477 478**System capability**: SystemCapability.Notification.ReminderAgent 479 480| Name| Type| Mandatory| Description| 481| -------- | -------- | -------- | -------- | 482| reminderType | [ReminderType](#remindertype) | Yes| Type of the reminder.| 483| actionButton | [ActionButton](#actionbutton) | No| Button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.)| 484| wantAgent | [WantAgent](#wantagent) | No| Information about the ability that is redirected to when the notification is clicked.| 485| maxScreenWantAgent | [MaxScreenWantAgent](#maxscreenwantagent) | No| Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.| 486| ringDuration | number | No| Ringing duration, in seconds. The default value is **1**.| 487| snoozeTimes | number | No| Number of reminder snooze times. The default value is **0**.| 488| timeInterval | number | No| Reminder snooze interval, in seconds. The default value is **0**.| 489| title | string | No| Reminder title.| 490| content | string | No| Reminder content.| 491| expiredContent | string | No| Content to be displayed after the reminder expires.| 492| snoozeContent | string | No| Content to be displayed when the reminder is snoozing.| 493| notificationId | number | No| Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one.| 494| slotType | [notification.SlotType](js-apis-notification.md#slottype) | No| Type of the slot used by the reminder.| 495 496 497## ReminderRequestCalendar 498 499ReminderRequestCalendar extends ReminderRequest 500 501Defines a reminder for a calendar event. 502 503**System capability**: SystemCapability.Notification.ReminderAgent 504 505| Name| Type| Mandatory| Description| 506| -------- | -------- | -------- | -------- | 507| dateTime | [LocalDateTime](#localdatetime) | Yes| Reminder time.| 508| repeatMonths | Array\<number\> | No| Month in which the reminder repeats.| 509| repeatDays | Array\<number\> | No| Date on which the reminder repeats.| 510 511 512## ReminderRequestAlarm 513 514ReminderRequestAlarm extends ReminderRequest 515 516Defines a reminder for an alarm. 517 518**System capability**: SystemCapability.Notification.ReminderAgent 519 520| Name| Type| Mandatory| Description| 521| -------- | -------- | -------- | -------- | 522| hour | number | Yes| Hour portion of the reminder time.| 523| minute | number | Yes| Minute portion of the reminder time.| 524| daysOfWeek | Array\<number\> | No| Days of a week when the reminder repeats. The value ranges from 1 to 7, corresponding to the data from Monday to Sunday.| 525 526 527## ReminderRequestTimer 528 529ReminderRequestTimer extends ReminderRequest 530 531Defines a reminder for a scheduled timer. 532 533**System capability**: SystemCapability.Notification.ReminderAgent 534 535| Name| Type| Mandatory| Description| 536| -------- | -------- | -------- | -------- | 537| triggerTimeInSeconds | number | Yes| Number of seconds in the countdown timer.| 538 539 540## LocalDateTime 541 542Sets the time information for a calendar reminder. 543 544**System capability**: SystemCapability.Notification.ReminderAgent 545 546| Name| Type| Mandatory| Description| 547| -------- | -------- | -------- | -------- | 548| year | number | Yes| Year.| 549| month | number | Yes| Month.| 550| day | number | Yes| Date.| 551| hour | number | Yes| Hour.| 552| minute | number | Yes| Minute.| 553| second | number | No| Second.| 554