未验证 提交 c2f0d634 编写于 作者: O openharmony_ci 提交者: Gitee

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

Merge pull request !7976 from lyj/master
......@@ -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窗口不再能看到订阅触发的日志。
## 相关实例
......
......@@ -4,7 +4,7 @@ HiAppEvent提供了应用事件打点接口,为应用提供事件打点的功
## 基本概念
HiAppEvent模块支持应用事件业务的开发,提供应用事件相关的功能,主要包括应用事件落盘、查询历史应用事件数据等功能。
HiAppEvent模块支持应用事件业务的开发,提供应用事件相关的功能,主要包括应用事件落盘、应用事件订阅、应用事件清理等功能。
**打点**:记录由用户操作引起的变化,提供业务数据信息,以供开发、产品、运维分析。
......@@ -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。
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| ------------------------------- | -------- | ---- | ---- | ------------------ |
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册