!8982 提醒代理文档修改

Merge pull request !8982 from 廖康康/OpenHarmony-3.2-Beta2

!8982 提醒代理文档修改
Merge pull request !8982 from 廖康康/OpenHarmony-3.2-Beta2
ccc084b2 · openharmony_ci · Gitee · 46d29c1d · a681ec2a · ccc084b2
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,8 +66,97 @@ interface LocalDateTime：时间信息实例
   }
   ```

-2. 发布提醒
-   ```
+   日历实例定义：
+
+    ```js
+    // JS工程写法：
+    // calendar: {
+    // eTS工程写法：
+    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
+    }
+    ```
+
+    闹钟实例定义：
+
+    ```js
+    // JS工程写法：
+    // alarm: {
+    // eTS工程写法：
+    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. 发布倒计时提醒。
+   ```js
   startTimer() {
       reminderAgent.publishReminder(this.timer, (err, reminderId) =>{
           this.printInfo(JSON.stringify(err));
@@ -182,102 +166,12 @@ interface LocalDateTime：时间信息实例
   ```

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

-日历实例定义：
-
-```
-// JS工程写法：
-// calendar: {
-// eTS工程写法：
-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
-}
-```
-
-闹钟实例定义：
-
-```
-// JS工程写法：
-// alarm: {
-// eTS工程写法：
-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
-}
-```
-
-
 ## 相关实例

 基于后台代理提醒开发，有以下相关实例可供参考：

--- 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