reminderAgent
The reminderAgent module provides APIs for publishing scheduled reminders through the reminder agent.
You 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.
NOTE
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.
Modules to Import
import reminderAgent from'@ohos.reminderAgent';
reminderAgent.publishReminder
publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
Publishes an agent-powered reminder. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.PUBLISH_AGENT_REMINDER
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
reminderReq | ReminderRequest | Yes | Reminder to be published. |
callback | AsyncCallback<number> | Yes | Asynchronous callback used to return the published reminder's ID. |
Example
export default {
data: {
timer: {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 3
}
},
startTimer() {
reminderAgent.publishReminder(timer, (err, reminderId) => { console.log("reminderId = " + reminderId);
});
}
}
reminderAgent.publishReminder
publishReminder(reminderReq: ReminderRequest): Promise<number>
Publishes an agent-powered reminder. This API uses a promise callback to return the result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
reminderReq | ReminderRequest | Yes | Reminder to be published. |
Return value
Type | Description |
---|---|
Promise<number> | Promise used to return the published reminder's ID. |
Example
export default {
data:
{timer: {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 3
}
},
startTimer() {
reminderAgent.publishReminder(this.timer).then((reminderId) => {
console.log("reminderId = " + reminderId);
});
}
}
reminderAgent.cancelReminder
cancelReminder(reminderId: number, callback: AsyncCallback<void>): void
Cancels the reminder with the specified ID. This API uses an asynchronous callback to return the cancellation result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
reminderId | number | Yes | ID of the reminder to cancel. |
callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result. |
Example
export default {
cancel() {
reminderAgent.cancelReminder(1, (err, data) => {
console.log("do next");
});
}
}
reminderAgent.cancelReminder
cancelReminder(reminderId: number): Promise<void>
Cancels the reminder with the specified ID. This API uses a promise to return the cancellation result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
reminderId | number | Yes | ID of the reminder to cancel. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
export default {
cancel() {
reminderAgent.cancelReminder(1).then(() => {
console.log("do next");
});
}
}
reminderAgent.getValidReminders
getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void
Obtains all valid (not yet expired) reminders set by the current application. This API uses an asynchronous callback to return the reminders.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Array<ReminderRequest>> | Yes | Asynchronous callback used to return an array of all valid reminders set by the current application. |
Example
reminderAgent.getValidReminders((err, reminders) => {
for (let i = 0; i < reminders.length; i++) {
console.log("getValidReminders = " + reminders[i]);
console.log("getValidReminders, reminderType = " + reminders[i].reminderType);
for (let j = 0; j < reminders[i].actionButton.length; j++) {
console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title);
console.log("getValidReminders, actionButton.type = " + reminders[i].actionButton[j].type);
}
console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent.pkgName);
console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent.abilityName);
console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent.pkgName);
console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent.abilityName);
console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration);
console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes);
console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval);
console.log("getValidReminders, title = " + reminders[i].title);
console.log("getValidReminders, content = " + reminders[i].content);
console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent);
console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent);
console.log("getValidReminders, notificationId = " + reminders[i].notificationId);
console.log("getValidReminders, slotType = " + reminders[i].slotType);
}
})
reminderAgent.getValidReminders
getValidReminders(): Promise<Array<ReminderRequest>>
Obtains all valid (not yet expired) reminders set by the current application. This API uses a promise to return the reminders.
System capability: SystemCapability.Notification.ReminderAgent
Return value
Type | Description |
---|---|
Promise<Array<ReminderRequest>> | Promise used to return an array of all valid reminders set by the current application. |
Example
reminderAgent.getValidReminders().then((reminders) => {
for (let i = 0; i < reminders.length; i++) {
console.log("getValidReminders = " + reminders[i]);
console.log("getValidReminders, reminderType = " + reminders[i].reminderType);
for (let j = 0; j < reminders[i].actionButton.length; j++) {
console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title);
console.log("getValidReminders, actionButton.type = " + reminders[i].actionButton[j].type);
}
console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent.pkgName);
console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent.abilityName);
console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent.pkgName);
console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent.abilityName);
console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration);
console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes);
console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval);
console.log("getValidReminders, title = " + reminders[i].title);
console.log("getValidReminders, content = " + reminders[i].content);
console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent);
console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent);
console.log("getValidReminders, notificationId = " + reminders[i].notificationId);
console.log("getValidReminders, slotType = " + reminders[i].slotType);
}
})
reminderAgent.cancelAllReminders
cancelAllReminders(callback: AsyncCallback<void>): void
Cancels all reminders set by the current application. This API uses an asynchronous callback to return the cancellation result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result. |
Example
reminderAgent.cancelAllReminders((err, data) =>{
console.log("do next")})
reminderAgent.cancelAllReminders
cancelAllReminders(): Promise<void>
Cancels all reminders set by the current application. This API uses a promise to return the cancellation result.
System capability: SystemCapability.Notification.ReminderAgent
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
reminderAgent.cancelAllReminders().then(() => {
console.log("do next")})
reminderAgent.addNotificationSlot
addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
Adds a notification slot. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
slot | NotificationSlot | Yes | Notification slot, whose type can be set. |
callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result. |
Example
export default { data: { mySlot: {
type: 3,
sound: "/sdcard/music2.mp3"
} },
addSlot() {
reminderAgent.addNotificationSlot(this.mySlot, (err, data) => {
console.log("do next");
});
}
}
reminderAgent.addNotificationSlot
addNotificationSlot(slot: NotificationSlot): Promise<void>
Adds a notification slot. This API uses a promise to return the result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
slot | NotificationSlot | Yes | Notification slot, whose type can be set. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
export default { data: { mySlot: {
type: 3,
sound: "/sdcard/music2.mp3"
} },
addSlot() {
reminderAgent.addNotificationSlot(this.mySlot).then(() => {
console.log("do next");
});
}
}
reminderAgent.removeNotificationSlot
removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
Removes a notification slot of a specified type. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
slotType | notification.SlotType | Yes | Type of the notification slot to remove. |
callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result. |
Example
export default {
removeSlot() {reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION, (err, data) => {
console.log("do next");
});
}
}
reminderAgent.removeNotificationSlot
removeNotificationSlot(slotType: notification.SlotType): Promise<void>
Removes a notification slot of a specified type. This API uses a promise to return the result.
System capability: SystemCapability.Notification.ReminderAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
slotType | notification.SlotType | Yes | Type of the notification slot to remove. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
export default {
removeSlot() { reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION).then(() => {
console.log("do next");
});
}
}
ActionButtonType
Enumerates button types.
System capability: SystemCapability.Notification.ReminderAgent
Name | Default Value | Description |
---|---|---|
ACTION_BUTTON_TYPE_CLOSE | 0 | Button for closing the reminder. |
ACTION_BUTTON_TYPE_SNOOZE | 1 | Button for snoozing the reminder. |
ReminderType
Enumerates reminder types.
System capability: SystemCapability.Notification.ReminderAgent
Name | Default Value | Description |
---|---|---|
REMINDER_TYPE_TIMER | 0 | Countdown reminder. |
REMINDER_TYPE_CALENDAR | 1 | Calendar reminder. |
REMINDER_TYPE_ALARM | 2 | Alarm reminder. |
ActionButton
Defines a button displayed in the reminder notification.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
title | string | Yes | Text on the button. |
type | ActionButtonType | Yes | Button type. |
WantAgent
Sets the package and ability that are redirected to when the reminder notification is clicked.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
pkgName | string | Yes | Name of the package that is redirected to when the reminder notification is clicked. |
abilityName | string | Yes | Name of the ability that is redirected to when the reminder notification is clicked. |
MaxScreenWantAgent
Sets the name of the target package and ability to start automatically when the reminder arrives and the device is not in use. If the device is in use, a notification will be displayed.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
pkgName | string | Yes | Name of the package that is automatically started when the reminder arrives and the device is not in use. |
abilityName | string | Yes | Name of the ability that is automatically started when the reminder arrives and the device is not in use. |
ReminderRequest
Defines the reminder to publish.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
reminderType | ReminderType | Yes | Type of the reminder. |
actionButton | [ActionButton?, ActionButton?] | No | Action button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.) |
wantAgent | WantAgent | No | Information about the ability that is redirected to when the notification is clicked. |
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. |
ringDuration | number | No | Ringing duration. |
snoozeTimes | number | No | Number of reminder snooze times. |
timeInterval | number | No | Reminder snooze interval. |
title | string | No | Reminder title. |
content | string | No | Reminder content. |
expiredContent | string | No | Content to be displayed after the reminder expires. |
snoozeContent | string | No | Content to be displayed when the reminder is snoozing. |
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. |
slotType | notification.SlotType | No | Type of the slot used by the reminder. |
ReminderRequestCalendar
ReminderRequestCalendar extends ReminderRequest
Defines a reminder for a calendar event.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
dateTime | LocalDateTime | Yes | Reminder time. |
repeatMonths | Array<number> | No | Month in which the reminder repeats. |
repeatDays | Array<number> | No | Date on which the reminder repeats. |
ReminderRequestAlarm
ReminderRequestAlarm extends ReminderRequest
Defines a reminder for an alarm.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
hour | number | Yes | Hour portion of the reminder time. |
minute | number | Yes | Minute portion of the reminder time. |
daysOfWeek | Array<number> | No | Days of a week when the reminder repeats. |
ReminderRequestTimer
ReminderRequestTimer extends ReminderRequest
Defines a reminder for a scheduled timer.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
triggerTimeInSeconds | number | Yes | Number of seconds in the countdown timer. |
LocalDateTime
Sets the time information for a calendar reminder.
System capability: SystemCapability.Notification.ReminderAgent
Name | Type | Mandatory | Description |
---|---|---|---|
year | number | Yes | Year. |
month | number | Yes | Month. |
day | number | Yes | Date. |
hour | number | Yes | Hour. |
minute | number | Yes | Minute. |
second | number | No | Second. |