1# @ohos.commonEvent (公共事件模块)
2
3本模块提供了公共事件的能力，包括公共事件的权限列表，发布公共事件，订阅或取消订阅公共事件，获取或修改公共事件结果代码、结果数据等。
4
5> **说明：**
6> - 从API Version 9开始，该接口不再维护，推荐使用新接口[@ohos.commonEventManager](js-apis-commonEventManager.md)。
7>
8> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
9
10## 导入模块
11
12```ts
13import commonEvent from '@ohos.commonEvent';
14```
15
16## Support
17
18系统公共事件是指由系统服务或系统应用发布的事件，订阅这些系统公共事件需要特定的权限。发布或订阅这些事件需要使用如下链接中的枚举定义。
19
20全部系统公共事件枚举定义请参见[系统公共事件定义](./common_event/commonEvent-definitions.md)。
21
22## commonEvent.publish<sup>(deprecated)</sup>
23
24publish(event: string, callback: AsyncCallback\<void>): void
25
26发布公共事件（回调形式）。
27
28> **说明：**
29> 从 API version 7开始支持，从API version 9开始废弃。建议使用[commonEventManager.publish](js-apis-commonEventManager.md#commoneventmanagerpublish)替代。
30
31**系统能力：** `SystemCapability.Notification.CommonEvent`
32
33**参数：**
34
35| 参数名     | 类型                 | 必填 | 说明                   |
36| -------- | -------------------- | ---- | ---------------------- |
37| event    | string               | 是   | 表示要发送的公共事件。 |
38| callback | AsyncCallback\<void> | 是   | 表示被指定的回调方法。 |
39
40**示例：**
41
42```ts
43import Base from '@ohos.base';
44
45//发布公共事件回调
46function publishCB(err:Base.BusinessError) {
47	if (err.code) {
48        console.error(`publish failed, code is ${err.code}`);
49    } else {
50        console.info("publish");
51    }
52}
53
54//发布公共事件
55commonEvent.publish("event", publishCB);
56```
57
58## commonEvent.publish<sup>(deprecated)</sup>
59
60publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\<void>): void
61
62以回调的形式发布公共事件。
63
64> **说明：**
65> 从 API version 7开始支持，从API version 9开始废弃。建议使用[commonEventManager.publish](js-apis-commonEventManager.md#commoneventmanagerpublish-1)替代。
66
67**系统能力：** `SystemCapability.Notification.CommonEvent`
68
69**参数：**
70
71| 参数名     | 类型                   | 必填 | 说明                   |
72| -------- | ---------------------- | ---- | ---------------------- |
73| event    | string                 | 是   | 表示要发布的公共事件。  |
74| options  | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是   | 表示发布公共事件的属性。 |
75| callback | AsyncCallback\<void>   | 是   | 表示被指定的回调方法。  |
76
77**示例：**
78
79
80```ts
81import Base from '@ohos.base';
82import CommonEventManager from '@ohos.commonEventManager';
83
84//公共事件相关信息
85let options:CommonEventManager.CommonEventPublishData = {
86	code: 0,			 //公共事件的初始代码
87	data: "initial data",//公共事件的初始数据
88	isOrdered: true	 //有序公共事件
89}
90
91//发布公共事件回调
92function publishCB(err:Base.BusinessError) {
93	if (err.code) {
94        console.error(`publish failed, code is ${err.code}`);
95    } else {
96        console.info("publish");
97    }
98}
99
100//发布公共事件
101commonEvent.publish("event", options, publishCB);
102```
103
104## commonEvent.createSubscriber<sup>(deprecated)</sup>
105
106createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void
107
108以回调形式创建订阅者。
109
110> **说明：**
111>从 API version 7开始支持，从API version 9开始废弃。建议使用[commonEventManager.createSubscriber](js-apis-commonEventManager.md#commoneventmanagercreatesubscriber)替代。
112
113**系统能力：** `SystemCapability.Notification.CommonEvent`
114
115**参数：**
116
117| 参数名          | 类型                                                         | 必填 | 说明                       |
118| ------------- | ------------------------------------------------------------ | ---- | -------------------------- |
119| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)        | 是   | 表示订阅信息。             |
120| callback      | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 是   | 表示创建订阅者的回调方法。 |
121
122**示例：**
123
124
125```ts
126import Base from '@ohos.base';
127import CommonEventManager from '@ohos.commonEventManager';
128
129let subscriber:CommonEventManager.CommonEventSubscriber; // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
130
131// 订阅者信息
132let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
133    events: ["event"]
134};
135
136// 创建订阅者回调
137function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
138    if (err.code) {
139        console.error(`createSubscriber failed, code is ${err.code}`);
140    } else {
141        console.info("createSubscriber");
142        subscriber = commonEventSubscriber;
143    }
144}
145
146// 创建订阅者
147commonEvent.createSubscriber(subscribeInfo, createCB);
148```
149
150## commonEvent.createSubscriber<sup>(deprecated)</sup>
151
152createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber>
153
154以Promise形式创建订阅者。
155
156> **说明：**
157>从 API version 7开始支持，从API version 9开始废弃。建议使用[commonEventManager.createSubscriber](js-apis-commonEventManager.md#commoneventmanagercreatesubscriber-1)替代。
158
159**系统能力：** `SystemCapability.Notification.CommonEvent`
160
161**参数：**
162
163| 参数名          | 类型                                                  | 必填 | 说明           |
164| ------------- | ----------------------------------------------------- | ---- | -------------- |
165| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 是   | 表示订阅信息。 |
166
167**返回值：**
168| 类型                                                      | 说明             |
169| --------------------------------------------------------- | ---------------- |
170| Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 返回订阅者对象。 |
171
172**示例：**
173
174```ts
175import Base from '@ohos.base';
176import CommonEventManager from '@ohos.commonEventManager';
177
178let subscriber:CommonEventManager.CommonEventSubscriber; // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
179
180// 订阅者信息
181let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
182    events: ["event"]
183};
184
185// 创建订阅者
186commonEvent.createSubscriber(subscribeInfo).then((commonEventSubscriber:CommonEventManager.CommonEventSubscriber) => {
187    console.info("createSubscriber");
188    subscriber = commonEventSubscriber;
189}).catch((err:Base.BusinessError) => {
190    console.error(`createSubscriber failed, code is ${err.code}`);
191});
192```
193
194## commonEvent.subscribe<sup>(deprecated)</sup>
195
196subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\<CommonEventData>): void
197
198以回调形式订阅公共事件。
199
200> **说明：**
201>从 API version 7开始支持，从API version 9开始废弃。建议使用[commonEventManager.subscribe](js-apis-commonEventManager.md#commoneventmanagersubscribe)替代。
202
203**系统能力：** `SystemCapability.Notification.CommonEvent`
204
205**参数：**
206
207| 参数名       | 类型                                                | 必填 | 说明                             |
208| ---------- | ---------------------------------------------------- | ---- | -------------------------------- |
209| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)     | 是   | 表示订阅者对象。                 |
210| callback   | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | 是   | 表示接收公共事件数据的回调函数。 |
211
212**示例：**
213
214```ts
215import Base from '@ohos.base';
216import CommonEventManager from '@ohos.commonEventManager';
217
218let subscriber:CommonEventManager.CommonEventSubscriber;// 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
219
220// 订阅者信息
221let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
222    events: ["event"]
223};
224
225// 订阅公共事件回调
226function subscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) {
227    if (err.code) {
228        console.error(`subscribe failed, code is ${err.code}`);
229    } else {
230        console.info("subscribe " + JSON.stringify(data));
231    }
232}
233
234// 创建订阅者回调
235function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
236    if (err.code) {
237        console.error(`createSubscriber failed, code is ${err.code}`);
238    } else {
239        console.info("createSubscriber");
240        subscriber = commonEventSubscriber;
241        // Subscribe to a common event.
242        commonEvent.subscribe(subscriber, subscribeCB);
243    }
244}
245
246// 创建订阅者
247commonEvent.createSubscriber(subscribeInfo, createCB);
248```
249
250## commonEvent.unsubscribe<sup>(deprecated)</sup>
251
252unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void
253
254以回调形式取消订阅公共事件。
255
256> **说明：**
257>从 API version 7开始支持，从API version 9开始废弃。建议使用[commonEventManager.subscribe](js-apis-commonEventManager.md#commoneventmanagerunsubscribe)替代。
258
259**系统能力：** `SystemCapability.Notification.CommonEvent`
260
261**参数：**
262
263| 参数名       | 类型                                             | 必填 | 说明                     |
264| ---------- | ----------------------------------------------- | ---- | ------------------------ |
265| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 是   | 表示订阅者对象。         |
266| callback   | AsyncCallback\<void>                            | 否   | 表示取消订阅的回调方法。 |
267
268**示例：**
269
270```ts
271import Base from '@ohos.base';
272import CommonEventManager from '@ohos.commonEventManager';
273
274let subscriber:CommonEventManager.CommonEventSubscriber;	// 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
275
276// 订阅者信息
277let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
278    events: ["event"]
279};
280
281// 订阅公共事件回调
282function subscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) {
283    if (err.code) {
284        console.error(`subscribe failed, code is ${err.code}`);
285    } else {
286        console.info("subscribe " + JSON.stringify(data));
287    }
288}
289
290// 创建订阅者回调
291function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
292    if (err.code) {
293        console.error(`createSubscriber failed, code is ${err.code}`);
294    } else {
295        console.info("createSubscriber");
296        subscriber = commonEventSubscriber;
297        // Subscribe to a common event.
298        commonEvent.subscribe(subscriber, subscribeCB);
299    }
300}
301
302// 取消订阅公共事件回调
303function unsubscribeCB(err:Base.BusinessError) {
304    if (err.code) {
305        console.error(`unsubscribe failed, code is ${err.code}`);
306    } else {
307        console.info("unsubscribe");
308    }
309}
310
311// 创建订阅者
312commonEvent.createSubscriber(subscribeInfo, createCB);
313
314// 取消订阅公共事件
315commonEvent.unsubscribe(subscriber, unsubscribeCB);
316```