未验证 提交 8d6d5313 编写于 作者: O openharmony_ci 提交者: Gitee

!8936 翻译完成 8307:background-agent-scheduled-reminder-guide.md

Merge pull request !8936 from ester.zhou/TR-8307
...@@ -4,167 +4,148 @@ ...@@ -4,167 +4,148 @@
You can set your application to call the **ReminderRequest** class 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, even when your application is frozen or exits. You can set your application to call the **ReminderRequest** class 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, even when your application is frozen or exits.
## Available APIs ## Available APIs
**reminderAgent** encapsulates the methods for publishing and canceling reminders. **reminderAgent** encapsulates the methods for publishing and canceling reminders.
**Table 1** Major APIs in reminderAgent **Table 1** Major APIs in reminderAgent
| Name| Description|
| -------- | -------- |
| API | Description | | function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback&lt;number&gt;): void;<br>function publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt;; | Publishes a scheduled reminder.<br>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&lt;void&gt;): void;<br>function cancelReminder(reminderId: number): Promise&lt;void&gt;; | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.)|
| function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback\<number>): void;<br>function publishReminder(reminderReq: ReminderRequest): Promise\<number>; | Publishes a scheduled reminder.<br>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 getValidReminders(callback: AsyncCallback&lt;Array&lt;ReminderRequest&gt;&gt;): void;<br>function getValidReminders(): Promise&lt;Array&lt;ReminderRequest&gt;&gt;; | Obtains all valid reminders set by the current application.|
| function cancelReminder(reminderId: number, callback: AsyncCallback\<void>): void;<br/>function cancelReminder(reminderId: number): Promise\<void>; | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.) | | function cancelAllReminders(callback: AsyncCallback&lt;void&gt;): void;<br>function cancelAllReminders(): Promise&lt;void&gt;; | Cancels all reminders set by the current application.|
| function getValidReminders(callback: AsyncCallback<Array\<ReminderRequest>>): void;<br/>function getValidReminders(): Promise<Array\<ReminderRequest>>; | Obtains all valid reminders set by the current application. | | function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback&lt;void&gt;): void;<br>function addNotificationSlot(slot: NotificationSlot): Promise&lt;void&gt;; | Registers a **NotificationSlot** instance to be used by the reminder. |
| function cancelAllReminders(callback: AsyncCallback\<void>): void;<br/>function cancelAllReminders(): Promise\<void>; | Cancels all reminders set by the current application. | | function removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback&lt;void&gt;): void;<br>function removeNotificationSlot(slotType: notification.SlotType): Promise&lt;void&gt;; | Removes a **NotificationSlot** instance of a specified type. |
| function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback\<void>): void;<br/>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. |
**ActionButtonType** enumerates types of buttons displayed in a reminder notification. **ActionButtonType** enumerates types of buttons displayed in a reminder notification.
**Table 2** ActionButtonType enumeration **Table 2** ActionButtonType enums
| Name| Description|
| 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_CLOSE | Close button, which can be tapped to 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. **ReminderType** enumerates the reminder types.
**Table 3** ReminderType enumeration **Table 3** ReminderType enums
| Name | Description | | Name| Description|
| ---------------------- | ------------------- | | -------- | -------- |
| REMINDER_TYPE_TIMER | Countdown reminder. | | REMINDER_TYPE_TIMER | Countdown reminder.|
| REMINDER_TYPE_CALENDAR | Calendar reminder. | | REMINDER_TYPE_CALENDAR | Calendar reminder.|
| REMINDER_TYPE_ALARM | Alarm reminder. | | REMINDER_TYPE_ALARM | Alarm reminder.|
**ActionButton** defines a button displayed in the reminder notification. **ActionButton** defines a button displayed in the reminder notification.
**Table 4** ActionButton instance **Table 4** ActionButton
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Name | Type | Mandatory | Description | | title | string | Yes| Text on the button.|
| ----- | ---------------- | --------- | ------------------- | | type | ActionButtonType | Yes| Button type.|
| 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. **WantAgent** sets the package and ability that are redirected to when the reminder notification is clicked.
**Table 5** WantAgent instance **Table 5** WantAgent
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| ----------- | ------ | --------- | ------------------------------------------------------------ | | -------- | -------- | -------- | -------- |
| pkgName | string | Yes | Name of the package redirected to when the reminder notification is clicked. | | 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. | | 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. **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 instance **Table 6** MaxScreenWantAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| 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.|
| 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. **ReminderRequest** defines the reminder to publish.
**Table 7** ReminderRequest instance **Table 7** ReminderRequest
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Name | Type | Mandatory | Description | | reminderType | ReminderType | Yes| Type of the reminder.|
| ------------------ | ------------------------------ | --------- | ------------------------------------------------------------ | | actionButton | [ActionButton?,ActionButton?] | No| Action button displayed in the reminder notification.|
| reminderType | ReminderType | Yes | Type of the reminder. | | wantAgent | WantAgent | No| Information about the ability that is redirected to when the notification is clicked.|
| actionButton | [ActionButton?, ActionButton?] | No | Action button displayed in the reminder notification. | | 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.|
| wantAgent | WantAgent | No | Information about the ability that is redirected to when the notification is clicked. | | ringDuration | number | No| Ring duration.|
| 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. | | snoozeTimes | number | No| Number of reminder snooze times.|
| ringDuration | number | No | Ring duration. | | timeInterval | number | No| Reminder snooze interval.|
| snoozeTimes | number | No | Number of reminder snooze times. | | title | string | No| Reminder title.|
| timeInterval | number | No | Reminder snooze interval. | | content | string | No| Reminder content.|
| title | string | No | Reminder title. | | expiredContent | string | No| Extended content to be displayed when the reminder expires.|
| content | string | No | Reminder content. | | snoozeContent | string | No| Extended content to be displayed when the reminder is snoozing.|
| expiredContent | string | No | Extended content to be displayed when the reminder expires. | | notificationId | number | No| Notification ID used by the reminder. For details, see **NotificationRequest::SetNotificationId(int32_t id)**.|
| snoozeContent | string | No | Extended content to be displayed when the reminder is snoozing. | | slotType | SlotType | No| Type of the slot used by the reminder. |
| notificationId | number | No | Notification ID used by the reminder. For details, see the API reference of the **NotificationRequest.setNotificationId(int id)** method. |
| slotType | SlotType | No | Type of the slot used by the reminder. |
**ReminderRequestCalendar** extends **ReminderRequest** and defines a reminder for a calendar event. **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. 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 instance **Table 8** ReminderRequestCalendar
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| ------------ | -------------- | --------- | ------------------------------------------------------------ | | -------- | -------- | -------- | -------- |
| dateTime | LocalDateTime | Yes | Reminder time, accurate to the minute. | | 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. | | repeatMonths | Array&lt;number&gt; | 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. | | repeatDays | Array&lt;number&gt; | 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. **ReminderRequestAlarm** extends **ReminderRequest** and defines a reminder for the alarm clock.
**Table 9** ReminderRequestAlarm instance **Table 9** ReminderRequestAlarm
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| 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.|
| hour | number | Yes | Hour portion of the reminder time. The value range is 0 to 23. | | daysOfWeek | Array&lt;number&gt; | No| Days of a week when the reminder repeats. The value range is 1 to 7.|
| 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. **ReminderRequestTimer** extends **ReminderRequest** and defines a reminder for a scheduled timer.
**Table 10** ReminderRequestTimer instance **Table 10** ReminderRequestTimer
| Name| Type| Mandatory| Description|
| Name | Type | Mandatory | Description | | -------- | -------- | -------- | -------- |
| -------------------- | ------ | --------- | ----------------------------------------- | | triggerTimeInSeconds | number | Yes| Number of seconds in the countdown timer.|
| triggerTimeInSeconds | number | Yes | Number of seconds in the countdown timer. |
**LocalDateTime** defines a **LocalDateTime** instance. **LocalDateTime** defines a **LocalDateTime** instance.
**Table 11** 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.|
| 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. |
## How to Develop ## How to Develop
> **NOTE** > **NOTE**
>
> To publish a reminder, your application needs to apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission. > To publish a reminder, your application needs to apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission.
Publish a 10-second countdown reminder. Publish a 10-second countdown reminder.
1. Define a countdown timer instance. 1. Define a countdown timer instance.
``` ```
import reminderAgent from '@ohos.reminderAgent'; import reminderAgent from '@ohos.reminderAgent';
import notification from '@ohos.notification'; import notification from '@ohos.notification';
export default { export default {
// In JS Project: // For a JS project:
// timer: { // timer: {
// In eTS Project: // For an eTS project:
let timer : reminderAgent.ReminderRequestTimer = { let timer : reminderAgent.ReminderRequestTimer = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 10, triggerTimeInSeconds: 10,
...@@ -192,7 +173,6 @@ Publish a 10-second countdown reminder. ...@@ -192,7 +173,6 @@ Publish a 10-second countdown reminder.
``` ```
2. Publish the reminder. 2. Publish the reminder.
``` ```
startTimer() { startTimer() {
reminderAgent.publishReminder(this.timer, (err, reminderId) =>{ reminderAgent.publishReminder(this.timer, (err, reminderId) =>{
...@@ -203,7 +183,6 @@ Publish a 10-second countdown reminder. ...@@ -203,7 +183,6 @@ Publish a 10-second countdown reminder.
``` ```
HML page code: HML page code:
``` ```
<div class="container"> <div class="container">
<button type="text" value="publishReminder" onclick="startTimer"></button> <button type="text" value="publishReminder" onclick="startTimer"></button>
...@@ -213,9 +192,9 @@ Publish a 10-second countdown reminder. ...@@ -213,9 +192,9 @@ Publish a 10-second countdown reminder.
Sample code for defining a calendar reminder instance: Sample code for defining a calendar reminder instance:
``` ```
// In JS Project: // For a JS project:
// calendar: { // calendar: {
// In eTS Project: // For an eTS project:
let calendar : reminderAgent.ReminderRequestCalendar = { let calendar : reminderAgent.ReminderRequestCalendar = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR,
dateTime: { dateTime: {
...@@ -261,9 +240,9 @@ let calendar : reminderAgent.ReminderRequestCalendar = { ...@@ -261,9 +240,9 @@ let calendar : reminderAgent.ReminderRequestCalendar = {
Sample code for defining an alarm reminder instance: Sample code for defining an alarm reminder instance:
``` ```
// In JS Project: // For a JS project:
// alarm: { // alarm: {
// In eTS Project: // For an eTS project:
let alarm : reminderAgent.ReminderRequestAlarm = { let alarm : reminderAgent.ReminderRequestAlarm = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM,
hour: 11, hour: 11,
...@@ -297,4 +276,5 @@ let alarm : reminderAgent.ReminderRequestAlarm = { ...@@ -297,4 +276,5 @@ let alarm : reminderAgent.ReminderRequestAlarm = {
notificationId: 100, notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION slotType: notification.SlotType.SOCIAL_COMMUNICATION
} }
``` ```
\ No newline at end of file
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册