!8863 提醒代理文档更新

Merge pull request !8863 from 廖康康/master

!8863 提醒代理文档更新
Merge pull request !8863 from 廖康康/master
ba08a694 · openharmony_ci · Gitee · 074394b1 · f8b7e1c1 · ba08a694
2 changed file
--- a/zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md
+++ b/zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md
-# 开发指导
+# 后台提醒开发指导

 ## 场景介绍

@@ -7,138 +7,33 @@

 ## 接口说明

-reminderAgent：封装了发布、取消提醒类通知的方法
+reminderAgent：封装了发布、取消提醒类通知的方法。
+
+具体后台提醒相关功能接口请见[后台代理提醒](../reference/apis/js-apis-reminderAgent.md)。

 **表1** reminderAgent主要接口

 | 接口名 | 描述 |
 | -------- | -------- |
-| function&nbsp;publishReminder(reminderReq:&nbsp;ReminderRequest,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):&nbsp;void;<br/>function&nbsp;publishReminder(reminderReq:&nbsp;ReminderRequest):&nbsp;Promise&lt;number&gt;; | 发布一个定时提醒类通知。<br/>单个应用有效的提醒个数最多支持30个（不包括已经超时，即后续不会再提醒的提醒实例）<br/>整个系统有效的提醒个数最多支持2000个（不包括已经超时，即后续不会再提醒的提醒实例） |
-| function&nbsp;cancelReminder(reminderId:&nbsp;number,&nbsp;callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void;<br/>function&nbsp;cancelReminder(reminderId:&nbsp;number):&nbsp;Promise&lt;void&gt;; | 取消一个指定的提醒类通知。(reminderId从publishReminder的返回值获取) |
-| function&nbsp;getValidReminders(callback:&nbsp;AsyncCallback&lt;Array&lt;ReminderRequest&gt;&gt;):&nbsp;void;<br/>function&nbsp;getValidReminders():&nbsp;Promise&lt;Array&lt;ReminderRequest&gt;&gt;; | 获取当前应用设置的所有有效的提醒。 |
-| function&nbsp;cancelAllReminders(callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void;<br/>function&nbsp;cancelAllReminders():&nbsp;Promise&lt;void&gt;; | 取消当前应用设置的所有提醒 |
-| function&nbsp;addNotificationSlot(slot:&nbsp;NotificationSlot,&nbsp;callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void;<br/>function&nbsp;addNotificationSlot(slot:&nbsp;NotificationSlot):&nbsp;Promise&lt;void&gt;; | 注册一个提醒类需要使用的NotificationSlot |
-| function&nbsp;removeNotificationSlot(slotType:&nbsp;notification.SlotType,&nbsp;callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void;<br/>function&nbsp;removeNotificationSlot(slotType:&nbsp;notification.SlotType):&nbsp;Promise&lt;void&gt;; | 删除指定类型的NotificationSlot |
-
-enum ActionButtonType: 在提醒弹出的通知界面上的按钮的类型。
-
-**表2** ActionButtonType 枚举类型
-
-| 枚举名 | 描述 |
-| -------- | -------- |
-| ACTION_BUTTON_TYPE_CLOSE | 关闭按钮。关闭提醒的通知，取消延迟提醒。如果正在响铃，点击后会关闭当前提醒的铃声。 |
-| ACTION_BUTTON_TYPE_SNOOZE | 延迟按钮。点击当前的提醒会延迟相应时间。 |
-
-enum ReminderType: 提醒类型
-
-**表3** ReminderType 提醒类型枚举
-
-| 枚举名 | 描述 |
-| -------- | -------- |
-| REMINDER_TYPE_TIMER | 指明是倒计时类型 |
-| REMINDER_TYPE_CALENDAR | 指明是日历类型 |
-| REMINDER_TYPE_ALARM | 指明是闹钟类型 |
-
-interface ActionButton：在提醒弹出的通知界面上的按钮实例
-
-**表4** ActionButton
-
-| 参数名 | 类型 | 必填 | 描述 |
-| -------- | -------- | -------- | -------- |
-| title | string | 是 | 按钮上显示的名称 |
-| type | ActionButtonType | 是 | 按钮的类型 |
-
-interface WantAgent: 设置点击通知后需要跳转的目标ability信息
-
-**表5** WantAgent
-
-| 参数名 | 类型 | 是否必选 | 描述 |
-| -------- | -------- | -------- | -------- |
-| pkgName | string | 是 | 目标包的名称 |
-| abilityName | string | 是 | 目标ability的名称 |
-
-interface MaxScreenWantAgent: 设置提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框
-
-**表6** MaxScreenWantAgent
-
-| 参数名 | 类型 | 必填 | 描述 |
-| -------- | -------- | -------- | -------- |
-| pkgName | string | 是 | 目标包的名称 |
-| abilityName | string | 是 | 目标ability的名称 |
-
-interface ReminderRequest: 需要发布的提醒实例的信息
-
-**表7** ReminderRequest
-
-| 参数名 | 类型 | 必填 | 描述 |
-| -------- | -------- | -------- | -------- |
-| reminderType | ReminderType | 是 | 提醒的类型 |
-| actionButton | [ActionButton?,ActionButton?] | 否 | 弹出的提醒通知栏中显示的按钮 |
-| wantAgent | WantAgent | 否 | 点击通知后需要跳转的目标ability信息 |
-| maxScreenWantAgent | MaxScreenWantAgent | 否 | 提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框 |
-| ringDuration | number | 否 | 响铃时长 |
-| snoozeTimes | number | 否 | 延迟提醒次数 |
-| timeInterval | number | 否 | 延迟提醒间隔 |
-| title | string | 否 | 提醒的标题 |
-| content | string | 否 | 提醒的内容 |
-| expiredContent | string | 否 | 提醒“过期”时显示的扩展内容 |
-| snoozeContent | string | 否 | 提醒“再响”时显示的扩展内容 |
-| notificationId | number | 否 | 提醒使用的notificationRequest的id，参见NotificationRequest::SetNotificationId(int32_t&nbsp;id) |
-| slotType | SlotType | 否 | 提醒使用的slot类型 |
-
-interface ReminderRequestCalendar extends ReminderRequest: 日历类提醒实例。
-
-如果没有指定重复的月或天，那么第一次指定的目标时间必须大于当前时间，否则应用将异常退出。
-
-**表8** ReminderRequestCalendar
-
-| 参数名 | 类型 | 必填 | 描述 |
-| -------- | -------- | -------- | -------- |
-| dateTime | LocalDateTime | 是 | 设置目标时间(精确到分钟级别) |
-| repeatMonths | Array&lt;number&gt; | 否 | 设置重复提醒的月份，范围从 1 到 12 |
-| repeatDays | Array&lt;number&gt; | 否 | 设置重复提醒的日期，范围从 1 到 31 |
-
-interface ReminderRequestAlarm extends ReminderRequest: 闹钟类提醒实例。
-
-**表9** ReminderRequestAlarm
-
-| 参数名 | 类型 | 必填 | 描述 |
-| -------- | -------- | -------- | -------- |
-| hour | number | 是 | 设置目标时间（小时），范围从 0 到 23 |
-| minute | number | 是 | 设置目标时间（分钟），范围从 0 到 59 |
-| daysOfWeek | Array&lt;number&gt; | 否 | 设置每个星期哪一天重复提醒，范围从 1 到 7 |
-
-interface ReminderRequestTimer extends ReminderRequest：倒计时提醒实例
-
-**表10** ReminderRequestTimer
-
-| 参数名 | 类型 | 必填 | 描述 |
-| -------- | -------- | -------- | -------- |
-| triggerTimeInSeconds | number | 是 | 设置倒计时秒数 |
-
-interface LocalDateTime：时间信息实例
-
-**表11** LocalDateTime
-
-| 参数名 | 类型 | 必填 | 描述 |
-| -------- | -------- | -------- | -------- |
-| year | number | 是 | 年 |
-| month | number | 是 | 月 |
-| day | number | 是 | 日 |
-| hour | number | 是 | 时 |
-| minute | number | 是 | 分 |
-| second | number | 否 | 秒 |
-
+| publishReminder(reminderReq:&nbsp;ReminderRequest,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):&nbsp;void<br/>publishReminder(reminderReq:&nbsp;ReminderRequest):&nbsp;Promise&lt;number&gt; | 发布一个定时提醒类通知。<br/>单个应用有效的提醒个数最多支持30个（不包括已经超时，即后续不会再提醒的提醒实例）<br/>整个系统有效的提醒个数最多支持2000个（不包括已经超时，即后续不会再提醒的提醒实例） |
+| cancelReminder(reminderId:&nbsp;number,&nbsp;callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void<br/>cancelReminder(reminderId:&nbsp;number):&nbsp;Promise&lt;void&gt; | 取消一个指定的提醒类通知。(reminderId从publishReminder的返回值获取) |
+| getValidReminders(callback:&nbsp;AsyncCallback&lt;Array&lt;ReminderRequest&gt;&gt;):&nbsp;void<br/>getValidReminders():&nbsp;Promise&lt;Array&lt;ReminderRequest&gt;&gt; | 获取当前应用设置的所有有效的提醒。 |
+| cancelAllReminders(callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void<br/>cancelAllReminders():&nbsp;Promise&lt;void&gt; | 取消当前应用设置的所有提醒 |
+| addNotificationSlot(slot:&nbsp;NotificationSlot,&nbsp;callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void<br/>addNotificationSlot(slot:&nbsp;NotificationSlot):&nbsp;Promise&lt;void&gt; | 注册一个提醒类需要使用的NotificationSlot |
+| removeNotificationSlot(slotType:&nbsp;notification.SlotType,&nbsp;callback:&nbsp;AsyncCallback&lt;void&gt;):&nbsp;void<br/>removeNotificationSlot(slotType:&nbsp;notification.SlotType):&nbsp;Promise&lt;void&gt; | 删除指定类型的NotificationSlot |

 ## 开发步骤

 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
-> 应用需要配置权限：ohos.permission.PUBLISH_AGENT_REMINDER
+>
+> 1. 应用需要配置权限：ohos.permission.PUBLISH_AGENT_REMINDER。
+>
+> 2. 应用需要申请通知弹窗：[Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8)。

-发布一个10秒倒计时提醒
+1. 定义一个提醒代理。

-1. 定义一个倒计时实例
-   ```
+   倒计时实例定义：
+   ```js
   import reminderAgent from '@ohos.reminderAgent';
   import notification from '@ohos.notification';
   export default {
@@ -171,30 +66,13 @@ interface LocalDateTime：时间信息实例
   }
   ```

-2. 发布提醒
-   ```
-   startTimer() {
-       reminderAgent.publishReminder(this.timer, (err, reminderId) =>{
-           this.printInfo(JSON.stringify(err));
-           this.printInfo("reminderId:" + reminderId);
-       });
-   }
-   ```
-
-   HML页面：
-   ```
-   <div class="container">
-       <button type="text" value="publishReminder" onclick="startTimer"></button>
-   </div>
-   ```
+   日历实例定义：

-日历实例定义：
-
-```
-// JS工程写法：
-// calendar: {
-// eTS工程写法：
-let calendar : reminderAgent.ReminderRequestCalendar = {
+    ```js
+    // JS工程写法：
+    // calendar: {
+    // eTS工程写法：
+    let calendar : reminderAgent.ReminderRequestCalendar = {
        reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR,
        dateTime: {
            year: 2050,
@@ -233,16 +111,16 @@ let calendar : reminderAgent.ReminderRequestCalendar = {
        snoozeContent: "remind later",
        notificationId: 100,
        slotType: notification.SlotType.SOCIAL_COMMUNICATION
-}
-```
+    }
+    ```

-闹钟实例定义：
+    闹钟实例定义：

-```
-// JS工程写法：
-// alarm: {
-// eTS工程写法：
-let alarm : reminderAgent.ReminderRequestAlarm = {
+    ```js
+    // JS工程写法：
+    // alarm: {
+    // eTS工程写法：
+    let alarm : reminderAgent.ReminderRequestAlarm = {
        reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM,
        hour: 11,
        minute: 14,
@@ -274,9 +152,25 @@ let alarm : reminderAgent.ReminderRequestAlarm = {
        snoozeContent: "remind later",
        notificationId: 100,
        slotType: notification.SlotType.SOCIAL_COMMUNICATION
-}
-```
+    }
+    ```
+
+2. 发布倒计时提醒。
+   ```js
+   startTimer() {
+       reminderAgent.publishReminder(this.timer, (err, reminderId) =>{
+           this.printInfo(JSON.stringify(err));
+           this.printInfo("reminderId:" + reminderId);
+       });
+   }
+   ```

+   HML页面：
+   ```html
+   <div class="container">
+       <button type="text" value="publishReminder" onclick="startTimer"></button>
+   </div>
+   ```

 ## 相关实例


--- a/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md
@@ -19,7 +19,7 @@ import reminderAgent from'@ohos.reminderAgent';

 publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback&lt;number&gt;): void

-发布一个后台代理提醒，使用callback方式实现异步调用。
+发布一个后台代理提醒，使用callback方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。

 **需要权限**： ohos.permission.PUBLISH_AGENT_REMINDER

@@ -48,7 +48,7 @@ publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback&lt;number&

 publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt;

-发布一个后台代理提醒，使用Promise方式实现异步调用。
+发布一个后台代理提醒，使用Promise方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。

 **需要权限**： ohos.permission.PUBLISH_AGENT_REMINDER

@@ -434,7 +434,7 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION).

 ## MaxScreenWantAgent

-提醒到达时自动拉起的目标ability信息。
+全屏显示提醒到达时自动拉起的目标ability信息，该接口预留。

 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent