!9990 hiappevent-guidelines.md补充代码注释

Merge pull request !9990 from lyj/master

zh-cn/application-dev/dfx/hiappevent-guidelines.md

@@ -12,12 +12,10 @@
 
 **打点接口功能介绍：**
 
-| 接口名                                                       | 描述                                                         |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| 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方式作为异步回调。 |
+| 接口名                                                       | 描述                                                 |
+| ------------------------------------------------------------ | ---------------------------------------------------- |
+| write(AppEventInfo info, AsyncCallback\<void> callback): void | 应用事件异步打点方法，使用callback方式作为异步回调。 |
+| write(AppEventInfo info): Promise\<void>                     | 应用事件异步打点方法，使用Promise方式作为异步回调。  |
 
 当采用callback作为异步回调时，可以在callback中进行下一步处理。
 
@@ -35,7 +33,7 @@
 
 | 接口名                                             | 描述                 |
 | -------------------------------------------------- | -------------------- |
-| addWatcher(Watcher watcher): AppEventPackageHolder | 新增应用事件订阅者。 |
+| addWatcher(Watcher watcher): AppEventPackageHolder | 添加应用事件订阅者。 |
 | removeWatcher(Watcher watcher): void               | 移除应用事件订阅者。 |
 
 **清理接口功能介绍：**
@@ -66,7 +64,7 @@
 
 以一次应用事件打点订阅流程为例，说明开发步骤。
 
-1. 新建一个ets应用工程，编辑工程中的“entry > src > main > ets  > pages > index.ets” 文件，依次添加三个按钮，以对应用事件打点订阅流程进行模拟。其中，按钮1模拟了应用事件打点的调用，按钮2模拟了新增自动触发回调的事件订阅者的调用，按钮3模拟了移除事件订阅者的调用，完整示例代码如下：
+1. 新建一个ets应用工程，编辑工程中的“entry > src > main > ets  > pages > index.ets” 文件，依次添加三个按钮，以对应用事件打点订阅流程进行模拟。其中，按钮1模拟了应用事件打点的调用，按钮2模拟了添加自动触发回调的事件订阅者的调用，按钮3模拟了移除事件订阅者的调用，完整示例代码如下：
 
    ```ts
    import hiAppEvent from '@ohos.hiAppEvent';
@@ -84,6 +82,7 @@
              .fontWeight(FontWeight.Bold)
    
            Button("1 writeTest").onClick(()=>{
+             // 根据传入的事件参数执行一次应用事件打点
              hiAppEvent.write({
                domain: "test_domain",
                name: "test_event",
@@ -100,6 +99,7 @@
            })
    
            Button("2 addWatcherTest").onClick(()=>{
+             // 根据传入的订阅参数添加一个应用事件订阅者
              hiAppEvent.addWatcher({
                name: "watcher1",
                appEventFilters: [{ domain: "test_domain" }],
@@ -109,17 +109,23 @@
                  timeOut: 2
                },
                onTrigger: function (curRow, curSize, holder) {
+                 // 返回的holder对象为null表示订阅过程发生异常，因此在记录错误日志后直接返回
                  if (holder == null) {
                    console.error("HiAppEvent holder is null");
                    return;
                  }
+                 // 设置每次获取的订阅事件包大小阈值为1000字节
+                 holder.setSize(1000);
                  let eventPkg = null;
+                 // 根据设置阈值大小去获取订阅事件包（返回的事件包对象为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);
+                   // 对获取的订阅事件包进行解析，并将解析结果打印在Log界面
+                   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);
+                     console.info('HiAppEvent eventPkg.data=' + eventInfo);
                    }
                  }
                }
@@ -127,6 +133,7 @@
            })
    
            Button("3 removeWatcherTest").onClick(()=>{
+             // 移除指定名称的应用事件订阅者
              hiAppEvent.removeWatcher({
                name: "watcher1"
              })
@@ -147,7 +154,7 @@
    success to write event: 0
    ```
 
-4. 在应用界面点击按钮2进行新增事件订阅者，再多次点击按钮1进行多次打点。在满足回调任一触发条件（事件数量、事件数据大小、定时时长）后，可以在Log窗口看到回调函数触发后获取到的订阅事件包的日志：
+4. 在应用界面点击按钮2进行添加事件订阅者，再多次点击按钮1进行多次打点。在满足回调任一触发条件（事件数量、事件数据大小、定时时长）后，可以在Log窗口看到回调函数触发后获取到的订阅事件包的日志：
 
    ```
    HiAppEvent eventPkg.packageId=0