1# 订阅应用事件（ArkTS）
2
3HiAppEvent提供了事件订阅接口，用于本地获取应用事件。
4
5## 接口说明
6
7API接口的具体使用说明（参数使用限制、具体取值范围等）请参考[应用事件打点API文档](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md)。
8
9**打点接口功能介绍：**
10
11| 接口名                                              | 描述                                         |
12| --------------------------------------------------- | -------------------------------------------- |
13| write(info: AppEventInfo, callback: AsyncCallback\<void>): void | 应用事件异步打点方法，使用callback方式作为异步回调。 |
14| write(info: AppEventInfo): Promise\<void>               | 应用事件异步打点方法，使用Promise方式作为异步回调。 |
15
16**订阅接口功能介绍：**
17
18| 接口名                                              | 描述                                         |
19| --------------------------------------------------- | -------------------------------------------- |
20| addWatcher(watcher: Watcher): AppEventPackageHolder | 添加应用事件观察者，以添加对应用事件的订阅。 |
21| removeWatcher(watcher: Watcher): void               | 移除应用事件观察者，以移除对应用事件的订阅。 |
22
23## 开发步骤
24
25以实现对用户点击按钮行为的事件打点及订阅为例，说明开发步骤。
26
271. 新建一个ArkTS应用工程，编辑工程中的“entry > src > main > ets  > entryability > EntryAbility.ets”文件，导入依赖模块：
28
29   ```ts
30   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
31   ```
32
332. 编辑工程中的“entry > src > main > ets  > entryability > EntryAbility.ets” 文件，在onCreate函数中添加对用户点击按钮事件的订阅，示例代码如下：
34
35   ```ts
36    hiAppEvent.addWatcher({
37      // 开发者可以自定义观察者名称，系统会使用名称来标识不同的观察者
38      name: "watcher1",
39      // 开发者可以订阅感兴趣的应用事件，此处是订阅了按钮事件
40      appEventFilters: [{ domain: "button" }],
41      // 开发者可以设置订阅回调触发的条件，此处是设置为事件打点数量满足1个
42      triggerCondition: { row: 1 },
43      // 开发者可以自行实现订阅回调函数，以便对订阅获取到的事件打点数据进行自定义处理
44      onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => {
45        // 返回的holder对象为null，表示订阅过程发生异常，因此在记录错误日志后直接返回
46        if (holder == null) {
47          hilog.error(0x0000, 'testTag', "HiAppEvent holder is null");
48          return;
49        }
50        hilog.info(0x0000, 'testTag', `HiAppEvent onTrigger: curRow=%{public}d, curSize=%{public}d`, curRow, curSize);
51        let eventPkg: hiAppEvent.AppEventPackage | null = null;
52        // 根据设置阈值大小（默认为512KB）去获取订阅事件包，直到将订阅数据全部取出
53        // 返回的事件包对象为null，表示当前订阅数据已被全部取出，此次订阅回调触发结束
54        while ((eventPkg = holder.takeNext()) != null) {
55          // 开发者可以对事件包中的事件打点数据进行自定义处理，此处是将事件打点数据打印在日志中
56          hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.packageId=%{public}d`, eventPkg.packageId);
57          hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.row=%{public}d`, eventPkg.row);
58          hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.size=%{public}d`, eventPkg.size);
59          for (const eventInfo of eventPkg.data) {
60            hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.info=%{public}s`, eventInfo);
61          }
62        }
63      }
64    });
65
663. 编辑工程中的“entry > src > main > ets  > pages > Index.ets” 文件，导入依赖模块：
67
68   ```ts
69   import { BusinessError } from '@kit.BasicServicesKit';
70   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
71   ```
72
734. 编辑工程中的“entry > src > main > ets  > pages > Index.ets” 文件，添加一个按钮并在其onClick函数中进行事件打点，以记录按钮点击事件，示例代码如下：
74
75   ```ts
76     Button("writeTest").onClick(()=>{
77       // 在按钮点击函数中进行事件打点，以记录按钮点击事件
78       let eventParams: Record<string, number> = { 'click_time': 100 };
79       let eventInfo: hiAppEvent.AppEventInfo = {
80         // 事件领域定义
81         domain: "button",
82         // 事件名称定义
83         name: "click",
84         // 事件类型定义
85         eventType: hiAppEvent.EventType.BEHAVIOR,
86         // 事件参数定义
87         params: eventParams,
88       };
89       hiAppEvent.write(eventInfo).then(() => {
90         hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`)
91       }).catch((err: BusinessError) => {
92         hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`)
93       });
94     })
95   ```
96
975. 点击DevEco Studio界面中的运行按钮，运行应用工程，然后在应用界面中点击按钮“writeTest”，触发一次按钮点击事件打点。
98
996. 可以在Log窗口看到按钮点击事件打点成功的日志，以及触发订阅回调后对打点事件数据的处理日志：
100
101   ```text
102   HiAppEvent success to write event
103   HiAppEvent eventPkg.packageId=0
104   HiAppEvent eventPkg.row=1
105   HiAppEvent eventPkg.size=124
106   HiAppEvent eventPkg.info={"domain_":"button","name_":"click","type_":4,"time_":1670268234523,"tz_":"+0800","pid_":3295,"tid_":3309,"click_time":100}
107   ```
108