From 3aa7b6f657a138d7facd10f84cfe648b33b24dfc Mon Sep 17 00:00:00 2001 From: lyj_love_code Date: Wed, 10 Aug 2022 16:31:45 +0800 Subject: [PATCH] update hiappevent api doc Signed-off-by: lyj_love_code --- .../dfx/hiappevent-guidelines.md | 178 ++++++--- .../dfx/hiappevent-overview.md | 2 +- .../reference/apis/js-apis-hiappevent.md | 370 +++++++++++++++++- 3 files changed, 472 insertions(+), 78 deletions(-) diff --git a/zh-cn/application-dev/dfx/hiappevent-guidelines.md b/zh-cn/application-dev/dfx/hiappevent-guidelines.md index e38e964549..23de727ff9 100644 --- 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\ callback): void | void | 应用事件异步打点方法，使用callback方式作为异步回调。 | -| write(string eventName, EventType type, object keyValues): Promise\ | Promise\ | 应用事件异步打点方法，使用promise方式作为异步回调。 | +| 接口名 | 描述 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| write(string eventName, EventType type, object keyValues, AsyncCallback\ callback): void | 应用事件异步打点方法，使用callback方式作为异步回调。 | +| write(string eventName, EventType type, object keyValues): Promise\ | 应用事件异步打点方法，使用Promise方式作为异步回调。 | +| write(AppEventInfo info, AsyncCallback\ callback): void | 支持domain参数的应用事件异步打点方法，使用callback方式作为异步回调。 | +| write(AppEventInfo info): Promise\ | 支持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个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。 | 忽略该事件，不执行打点。 | -| -2 | 无效的事件基本参数类型 | 事件名称参数必须为string。
事件类型参数必须为number类型。
keyValues参数必须为object类型。 | 忽略该事件，不执行打点。 | -| -99 | 应用打点功能被关闭 | 应用打点功能被关闭。 | 忽略该事件，不执行打点。 | -| -100 | 未知错误 | 无。 | 忽略该事件，不执行打点。 | -| 1 | 无效的key参数名称 | 非空且长度在16个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。
非下划线结尾。 | 忽略该键值对参数后，继续执行打点。 | -| 2 | 无效的key参数类型 | Key参数必须为字符串类型。 | 忽略该键值对参数后，继续执行打点。 | -| 3 | 无效的value参数类型 | value参数只支持以下类型：
boolean、number、string、Array[基本类型]。
| 忽略该键值对参数后，继续执行打点。 | -| 4 | value参数值过长 | 参数值长度必须在8*1024个字符以内（含）。 | 忽略该键值对参数后，继续执行打点。 | -| 5 | key-value参数对数过多 | key-value参数对数必须在32对以内（含）。 | 忽略后面多余的键值对参数后，继续执行打点。 | -| 6 | List类型的value参数容量过大 | List类型的value参数容量必须在100个以内（含）。 | 对List进行截断（只保留前100个元素）后，继续执行打点。 | -| 7 | 无效的List类型value参数 | List的泛型类型只能为基本类型。
List内的参数必须为同一类型。 | 忽略该键值对参数后，继续执行打点。 | +| 错误码 | 原因 | 校验规则 | 处理结果 | +| ------ | ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | +| 0 | 无 | 事件校验成功 | 事件正常打点。 | +| -1 | 无效的事件名称 | 非空且长度在48个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。 | 忽略该事件，不执行打点。 | +| -2 | 无效的事件基本参数类型 | 事件名称参数必须为string。
事件类型参数必须为number类型。
事件参数必须为object类型。 | 忽略该事件，不执行打点。 | +| -4 | 无效的事件领域名称 | 非空且长度在32个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。 | 忽略该事件，不执行打点。 | +| -99 | 应用打点功能被关闭 | 应用打点功能被关闭。 | 忽略该事件，不执行打点。 | +| -100 | 未知错误 | 无。 | 忽略该事件，不执行打点。 | +| 1 | 无效的key参数名称 | 非空且长度在16个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。
非下划线结尾。 | 忽略该键值对参数后，继续执行打点。 | +| 2 | 无效的key参数类型 | Key参数必须为字符串类型。 | 忽略该键值对参数后，继续执行打点。 | +| 3 | 无效的value参数类型 | value参数只支持以下类型：
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窗口不再能看到订阅触发的日志。 ## 相关实例 diff --git a/zh-cn/application-dev/dfx/hiappevent-overview.md b/zh-cn/application-dev/dfx/hiappevent-overview.md index d2b993f0a1..49d4a3baf1 100644 --- 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模块支持应用事件业务的开发，提供应用事件相关的功能，主要包括应用事件落盘、应用事件订阅、应用事件清理等功能。 **打点**：记录由用户操作引起的变化，提供业务数据信息，以供开发、产品、运维分析。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md b/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md index ac3c6a8390..9e36191871 100644 --- 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(deprecated) write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void -应用事件打点方法，将事件写入到当天的事件文件中，可接收类型为Json对象的事件参数，使用callback方式作为异步回调。 +> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9)替代。 + +应用事件打点方法，将事件写入到当天的事件文件中，使用callback方式作为异步回调。 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------------------------- | ---- | ------------------------------------------------------------ | -| eventName | string | 是 | 应用事件名称。
由开发者自定义。事件名称在48个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头。 | -| eventType | [EventType](#eventtype) | 是 | 应用事件类型。 | -| keyValues | object | 是 | 事件参数键值对，如果是变长参数类型，则依次输入事件的参数名与参数值。如果是Json对象类型，则Json对象的key是事件的参数名，value是事件的参数值。
- key类型只能为string，value类型只能为string、number、boolean、Array（数组数据类型只能为string、number、boolean）。
- 事件的参数个数必须小于等于32。
- 参数名在16个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头，不能以下划线结尾。
- string类型参数值在8*1024个字符内。
- Array类型参数值的元素个数必须在100个以内，超出时会进行截断处理。 | -| callback | AsyncCallback<void> | 否 | 回调函数，可以在回调函数中处理接口返回值。
- 返回值为0表示事件校验成功，事件正常异步写入事件文件；
- 大于0表示事件校验存在异常参数，在忽略异常参数后将事件异步写入事件文件；
- 小于0表示事件校验失败，不将事件写入事件文件。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | -------------- | +| eventName | string | 是 | 事件名称。 | +| eventType | [EventType](#eventtype) | 是 | 事件类型。 | +| keyValues | object | 是 | 事件参数。 | +| callback | AsyncCallback<void> | 否 | 事件回调函数。 | **示例：** @@ -46,27 +89,29 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str ``` -## hiAppEvent.write +## hiAppEvent.write(deprecated) write(eventName: string, eventType: EventType, keyValues: object): Promise<void> -应用事件打点方法，将事件写入到当天的事件文件中，可接收类型为Json对象的事件参数，使用promise方式作为异步回调。 +> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9-1)替代。 + +应用事件打点方法，将事件写入到当天的事件文件中，使用Promise方式作为异步回调。 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ----------------------- | ---- | ------------------------------------------------------------ | -| eventName | string | 是 | 应用事件名称。
由开发者自定义。事件名称在48个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头。 | -| eventType | [EventType](#eventtype) | 是 | 应用事件类型。 | -| keyValues | object | 是 | 事件参数键值对，如果是变长参数类型，则依次输入事件的参数名与参数值。如果是Json对象类型，则Json对象的key是事件的参数名，value是事件的参数值。
- key类型只能为string，value类型只能为string、number、boolean、Array（数组数据类型只能为string、number、boolean）。
- 事件的参数个数必须小于等于32。
- 参数名在16个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头，不能以下划线结尾。
- string类型参数值在8*1024个字符内。
- Array类型参数值的元素个数必须在100个以内，超出时会进行截断处理。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | ---------- | +| eventName | string | 是 | 事件名称。 | +| eventType | [EventType](#eventtype) | 是 | 事件类型。 | +| keyValues | object | 是 | 事件参数。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------------------------------------------ | -| Promise<void> | Promise实例，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行回调处理。 | +| Promise<void> | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 | **示例：** @@ -81,6 +126,96 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str }); ``` +## hiAppEvent.write9+ + +write(info: [AppEventInfo](#appeventinfo9), callback: AsyncCallback<void>): void + +应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用callback方式作为异步回调。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo9) | 是 | 应用事件对象。 | +| callback | AsyncCallback<void> | 否 | 事件回调函数。 | + +**示例：** + +```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.write9+ + +write(info: [AppEventInfo](#appeventinfo9)): Promise<void> + +应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用Promise方式作为异步回调。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo9) | 是 | 应用事件对象。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------------------------------------------------------ | +| Promise<void> | 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}`); +}); +``` + +## AppEventInfo9+ + +此接口提供了应用事件信息的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。 + +| 名称 | 参数类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | ---------- | +| domain | string | 是 | 事件领域。 | +| name | string | 是 | 事件名称。 | +| eventType | [EventType](#eventtype) | 是 | 事件类型。 | +| params | object | 是 | 事件参数。 | ## hiAppEvent.configure @@ -103,6 +238,7 @@ configure(config: ConfigOption): boolean | boolean | 配置结果，true 表示配置成功，false 表示配置失败。 | **示例：** + ```js // 配置应用事件打点功能开关 hiAppEvent.configure({ @@ -115,24 +251,216 @@ hiAppEvent.configure({ }); ``` - ## ConfigOption 此接口提供了应用打点的配置选项。 -**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。 +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。 | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------- | ---- | ------------------------------------------------------------ | | disable | boolean | 否 | 应用打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 | | maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 | +## hiAppEvent.addWatcher9+ + +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.removeWatcher9+ + +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); +``` + +## Watcher9+ + +此接口提供了应用事件订阅者的参数选项。 + +**系统能力：**SystemCapability.HiviewDFX.HiAppEvent。 + +| 名称 | 参数类型 | 必填 | 说明 | +| ---------------- | ------------------------------------------------------------ | ---- | -------------------------------- | +| name | string | 是 | 订阅者名称，用于唯一标识订阅者。 | +| triggerCondition | [TriggerCondition](#triggercondition9) | 否 | 订阅回调触发条件。 | +| appEventFilters | [AppEventFilter](#appeventfilter9)[] | 否 | 订阅过滤条件。 | +| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder9)) => void | 否 | 订阅回调函数 。 | + +## TriggerCondition9+ + +此接口提供了订阅者回调触发条件的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。 + +| 名称 | 参数类型 | 必填 | 说明 | +| ------- | -------- | ---- | -------------------------------------- | +| row | number | 否 | 满足触发回调的事件总数。 | +| size | number | 否 | 满足触发回调的事件总大小，单位为byte。 | +| timeOut | number | 否 | 满足触发回调的定时时长，单位为30s。 | + +## AppEventFilter9+ + +此接口提供了订阅者过滤应用事件的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。 + +| 名称 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | ------------------------ | +| domain | string | 是 | 需要订阅的事件领域。 | +| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | + +## AppEventPackageHolder9+ + +订阅数据持有者类，用于对订阅事件进行处理。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。 + +### setSize9+ + +setSize(size: number): void + +设置每次取出的应用事件包的数据大小阈值，单位为byte，默认值为512*1024。 + +**示例：** + +```js +holder.setSize(1000); +``` + +### takeNext9+ + +takeNext(): [AppEventPackage](#appeventpackage9) + +根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 + +**示例：** + +```js +let eventPkg = holder.takeNext(); +``` + +## AppEventPackage9+ + +此接口提供了订阅返回的应用事件包的参数定义。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent。 + +| 名称 | 参数类型 | 说明 | +| --------- | -------- | ------------------------------ | +| packageId | number | 事件包ID，从0开始自动递增。 | +| row | number | 事件包的事件数量。 | +| size | number | 事件包的数据大小，单位为byte。 | +| data | string[] | 事件包的事件信息。 | + +## hiAppEvent.clearData9+ + +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。 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | ------------------------------- | -------- | ---- | ---- | ------------------ | -- GitLab