From 14675d885cefeae0136811d05bc429fbaffe9611 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Fri, 9 Sep 2022 14:00:26 +0800 Subject: [PATCH] update docs (8863) Signed-off-by: ester.zhou --- ...ckground-agent-scheduled-reminder-guide.md | 320 ++++++------------ .../reference/apis/js-apis-reminderAgent.md | 8 +- 2 files changed, 111 insertions(+), 217 deletions(-) diff --git a/en/application-dev/notification/background-agent-scheduled-reminder-guide.md b/en/application-dev/notification/background-agent-scheduled-reminder-guide.md index 0757c602c2..1894942945 100644 --- a/en/application-dev/notification/background-agent-scheduled-reminder-guide.md +++ b/en/application-dev/notification/background-agent-scheduled-reminder-guide.md @@ -7,139 +7,33 @@ You can set your application to call the **ReminderRequest** class to create sch ## Available APIs -**reminderAgent** encapsulates the methods for publishing and canceling reminders. +**reminderAgent** encapsulates the APIs for publishing and canceling reminders. -**Table 1** Major APIs in reminderAgent - -| Name| Description| -| -------- | -------- | -| function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void;
function publishReminder(reminderReq: ReminderRequest): Promise<number>; | Publishes a scheduled reminder.
The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system. | -| function cancelReminder(reminderId: number, callback: AsyncCallback<void>): void;
function cancelReminder(reminderId: number): Promise<void>; | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.)| -| function getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void;
function getValidReminders(): Promise<Array<ReminderRequest>>; | Obtains all valid reminders set by the current application.| -| function cancelAllReminders(callback: AsyncCallback<void>): void;
function cancelAllReminders(): Promise<void>; | Cancels all reminders set by the current application.| -| function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void;
function addNotificationSlot(slot: NotificationSlot): Promise<void>; | Registers a **NotificationSlot** instance to be used by the reminder. | -| function removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void;
function removeNotificationSlot(slotType: notification.SlotType): Promise<void>; | Removes a **NotificationSlot** instance of a specified type. | +For details about the APIs, see [reminderAgent](../reference/apis/js-apis-reminderAgent.md). -**ActionButtonType** enumerates types of buttons displayed in a reminder notification. - -**Table 2** ActionButtonType enums - -| Name| Description| -| -------- | -------- | -| ACTION_BUTTON_TYPE_CLOSE | Close button, which can stop the reminder alert tone, close the reminder notification, and cancel the reminder snoozing.| -| ACTION_BUTTON_TYPE_SNOOZE | Snooze button, which can snooze the reminder.| - -**ReminderType** enumerates the reminder types. - -**Table 3** ReminderType enums +**Table 1** Major APIs in reminderAgent | Name| Description| | -------- | -------- | -| REMINDER_TYPE_TIMER | Countdown reminder.| -| REMINDER_TYPE_CALENDAR | Calendar reminder.| -| REMINDER_TYPE_ALARM | Alarm reminder.| - -**ActionButton** defines a button displayed in the reminder notification. - -**Table 4** ActionButton - -| 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. - -**Table 5** WantAgent - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| pkgName | string | Yes| Name of the package redirected to when the reminder notification is clicked.| -| abilityName | string | Yes| Name of the ability 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. - -**Table 6** MaxScreenWantAgent - -| 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. - -**Table 7** ReminderRequest - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| reminderType | ReminderType | Yes| Type of the reminder.| -| actionButton | [ActionButton?,ActionButton?] | No| Action button displayed in the reminder notification.| -| 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| Ring 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| Extended content to be displayed when the reminder expires.| -| snoozeContent | string | No| Extended content to be displayed when the reminder is snoozing.| -| notificationId | number | No| Notification ID used by the reminder. For details, see **NotificationRequest::SetNotificationId(int32_t id)**.| -| slotType | SlotType | No| Type of the slot used by the reminder. | - -**ReminderRequestCalendar** extends **ReminderRequest** and defines a reminder for a calendar event. - -For the application to run properly, if both **repeatMonths** and **repeatDays** are not specified, the earliest reminder time must be later than the current time. - -**Table 8** ReminderRequestCalendar - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| dateTime | LocalDateTime | Yes| Reminder time, accurate to the minute.| -| repeatMonths | Array<number> | No| Months in which the reminder repeats. The value range is 1 to 12.| -| repeatDays | Array<number> | No| Date on which the reminder repeats. The value range is 1 to 31.| - -**ReminderRequestAlarm** extends **ReminderRequest** and defines a reminder for the alarm clock. - -**Table 9** ReminderRequestAlarm - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| hour | number | Yes| Hour portion of the reminder time. The value range is 0 to 23.| -| minute | number | Yes| Minute portion of the reminder time. The value range is 0 to 59.| -| daysOfWeek | Array<number> | No| Days of a week when the reminder repeats. The value range is 1 to 7.| - -**ReminderRequestTimer** extends **ReminderRequest** and defines a reminder for a scheduled timer. - -**Table 10** ReminderRequestTimer - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| triggerTimeInSeconds | number | Yes| Number of seconds in the countdown timer.| - -**LocalDateTime** defines a **LocalDateTime** instance. - -**Table 11** LocalDateTime - -| 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.| - +| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
publishReminder(reminderReq: ReminderRequest): Promise<number> | Publishes a scheduled reminder.
The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system. | +| cancelReminder(reminderId: number, callback: AsyncCallback<void>): void
cancelReminder(reminderId: number): Promise<void> | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.)| +| getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void
getValidReminders(): Promise<Array<ReminderRequest>> | Obtains all valid reminders set by the current application.| +| cancelAllReminders(callback: AsyncCallback<void>): void
cancelAllReminders(): Promise<void> | Cancels all reminders set by the current application.| +| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
addNotificationSlot(slot: NotificationSlot): Promise<void> | Registers a **NotificationSlot** instance to be used by the reminder.| +| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
removeNotificationSlot(slotType: notification.SlotType): Promise<void> | Removes a **NotificationSlot** instance of a specified type.| ## How to Develop > **NOTE** > -> To publish a reminder, your application needs to apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission. +> 1. To publish a reminder through the reminder agent, your application needs to apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission. +> +> 2. Your application must have notification enabled. For details, see [Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8). -Publish a 10-second countdown reminder. +1. Define a reminder agent. -1. Define a countdown timer instance. - ``` + Sample code for defining a reminder agent for a countdown timer: + ```js import reminderAgent from '@ohos.reminderAgent'; import notification from '@ohos.notification'; export default { @@ -172,8 +66,97 @@ Publish a 10-second countdown reminder. } ``` -2. Publish the reminder. - ``` + Sample code for defining a reminder agent for a calendar event: + + ```js + // For a JS project: + // calendar: { + // For an eTS project: + let calendar : reminderAgent.ReminderRequestCalendar = { + reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, + dateTime: { + year: 2050, + month: 7, + day: 30, + hour: 11, + minute: 14, + second: 30 + }, + repeatMonths: [1], + repeatDays: [1], + actionButton: [ + { + title: "close", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + }, + { + title: "snooze", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + }, + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + ringDuration: 5, + snoozeTimes: 2, + timeInterval: 5, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + snoozeContent: "remind later", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION + } + ``` + + Sample code for defining a reminder agent for an alarm: + + ```js + // For a JS project: + // alarm: { + // For an eTS project: + let alarm : reminderAgent.ReminderRequestAlarm = { + reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, + hour: 11, + minute: 14, + daysOfWeek: [0], + actionButton: [ + { + title: "close", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + }, + { + title: "snooze", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + }, + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + ringDuration: 5, + snoozeTimes: 2, + timeInterval: 5, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + snoozeContent: "remind later", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION + } + ``` + +2. Publish a countdown reminder. + ```js startTimer() { reminderAgent.publishReminder(this.timer, (err, reminderId) =>{ this.printInfo(JSON.stringify(err)); @@ -183,98 +166,9 @@ Publish a 10-second countdown reminder. ``` HML page code: - ``` + ```html
``` -Sample code for defining a calendar reminder instance: - -``` -// For a JS project: -// calendar: { -// For an eTS project: -let calendar : reminderAgent.ReminderRequestCalendar = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, - dateTime: { - year: 2050, - month: 7, - day: 30, - hour: 11, - minute: 14, - second: 30 - }, - repeatMonths: [1], - repeatDays: [1], - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION -} -``` - -Sample code for defining an alarm reminder instance: - -``` -// For a JS project: -// alarm: { -// For an eTS project: -let alarm : reminderAgent.ReminderRequestAlarm = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, - hour: 11, - minute: 14, - daysOfWeek: [0], - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION -} -``` - diff --git a/en/application-dev/reference/apis/js-apis-reminderAgent.md b/en/application-dev/reference/apis/js-apis-reminderAgent.md index 24f01b3f40..7db47e5bec 100644 --- a/en/application-dev/reference/apis/js-apis-reminderAgent.md +++ b/en/application-dev/reference/apis/js-apis-reminderAgent.md @@ -20,7 +20,7 @@ import reminderAgent from'@ohos.reminderAgent'; publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void -Publishes an agent-powered reminder. This API uses an asynchronous callback to return the result. +Publishes 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). **Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER @@ -49,7 +49,7 @@ Publishes an agent-powered reminder. This API uses an asynchronous callback to r publishReminder(reminderReq: ReminderRequest): Promise<number> -Publishes an agent-powered reminder. This API uses a promise callback to return the result. +Publishes 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). **Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER @@ -435,7 +435,7 @@ Sets the package and ability that are redirected to when the reminder notificati ## 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. +Provides the information about the target package and ability to start automatically when the reminder is displayed in full-screen mode. This API is reserved. **System capability**: SystemCapability.Notification.ReminderAgent @@ -454,7 +454,7 @@ Defines the reminder to publish. | 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.)| +| actionButton | [ActionButton?, ActionButton?] | No| 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.| -- GitLab