!7976 新增HiAppEvent订阅API的文档说明

Merge pull request !7976 from lyj/master

!7976 新增HiAppEvent订阅API的文档说明
Merge pull request !7976 from lyj/master
c2f0d634 · openharmony_ci · Gitee · 350ebfae · 3aa7b6f6 · c2f0d634
3 changed file
--- a/zh-cn/application-dev/dfx/hiappevent-guidelines.md
+++ b/zh-cn/application-dev/dfx/hiappevent-guidelines.md
@@ -12,85 +12,151 @@

 **打点接口功能介绍：**

-| 接口名                                                       | 返回值         | 描述                                                 |
-| ------------------------------------------------------------ | -------------- | ---------------------------------------------------- |
-| write(string eventName, EventType type, object keyValues, AsyncCallback\<void> callback): void | void           | 应用事件异步打点方法，使用callback方式作为异步回调。 |
-| write(string eventName, EventType type, object keyValues): Promise\<void> | Promise\<void> | 应用事件异步打点方法，使用promise方式作为异步回调。  |
+| 接口名                                                       | 描述                                                         |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| write(string eventName, EventType type, object keyValues, AsyncCallback\<void> callback): void | 应用事件异步打点方法，使用callback方式作为异步回调。         |
+| write(string eventName, EventType type, object keyValues): Promise\<void> | 应用事件异步打点方法，使用Promise方式作为异步回调。          |
+| write(AppEventInfo info, AsyncCallback\<void> callback): void | 支持domain参数的应用事件异步打点方法，使用callback方式作为异步回调。 |
+| write(AppEventInfo info): Promise\<void>                     | 支持domain参数的应用事件异步打点方法，使用Promise方式作为异步回调。 |

-当采用callback作为异步回调时，可以在callback中进行下一步处理。当采用Promise对象返回时，可以在Promise对象中类似地处理接口返回值。具体结果码说明见[事件校验结果码](#事件校验结果码)。
+当采用callback作为异步回调时，可以在callback中进行下一步处理。

+当采用Promise对象返回时，也可以在Promise对象中类似地处理接口返回值。
+
+具体结果码说明见[事件校验结果码](#事件校验结果码)。

 **打点配置接口功能介绍：**

-| 接口名                         | 返回值  | 描述                                                         |
-| ------------------------------ | ------- | ------------------------------------------------------------ |
-| configure(ConfigOption config) | boolean | 应用事件打点配置方法，可以对打点功能进行自定义配置。返回true表示配置成功，false表示配置失败。 |
+| 接口名                                  | 描述                                                 |
+| --------------------------------------- | ---------------------------------------------------- |
+| configure(ConfigOption config): boolean | 应用事件打点配置方法，可以对打点功能进行自定义配置。 |
+
+**订阅接口功能介绍：**
+
+| 接口名                                             | 描述                 |
+| -------------------------------------------------- | -------------------- |
+| addWatcher(Watcher watcher): AppEventPackageHolder | 新增应用事件订阅者。 |
+| removeWatcher(Watcher watcher): void               | 移除应用事件订阅者。 |

+**清理接口功能介绍：**
+
+| 接口名            | 描述                 |
+| ----------------- | -------------------- |
+| clearData(): void | 清除本地的打点数据。 |

 ### 事件校验结果码

-| 错误码 | 原因                        | 校验规则                                                     | 处理结果                                              |
-| ------ | --------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
-| 0      | 无                          | 事件校验成功                                                 | 事件正常打点。                                        |
-| -1     | 无效的事件名称              | 非空且长度在48个字符以内（含）。<br>只由以下字符组成：0-9、a-z、_。<br/>非数字以及下划线开头。 | 忽略该事件，不执行打点。                              |
-| -2     | 无效的事件基本参数类型      | 事件名称参数必须为string。<br/>事件类型参数必须为number类型。<br/>keyValues参数必须为object类型。 | 忽略该事件，不执行打点。                              |
-| -99    | 应用打点功能被关闭          | 应用打点功能被关闭。                                         | 忽略该事件，不执行打点。                              |
-| -100   | 未知错误                    | 无。                                                         | 忽略该事件，不执行打点。                              |
-| 1      | 无效的key参数名称           | 非空且长度在16个字符以内（含）。<br/>只由以下字符组成：0-9、a-z、_。<br/>非数字以及下划线开头。<br/>非下划线结尾。 | 忽略该键值对参数后，继续执行打点。                    |
-| 2      | 无效的key参数类型           | Key参数必须为字符串类型。                                    | 忽略该键值对参数后，继续执行打点。                    |
-| 3      | 无效的value参数类型         | value参数只支持以下类型：<br/>boolean、number、string、Array[基本类型]。<br/> | 忽略该键值对参数后，继续执行打点。                    |
-| 4      | value参数值过长             | 参数值长度必须在8*1024个字符以内（含）。                     | 忽略该键值对参数后，继续执行打点。                    |
-| 5      | key-value参数对数过多       | key-value参数对数必须在32对以内（含）。                      | 忽略后面多余的键值对参数后，继续执行打点。            |
-| 6      | List类型的value参数容量过大 | List类型的value参数容量必须在100个以内（含）。               | 对List进行截断（只保留前100个元素）后，继续执行打点。 |
-| 7      | 无效的List类型value参数     | List的泛型类型只能为基本类型。<br/>List内的参数必须为同一类型。 | 忽略该键值对参数后，继续执行打点。                    |
+| 错误码 | 原因                          | 校验规则                                                     | 处理结果                                                   |
+| ------ | ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
+| 0      | 无                            | 事件校验成功                                                 | 事件正常打点。                                             |
+| -1     | 无效的事件名称                | 非空且长度在48个字符以内（含）。<br>只由以下字符组成：0-9、a-z、_。<br/>非数字以及下划线开头。 | 忽略该事件，不执行打点。                                   |
+| -2     | 无效的事件基本参数类型        | 事件名称参数必须为string。<br/>事件类型参数必须为number类型。<br/>事件参数必须为object类型。 | 忽略该事件，不执行打点。                                   |
+| -4     | 无效的事件领域名称            | 非空且长度在32个字符以内（含）。<br/>只由以下字符组成：0-9、a-z、_。<br/>非数字以及下划线开头。 | 忽略该事件，不执行打点。                                   |
+| -99    | 应用打点功能被关闭            | 应用打点功能被关闭。                                         | 忽略该事件，不执行打点。                                   |
+| -100   | 未知错误                      | 无。                                                         | 忽略该事件，不执行打点。                                   |
+| 1      | 无效的key参数名称             | 非空且长度在16个字符以内（含）。<br/>只由以下字符组成：0-9、a-z、_。<br/>非数字以及下划线开头。<br/>非下划线结尾。 | 忽略该键值对参数后，继续执行打点。                         |
+| 2      | 无效的key参数类型             | Key参数必须为字符串类型。                                    | 忽略该键值对参数后，继续执行打点。                         |
+| 3      | 无效的value参数类型           | value参数只支持以下类型：<br/>boolean、number、string、Array[基本类型]。 | 忽略该键值对参数后，继续执行打点。                         |
+| 4      | 非法长度的string类型value参数 | 参数值长度必须在8*1024个字符以内（含）。                     | 对字符串进行截断（只保留前8*1024个字符）后，继续执行打点。 |
+| 5      | key-value参数对数过多         | key-value参数对数必须在32对以内（含）。                      | 忽略后面多余的键值对参数后，继续执行打点。                 |
+| 6      | 非法容量的Array类型value参数  | Array类型的value参数容量必须在100个以内（含）。              | 对数组进行截断（只保留前100个元素）后，继续执行打点。      |
+| 7      | 非法类型的Array类型value参数  | Array内的参数必须为同一类型，且只能为boolean、number、string类型。 | 忽略该键值对参数后，继续执行打点。                         |

 ## 开发步骤

-在应用启动执行页面加载后，执行一个应用事件打点，用于记录应用的初始页面加载事件。
+以一次应用事件打点订阅流程为例，说明开发步骤。

-1. 新建一个JS应用工程，在“Project”窗口点击“entry > src > main > js > default > pages > index”，打开工程中的“index.js”文件，在页面执行加载后，执行一个应用事件打点，用于记录应用的初始页面加载事件，示例代码如下：
+1. 新建一个ets应用工程，编辑工程中的“entry > src > main > ets  > pages > index.ets” 文件，依次添加三个按钮，以对应用事件打点订阅流程进行模拟。其中，按钮1模拟了应用事件打点的调用，按钮2模拟了新增自动触发回调的事件订阅者的调用，按钮3模拟了移除事件订阅者的调用，完整示例代码如下：

-   ```js
-   import hiAppEvent from '@ohos.hiAppEvent'
+   ```ts
+   import hiAppEvent from '@ohos.hiAppEvent';
   
-   export default {
-       data: {
-           title: ""
-       },
-       onInit() {
-           this.title = this.$t('strings.world');
+   @Entry
+   @Component
+   struct Index {
+     @State message: string = 'Hello World'
   
-           // 1.callback方式
-           hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"}, (err, value) => {
-               if (err) {
-                   console.error(`failed to write event because ${err.code}`);
-                   return;
-               }
-               console.log(`success to write event: ${value}`);
-           });
+     build() {
+       Row() {
+         Column() {
+           Text(this.message)
+             .fontSize(50)
+             .fontWeight(FontWeight.Bold)
   
-           // 2.Promise方式
-           hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"})
-               .then((value) => {
-                   console.log(`success to write event: ${value}`);
-               }).catch((err) => {
-                   console.error(`failed to write event because ${err.code}`);
-               });
+           Button("1 writeTest").onClick(()=>{
+             hiAppEvent.write({
+               domain: "test_domain",
+               name: "test_event",
+               eventType: hiAppEvent.EventType.FAULT,
+               params: {
+                 int_data: 100,
+                 str_data: "strValue"
+               }
+             }).then((value) => {
+               console.log(`HiAppEvent success to write event: ${value}`);
+             }).catch((err) => {
+               console.error(`HiAppEvent failed to write event because ${err.code}`);
+             });
+           })
   
-           // 3.配置应用打点开关
-           hiAppEvent.configure({
-               disable: true
-           });
+           Button("2 addWatcherTest").onClick(()=>{
+             hiAppEvent.addWatcher({
+               name: "watcher1",
+               appEventFilters: [{ domain: "test_domain" }],
+               triggerCondition: {
+                 row: 2,
+                 size: 1000,
+                 timeOut: 2
+               },
+               onTrigger: function (curRow, curSize, holder) {
+                 if (holder == null) {
+                   console.error("HiAppEvent holder is null");
+                   return;
+                 }
+                 let eventPkg = null;
+                 while ((eventPkg = holder.takeNext()) != null) {
+                   console.info("HiAppEvent eventPkg.packageId=" + eventPkg.packageId);
+                   console.info("HiAppEvent eventPkg.row=" + eventPkg.row);
+                   console.info("HiAppEvent eventPkg.size=" + eventPkg.size);
+                   for (const eventInfo of eventPkg.data) {
+                     console.info("HiAppEvent eventPkg.data=" + eventInfo);
+                   }
+                 }
+               }
+             });
+           })
   
-           // 4.配置事件文件目录限额（默认为10M）
-           hiAppEvent.configure({
-               maxStorage: '100M'
-           });
+           Button("3 removeWatcherTest").onClick(()=>{
+             hiAppEvent.removeWatcher({
+               name: "watcher1"
+             })
+           })
+         }
+         .width('100%')
       }
+       .height('100%')
+     }
   }
   ```

-2. 运行项目，点击应用界面上的运行按钮。
+2. 点击IDE界面中的运行按钮，运行应用工程。
+
+3. 在应用界面点击按钮1进行一次事件打点，可以在Log窗口看到打点成功的日志：
+
+   ```
+   success to write event: 0
+   ```
+
+4. 在应用界面点击按钮2进行新增事件订阅者，再多次点击按钮1进行多次打点。在满足回调任一触发条件（事件数量、事件数据大小、定时时长）后，可以在Log窗口看到回调函数触发后获取到的订阅事件包的日志：
+
+   ```
+   HiAppEvent eventPkg.packageId=0
+   HiAppEvent eventPkg.row=2
+   HiAppEvent eventPkg.size=308
+   HiAppEvent eventPkg.data={"domain_":"test_domain","name_":"test_event","type_":1,"time_":1502096107556,"tz_":"+0000","pid_":4204,"tid_":4223,"int_data":100,"str_data":"strValue"}
+   ```
+
+5. 在应用界面点击按钮3进行移除事件订阅者，再多次点击按钮1进行多次打点，此时在Log窗口不再能看到订阅触发的日志。

 ## 相关实例


--- a/zh-cn/application-dev/dfx/hiappevent-overview.md
+++ b/zh-cn/application-dev/dfx/hiappevent-overview.md
@@ -4,7 +4,7 @@ HiAppEvent提供了应用事件打点接口，为应用提供事件打点的功

 ## 基本概念

-HiAppEvent模块支持应用事件业务的开发，提供应用事件相关的功能，主要包括应用事件落盘、查询历史应用事件数据等功能。
+HiAppEvent模块支持应用事件业务的开发，提供应用事件相关的功能，主要包括应用事件落盘、应用事件订阅、应用事件清理等功能。

 **打点**：记录由用户操作引起的变化，提供业务数据信息，以供开发、产品、运维分析。

--- a/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md
@@ -12,23 +12,66 @@
 import hiAppEvent from '@ohos.hiAppEvent';
 ```

+## 使用说明

-## hiAppEvent.write
+开发者在使用应用事件打点功能前，需要首先了解应用事件相关的参数规格定义。
+
+**事件领域**
+
+事件领域为string类型，字符串非空且长度在32个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头。
+
+**事件名称**
+
+事件名称为string类型，字符串非空且长度在48个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头。
+
+**事件类型**
+
+事件类型为[EventType](#eventtype)枚举类型。
+
+**事件参数**
+
+事件参数为object类型，key为事件的参数名称，value为事件的参数值，其规格定义如下：
+
+- 参数名为string类型，字符串非空且长度在16个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头或结尾。
+- 参数值支持string、number、boolean、Array类型；
+- 参数值为string类型时，其长度需在8*1024个字符以内，超出会做截断处理；
+- 参数值为Array类型时，Array中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理；
+- 参数个数需在32以内，超出的参数会做丢弃处理。
+
+**事件回调**
+
+开发者在调用事件打点方法后，可以在回调函数中对打点返回值进行处理，当前支持callback形式和Promise形式的回调，其返回值规格定义如下：
+
+- 返回值为0，表示事件校验成功，将事件直接落盘到事件文件；
+- 返回值大于0，表示事件校验存在异常参数，在忽略异常参数后将事件落盘到事件文件；
+- 返回值小于0，表示事件校验失败，不将事件落盘到事件文件。
+
+**订阅回调**
+
+开发者在调用事件订阅方法后，可以在订阅回调函数中对订阅数据进行处理，其入参定义如下：
+
+- curRow：返回的订阅事件数量；
+- curSize：返回的订阅事件数据大小，单位为byte；
+- holder：返回的订阅事件数据持有者，可以通过其对订阅事件进行处理。
+
+## hiAppEvent.write<sup>(deprecated)</sup>

 write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback&lt;void&gt;): void

-应用事件打点方法，将事件写入到当天的事件文件中，可接收类型为Json对象的事件参数，使用callback方式作为异步回调。
+> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9)替代。
+
+应用事件打点方法，将事件写入到当天的事件文件中，使用callback方式作为异步回调。

 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent

 **参数：**

-| 参数名    | 类型                      | 必填 | 说明                                                         |
-| --------- | ------------------------- | ---- | ------------------------------------------------------------ |
-| eventName | string                    | 是   | 应用事件名称。<br/>由开发者自定义。事件名称在48个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头。 |
-| eventType | [EventType](#eventtype)   | 是   | 应用事件类型。                                               |
-| keyValues | object                    | 是   | 事件参数键值对，如果是变长参数类型，则依次输入事件的参数名与参数值。如果是Json对象类型，则Json对象的key是事件的参数名，value是事件的参数值。<br/>- key类型只能为string，value类型只能为string、number、boolean、Array（数组数据类型只能为string、number、boolean）。<br/>- 事件的参数个数必须小于等于32。<br/>- 参数名在16个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头，不能以下划线结尾。<br/>- string类型参数值在8*1024个字符内。<br/>- Array类型参数值的元素个数必须在100个以内，超出时会进行截断处理。 |
-| callback  | AsyncCallback&lt;void&gt; | 否   | 回调函数，可以在回调函数中处理接口返回值。<br/>-&nbsp;返回值为0表示事件校验成功，事件正常异步写入事件文件；<br/>-&nbsp;大于0表示事件校验存在异常参数，在忽略异常参数后将事件异步写入事件文件；<br/>-&nbsp;小于0表示事件校验失败，不将事件写入事件文件。 |
+| 参数名    | 类型                      | 必填 | 说明           |
+| --------- | ------------------------- | ---- | -------------- |
+| eventName | string                    | 是   | 事件名称。     |
+| eventType | [EventType](#eventtype)   | 是   | 事件类型。     |
+| keyValues | object                    | 是   | 事件参数。     |
+| callback  | AsyncCallback&lt;void&gt; | 否   | 事件回调函数。 |

 **示例：**

@@ -46,27 +89,29 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str
 ```


-## hiAppEvent.write
+## hiAppEvent.write<sup>(deprecated)</sup>

 write(eventName: string, eventType: EventType, keyValues: object): Promise&lt;void&gt;

-应用事件打点方法，将事件写入到当天的事件文件中，可接收类型为Json对象的事件参数，使用promise方式作为异步回调。
+> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9-1)替代。
+
+应用事件打点方法，将事件写入到当天的事件文件中，使用Promise方式作为异步回调。

 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent

 **参数：**

-| 参数名    | 类型                    | 必填 | 说明                                                         |
-| --------- | ----------------------- | ---- | ------------------------------------------------------------ |
-| eventName | string                  | 是   | 应用事件名称。<br/>由开发者自定义。事件名称在48个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头。 |
-| eventType | [EventType](#eventtype) | 是   | 应用事件类型。                                               |
-| keyValues | object                  | 是   | 事件参数键值对，如果是变长参数类型，则依次输入事件的参数名与参数值。如果是Json对象类型，则Json对象的key是事件的参数名，value是事件的参数值。<br/>- key类型只能为string，value类型只能为string、number、boolean、Array（数组数据类型只能为string、number、boolean）。<br/>- 事件的参数个数必须小于等于32。<br/>- 参数名在16个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头，不能以下划线结尾。<br/>- string类型参数值在8*1024个字符内。<br/>- Array类型参数值的元素个数必须在100个以内，超出时会进行截断处理。 |
+| 参数名    | 类型                    | 必填 | 说明       |
+| --------- | ----------------------- | ---- | ---------- |
+| eventName | string                  | 是   | 事件名称。 |
+| eventType | [EventType](#eventtype) | 是   | 事件类型。 |
+| keyValues | object                  | 是   | 事件参数。 |

 **返回值：**

 | 类型                | 说明                                                         |
 | ------------------- | ------------------------------------------------------------ |
-| Promise&lt;void&gt; | Promise实例，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行回调处理。 |
+| Promise&lt;void&gt; | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 |

 **示例：**

@@ -81,6 +126,96 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str
    });
 ```

+## hiAppEvent.write<sup>9+</sup>
+
+write(info: [AppEventInfo](#appeventinfo9), callback: AsyncCallback&lt;void&gt;): void
+
+应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用callback方式作为异步回调。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
+
+**参数：**
+
+| 参数名   | 类型                           | 必填 | 说明           |
+| -------- | ------------------------------ | ---- | -------------- |
+| info     | [AppEventInfo](#appeventinfo9) | 是   | 应用事件对象。 |
+| callback | AsyncCallback&lt;void&gt;      | 否   | 事件回调函数。 |
+
+**示例：**
+
+```js
+hiAppEvent.write({
+    domain: "test_domain",
+    name: "test_event",
+    eventType: hiAppEvent.EventType.FAULT,
+    params: {
+        int_data: 100,
+        str_data: "strValue"
+    }
+}, (err, value) => {
+    if (err) {
+        // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入
+        console.error(`failed to write event because ${err.code}`);
+        return;
+    }
+
+    // 事件写入正常
+    console.log(`success to write event: ${value}`);
+});
+```
+
+## hiAppEvent.write<sup>9+</sup>
+
+write(info: [AppEventInfo](#appeventinfo9)): Promise&lt;void&gt;
+
+应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用Promise方式作为异步回调。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
+
+**参数：**
+
+| 参数名 | 类型                           | 必填 | 说明           |
+| ------ | ------------------------------ | ---- | -------------- |
+| info   | [AppEventInfo](#appeventinfo9) | 是   | 应用事件对象。 |
+
+**返回值：**
+
+| 类型                | 说明                                                         |
+| ------------------- | ------------------------------------------------------------ |
+| Promise&lt;void&gt; | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 |
+
+**示例：**
+
+```js
+hiAppEvent.write({
+    domain: "test_domain",
+    name: "test_event",
+    eventType: hiAppEvent.EventType.FAULT,
+    params: {
+        int_data: 100,
+        str_data: "strValue"
+    }
+}).then((value) => {
+    // 事件写入正常
+    console.log(`success to write event: ${value}`);
+}).catch((err) => {
+    // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入
+    console.error(`failed to write event because ${err.code}`);
+});
+```
+
+## AppEventInfo<sup>9+</sup>
+
+此接口提供了应用事件信息的参数选项。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。
+
+| 名称      | 参数类型                | 必填 | 说明       |
+| --------- | ----------------------- | ---- | ---------- |
+| domain    | string                  | 是   | 事件领域。 |
+| name      | string                  | 是   | 事件名称。 |
+| eventType | [EventType](#eventtype) | 是   | 事件类型。 |
+| params    | object                  | 是   | 事件参数。 |

 ## hiAppEvent.configure

@@ -103,6 +238,7 @@ configure(config: ConfigOption): boolean
 | boolean | 配置结果，true&nbsp;表示配置成功，false&nbsp;表示配置失败。 |

 **示例：**
+
 ```js
 // 配置应用事件打点功能开关
 hiAppEvent.configure({
@@ -115,24 +251,216 @@ hiAppEvent.configure({
 });
 ```

-
 ## ConfigOption

 此接口提供了应用打点的配置选项。

-**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。

 | 参数名     | 类型    | 必填 | 说明                                                         |
 | ---------- | ------- | ---- | ------------------------------------------------------------ |
 | disable    | boolean | 否   | 应用打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 |
 | maxStorage | string  | 否   | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 |

+## hiAppEvent.addWatcher<sup>9+</sup>
+
+addWatcher(watcher: [Watcher](#watcher9)): [AppEventPackageHolder](#appeventpackageholder9)
+
+新增应用事件订阅者。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
+
+**参数：**
+
+| 参数名  | 类型                 | 必填 | 说明             |
+| ------- | -------------------- | ---- | ---------------- |
+| watcher | [Watcher](#watcher9) | 是   | 应用事件订阅者。 |
+
+**返回值：**
+
+| 类型                                             | 说明                                 |
+| ------------------------------------------------ | ------------------------------------ |
+| [AppEventPackageHolder](#appeventpackageholder9) | 订阅数据持有者，订阅失败时返回null。 |
+
+**示例：**
+
+```js
+// 1. 如果订阅者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理
+hiAppEvent.addWatcher({
+    name: "watcher1",
+    appEventFilters: [
+        {
+            domain: "domain_test1",
+            eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
+        }
+    ],
+    triggerCondition: {
+        row: 10,
+        size: 1000,
+        timeOut: 1
+    },
+    onTrigger: function (curRow, curSize, holder) {
+        if (holder == null) {
+            console.error("holder is null");
+            return;
+        }
+        while (true) {
+            let eventPkg = holder.takeNext();
+            if (eventPkg == null) {
+                return;
+            }
+            console.info("eventPkg.packageId=" + eventPkg.packageId);
+            console.info("eventPkg.row=" + eventPkg.row);
+            console.info("eventPkg.size=" + eventPkg.size);
+            console.info("eventPkg.data=" + eventPkg.data);
+        }
+    }
+});
+
+// 2. 如果订阅者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件
+let holder = hiAppEvent.addWatcher({
+    name: "watcher2",
+});
+if (holder != null) {
+    let eventPkg = holder.takeNext();
+    if (eventPkg == null) {
+        return;
+    }
+    console.info("eventPkg.packageId=" + eventPkg.packageId);
+    console.info("eventPkg.row=" + eventPkg.row);
+    console.info("eventPkg.size=" + eventPkg.size);
+    console.info("eventPkg.data=" + eventPkg.data);
+}
+```
+
+## hiAppEvent.removeWatcher<sup>9+</sup>
+
+removeWatcher(watcher: [Watcher](#watcher9)): void
+
+移除应用事件订阅者。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
+
+**参数：**
+
+| 参数名  | 类型                 | 必填 | 说明             |
+| ------- | -------------------- | ---- | ---------------- |
+| watcher | [Watcher](#watcher9) | 是   | 应用事件订阅者。 |
+
+**示例：**
+
+```js
+// 1. 定义一个应用事件订阅者
+let watcher = {
+    name: "watcher1",
+}
+
+// 2. 开始订阅事件
+hiAppEvent.addWatcher(watcher);
+
+// 3. 取消订阅事件
+hiAppEvent.removeWatcher(watcher);
+```
+
+## Watcher<sup>9+</sup>
+
+此接口提供了应用事件订阅者的参数选项。
+
+**系统能力：**SystemCapability.HiviewDFX.HiAppEvent。
+
+| 名称             | 参数类型                                                     | 必填 | 说明                             |
+| ---------------- | ------------------------------------------------------------ | ---- | -------------------------------- |
+| name             | string                                                       | 是   | 订阅者名称，用于唯一标识订阅者。 |
+| triggerCondition | [TriggerCondition](#triggercondition9)                       | 否   | 订阅回调触发条件。               |
+| appEventFilters  | [AppEventFilter](#appeventfilter9)[]                         | 否   | 订阅过滤条件。                   |
+| onTrigger        | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder9)) => void | 否   | 订阅回调函数 。                  |
+
+## TriggerCondition<sup>9+</sup>
+
+此接口提供了订阅者回调触发条件的参数选项。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。
+
+| 名称    | 参数类型 | 必填 | 说明                                   |
+| ------- | -------- | ---- | -------------------------------------- |
+| row     | number   | 否   | 满足触发回调的事件总数。               |
+| size    | number   | 否   | 满足触发回调的事件总大小，单位为byte。 |
+| timeOut | number   | 否   | 满足触发回调的定时时长，单位为30s。    |
+
+## AppEventFilter<sup>9+</sup>
+
+此接口提供了订阅者过滤应用事件的参数选项。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。
+
+| 名称       | 参数类型                  | 必填 | 说明                     |
+| ---------- | ------------------------- | ---- | ------------------------ |
+| domain     | string                    | 是   | 需要订阅的事件领域。     |
+| eventTypes | [EventType](#eventtype)[] | 否   | 需要订阅的事件类型集合。 |
+
+## AppEventPackageHolder<sup>9+</sup>
+
+订阅数据持有者类，用于对订阅事件进行处理。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。
+
+### setSize<sup>9+</sup>
+
+setSize(size: number): void
+
+设置每次取出的应用事件包的数据大小阈值，单位为byte，默认值为512*1024。
+
+**示例：**
+
+```js
+holder.setSize(1000);
+```
+
+### takeNext<sup>9+</sup>
+
+takeNext(): [AppEventPackage](#appeventpackage9)
+
+根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。
+
+**示例：**
+
+```js
+let eventPkg = holder.takeNext();
+```
+
+## AppEventPackage<sup>9+</sup>
+
+此接口提供了订阅返回的应用事件包的参数定义。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。
+
+| 名称      | 参数类型 | 说明                           |
+| --------- | -------- | ------------------------------ |
+| packageId | number   | 事件包ID，从0开始自动递增。    |
+| row       | number   | 事件包的事件数量。             |
+| size      | number   | 事件包的数据大小，单位为byte。 |
+| data      | string[] | 事件包的事件信息。             |
+
+## hiAppEvent.clearData<sup>9+</sup>
+
+clearData(): void
+
+应用打点数据清理方法，将应用存储在本地的打点数据进行清除。
+
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
+
+**示例：**
+
+```js
+hiAppEvent.clearData();
+```
+

 ## EventType

 事件类型枚举。

-**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。

 | 名称      | 默认值 | 说明           |
 | --------- | ------ | -------------- |
@@ -146,7 +474,7 @@ hiAppEvent.configure({

 此接口提供了所有预定义事件的事件名称常量。

-**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。

 | 名称                      | 参数类型 | 可读 | 可写 | 说明                 |
 | ------------------------- | -------- | ---- | ---- | -------------------- |
@@ -159,7 +487,7 @@ hiAppEvent.configure({

 此接口提供了所有预定义参数的参数名称常量。

-**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。
+**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。

 | 名称                            | 参数类型 | 可读 | 可写 | 说明               |
 | ------------------------------- | -------- | ---- | ---- | ------------------ |