@ohos.commonEvent (公共事件模块)


@ohos.commonEvent (公共事件模块)

本模块提供了公共事件的能力,包括公共事件的权限列表,发布公共事件,订阅或取消订阅公共事件,获取或修改公共事件结果代码、结果数据等。

说明:

  • 从API Version 9开始,该接口不再维护,推荐使用新接口@ohos.commonEventManager

  • 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

import CommonEvent from '@ohos.commonEvent';
1

Support

系统公共事件是指由系统服务或系统应用发布的事件,订阅这些系统公共事件需要特定的权限。发布或订阅这些事件需要使用如下链接中的枚举定义。

全部系统公共事件枚举定义请参见系统公共事件定义

CommonEvent.publish

publish(event: string, callback: AsyncCallback<void>): void
1

发布公共事件(回调形式)。

系统能力: SystemCapability.Notification.CommonEvent

参数:

参数名 类型 必填 说明
event string 表示要发送的公共事件。
callback AsyncCallback<void> 表示被指定的回调方法。

示例:

//发布公共事件回调
function publishCB(err) {
	if (err.code) {
        console.error(`publish failed, code is ${err.code}`);
    } else {
        console.info("publish");
    }
}

//发布公共事件
CommonEvent.publish("event", publishCB);
1
2
3
4
5
6
7
8
9
10
11

CommonEvent.publish

publish(event: string, options: CommonEventPublishData, callback: AsyncCallback<void>): void
1

以回调的形式发布公共事件。

系统能力: SystemCapability.Notification.CommonEvent

参数:

参数名 类型 必填 说明
event string 表示要发布的公共事件。
options CommonEventPublishData 表示发布公共事件的属性。
callback syncCallback<void> 表示被指定的回调方法。

示例:

//公共事件相关信息
let options = {
	code: 0,			 //公共事件的初始代码
	data: "initial data",//公共事件的初始数据
	isOrdered: true	 //有序公共事件
}

//发布公共事件回调
function publishCB(err) {
	if (err.code) {
        console.error(`publish failed, code is ${err.code}`);
    } else {
        console.info("publish");
    }
}

//发布公共事件
CommonEvent.publish("event", options, publishCB);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

CommonEvent.publishAsUser8+

publishAsUser(event: string, userId: number, callback: AsyncCallback<void>): void
1

以回调的形式向指定用户发布公共事件。

系统能力: SystemCapability.Notification.CommonEvent

系统API:此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
event string 表示要发送的公共事件。
userId number 表示指定向该用户ID发送此公共事件。
callback AsyncCallback<void> 表示被指定的回调方法。

示例:

// 发布公共事件回调
function publishCB(err) {
	if (err.code) {
        console.error(`publishAsUser failed, code is ${err.code}`);
    } else {
        console.info("publishAsUser");
    }
}

// 指定发送的用户
let userId = 100;

// 发布公共事件
CommonEvent.publishAsUser("event", userId, publishCB);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

CommonEvent.publishAsUser8+

publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback<void>): void
1

以回调形式向指定用户发布公共事件并指定发布信息。

系统能力: SystemCapability.Notification.CommonEvent

系统API:此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
event string 表示要发布的公共事件。
userId number 表示指定向该用户ID发送此公共事件。
options CommonEventPublishData 表示发布公共事件的属性。
callback AsyncCallback<void> 表示被指定的回调方法。

示例:

// 公共事件相关信息
let options = {
	code: 0,			 // 公共事件的初始代码
	data: "initial data",// 公共事件的初始数据
}

// 发布公共事件回调
function publishCB(err) {
	if (err.code) {
        console.error(`publishAsUser failed, code is ${err.code}`);
    } else {
        console.info("publishAsUser");
    }
}

// 指定发送的用户
let userId = 100;

// 发布公共事件
CommonEvent.publishAsUser("event", userId, options, publishCB);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

CommonEvent.createSubscriber

createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback<CommonEventSubscriber>): void
1

以回调形式创建订阅者。

系统能力: SystemCapability.Notification.CommonEvent

参数:

参数名 类型 必填 说明
subscribeInfo CommonEventSubscribeInfo 表示订阅信息。
callback AsyncCallback<CommonEventSubscriber> 表示创建订阅者的回调方法。

示例:

let subscriber; // 用于保存创建成功的订阅者对象,后续使用其完成订阅及退订的动作

// 订阅者信息
let subscribeInfo = {
	events: ["event"]
};

// 创建订阅者回调
function createCB(err, commonEventSubscriber) {
    if (err.code) {
        console.error(`createSubscriber failed, code is ${err.code}`);
    } else {
        console.info("createSubscriber");
        subscriber = commonEventSubscriber;
    }
}

// 创建订阅者
CommonEvent.createSubscriber(subscribeInfo, createCB);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

CommonEvent.createSubscriber

createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise<CommonEventSubscriber>
1

以Promise形式创建订阅者。

系统能力: SystemCapability.Notification.CommonEvent

参数:

参数名 类型 必填 说明
subscribeInfo CommonEventSubscribeInfo 表示订阅信息。

返回值:

类型 说明
Promise<CommonEventSubscriber> 返回订阅者对象。

示例:

let subscriber; // 用于保存创建成功的订阅者对象,后续使用其完成订阅及退订的动作

// 订阅者信息
let subscribeInfo = {
	events: ["event"]
};

// 创建订阅者
CommonEvent.createSubscriber(subscribeInfo).then((commonEventSubscriber) => {
    console.info("createSubscriber");
    subscriber = commonEventSubscriber;
}).catch((err) => {
    console.error(`createSubscriber failed, code is ${err.code}`);
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14

CommonEvent.subscribe

subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback<CommonEventData>): void
1

以回调形式订阅公共事件。

系统能力: SystemCapability.Notification.CommonEvent

参数:

参数名 类型 必填 说明
subscriber CommonEventSubscriber 表示订阅者对象。
callback AsyncCallback<CommonEventData> 表示接收公共事件数据的回调函数。

示例:

let subscriber; // 用于保存创建成功的订阅者对象,后续使用其完成订阅及退订的动作

// 订阅者信息
let subscribeInfo = {
    events: ["event"]
};

// 订阅公共事件回调
function subscribeCB(err, data) {
    if (err.code) {
        console.error(`subscribe failed, code is ${err.code}`);
    } else {
        console.info("subscribe " + JSON.stringify(data));
    }
}

// 创建订阅者回调
function createCB(err, commonEventSubscriber) {
    if (err.code) {
        console.error(`createSubscriber failed, code is ${err.code}`);
    } else {
        console.info("createSubscriber");
        subscriber = commonEventSubscriber;
        // 订阅公共事件
        CommonEvent.subscribe(subscriber, subscribeCB);
    }
}

// 创建订阅者
CommonEvent.createSubscriber(subscribeInfo, createCB);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

CommonEvent.unsubscribe

unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback<void>): void
1

以回调形式取消订阅公共事件。

系统能力: SystemCapability.Notification.CommonEvent

参数:

参数名 类型 必填 说明
subscriber CommonEventSubscriber 表示订阅者对象。
callback AsyncCallback<void> 表示取消订阅的回调方法。

示例:

let subscriber;	// 用于保存创建成功的订阅者对象,后续使用其完成订阅及退订的动作

// 订阅者信息
let subscribeInfo = {
	events: ["event"]
};

// 订阅公共事件回调
function subscribeCB(err, data) {
    if (err.code) {
        console.error(`subscribe failed, code is ${err.code}`);
    } else {
        console.info("subscribe " + JSON.stringify(data));
    }
}

// 创建订阅者回调
function createCB(err, commonEventSubscriber) {
    if (err.code) {
        console.error(`createSubscriber failed, code is ${err.code}`);
    } else {
        console.info("createSubscriber");
        subscriber = commonEventSubscriber;
        // 订阅公共事件
        CommonEvent.subscribe(subscriber, subscribeCB);
    }
}

// 取消订阅公共事件回调
function unsubscribeCB(err) {
	if (err.code) {
        console.error(`unsubscribe failed, code is ${err.code}`);
    } else {
        console.info("unsubscribe");
    }
}

// 创建订阅者
CommonEvent.createSubscriber(subscribeInfo, createCB);

// 取消订阅公共事件
CommonEvent.unsubscribe(subscriber, unsubscribeCB);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42