1# @ohos.commonEvent (公共事件模块)(系统应用)
2
3本模块提供了公共事件的能力，包括公共事件的权限列表，发布公共事件，订阅或取消订阅公共事件，获取或修改公共事件结果代码、结果数据等。
4
5> **说明：**
6> 从API Version 9开始，该接口不再维护，推荐使用新接口[@ohos.commonEventManager](js-apis-commonEventManager.md)。
7>
8> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
9>
10> 当前界面仅包含本模块的系统接口，其他公开接口参见[CommonEvent](./js-apis-commonEvent.md)。
11
12## 导入模块
13
14```ts
15import commonEvent from '@ohos.commonEvent';
16```
17
18## Support
19
20系统公共事件是指由系统服务或系统应用发布的事件，订阅这些系统公共事件需要特定的权限。发布或订阅这些事件需要使用如下链接中的枚举定义。
21
22全部系统公共事件枚举定义请参见[系统公共事件定义](./common_event/commonEvent-definitions.md)。
23
24## commonEvent.publishAsUser<sup>(deprecated)</sup>
25
26publishAsUser(event: string, userId: number, callback: AsyncCallback\<void>): void
27
28以回调的形式向指定用户发布公共事件。
29
30> **说明：**
31> 从 API version 8开始支持，从API version 9开始废弃。建议使用[commonEventManager.publishAsUser](js-apis-commonEventManager-sys.md#commoneventmanagerpublishasuser)替代。
32
33**系统能力：** `SystemCapability.Notification.CommonEvent`
34
35**系统API**：此接口为系统接口，三方应用不支持调用。
36
37**参数：**
38
39| 参数名     | 类型                 | 必填 | 说明                               |
40| -------- | -------------------- | ---- | ---------------------------------- |
41| event    | string               | 是   | 表示要发送的公共事件。             |
42| userId   | number               | 是   | 表示指定向该用户ID发送此公共事件。 |
43| callback | AsyncCallback\<void> | 是   | 表示被指定的回调方法。             |
44
45**示例：**
46
47```ts
48import Base from '@ohos.base';
49
50// 发布公共事件回调
51function publishCB(err:Base.BusinessError) {
52	if (err.code) {
53        console.error(`publishAsUser failed, code is ${err.code}`);
54    } else {
55        console.info("publishAsUser");
56    }
57}
58
59// 指定发送的用户
60let userId = 100;
61
62// 发布公共事件
63commonEvent.publishAsUser("event", userId, publishCB);
64```
65
66## commonEvent.publishAsUser<sup>(deprecated)</sup>
67
68publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback\<void>): void
69
70以回调形式向指定用户发布公共事件并指定发布信息。
71
72> **说明：**
73> 从 API version 8开始支持，从API version 9开始废弃。建议使用[commonEventManager.publishAsUser](js-apis-commonEventManager-sys.md#commoneventmanagerpublishasuser-1)替代。
74
75**系统能力：** `SystemCapability.Notification.CommonEvent`
76
77**系统API**：此接口为系统接口，三方应用不支持调用。
78
79**参数：**
80
81| 参数名     | 类型                   | 必填 | 说明                   |
82| -------- | ---------------------- | ---- | ---------------------- |
83| event    | string                 | 是   | 表示要发布的公共事件。  |
84| userId   | number | 是 | 表示指定向该用户ID发送此公共事件。 |
85| options  | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是   | 表示发布公共事件的属性。 |
86| callback | AsyncCallback\<void>   | 是   | 表示被指定的回调方法。  |
87
88**示例：**
89
90
91```ts
92import Base from '@ohos.base';
93import CommonEventManager from '@ohos.commonEventManager';
94
95// 公共事件相关信息
96let options:CommonEventManager.CommonEventPublishData = {
97	code: 0,			 // 公共事件的初始代码
98	data: "initial data",// 公共事件的初始数据
99}
100
101// 发布公共事件回调
102function publishCB(err:Base.BusinessError) {
103    if (err.code) {
104        console.error(`publishAsUser failed, code is ${err.code}`);
105    } else {
106        console.info("publishAsUser");
107    }
108}
109
110// 指定发送的用户
111let userId = 100;
112
113// 发布公共事件
114commonEvent.publishAsUser("event", userId, options, publishCB);
115```
116
117
118unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void
119
120以回调形式取消订阅公共事件。
121
122> **说明：**
123>从 API version 7开始支持，从API version 9开始废弃。建议使用[commonEventManager.subscribe](js-apis-commonEventManager.md#commoneventmanagerunsubscribe)替代。
124
125**系统能力：** `SystemCapability.Notification.CommonEvent`
126
127**参数：**
128
129| 参数名       | 类型                                             | 必填 | 说明                     |
130| ---------- | ----------------------------------------------- | ---- | ------------------------ |
131| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 是   | 表示订阅者对象。         |
132| callback   | AsyncCallback\<void>                            | 否   | 表示取消订阅的回调方法。 |
133
134**示例：**
135
136```ts
137import Base from '@ohos.base';
138import CommonEventManager from '@ohos.commonEventManager';
139
140let subscriber:CommonEventManager.CommonEventSubscriber;	// 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
141
142// 订阅者信息
143let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
144    events: ["event"]
145};
146
147// 订阅公共事件回调
148function subscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) {
149    if (err.code) {
150        console.error(`subscribe failed, code is ${err.code}`);
151    } else {
152        console.info("subscribe " + JSON.stringify(data));
153    }
154}
155
156// 创建订阅者回调
157function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
158    if (err.code) {
159        console.error(`createSubscriber failed, code is ${err.code}`);
160    } else {
161        console.info("createSubscriber");
162        subscriber = commonEventSubscriber;
163        // Subscribe to a common event.
164        commonEvent.subscribe(subscriber, subscribeCB);
165    }
166}
167
168// 取消订阅公共事件回调
169function unsubscribeCB(err:Base.BusinessError) {
170    if (err.code) {
171        console.error(`unsubscribe failed, code is ${err.code}`);
172    } else {
173        console.info("unsubscribe");
174    }
175}
176
177// 创建订阅者
178commonEvent.createSubscriber(subscribeInfo, createCB);
179
180// 取消订阅公共事件
181commonEvent.unsubscribe(subscriber, unsubscribeCB);
182```