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