1# @ohos.commonEventManager (公共事件模块)
2
3本模块提供了公共事件相关的能力，包括发布公共事件、订阅公共事件、以及退订公共事件。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { commonEventManager } from '@kit.BasicServicesKit';
13```
14
15## Support
16
17系统公共事件是指由系统服务或系统应用发布的事件，订阅这些公共事件需要特定的权限、使用相应的值，详见[系统定义的公共事件](./common_event/commonEventManager-definitions.md)。
18
19## commonEventManager.publish
20
21publish(event: string, callback: AsyncCallback\<void>): void
22
23发布公共事件。使用callback异步回调。
24
25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
26
27**系统能力：** SystemCapability.Notification.CommonEvent
28
29**参数：**
30
31| 参数名     | 类型                 | 必填 | 说明                   |
32| -------- | -------------------- | ---- | ---------------------- |
33| event    | string               | 是   | 表示要发送的公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 |
34| callback | AsyncCallback\<void> | 是   | 表示事件发布后将要执行的回调函数。 |
35
36**错误码：**
37
38以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
39
40| 错误码ID | 错误信息                            |
41| -------- | ----------------------------------- |
42| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.      |
43| 1500004  | A third-party application cannot send system common events.                |
44| 1500007  | Failed to send the message to the common event service. |
45| 1500008  | Failed to initialize the common event service. |
46| 1500009  | Failed to obtain system parameters.  |
47
48**示例：**
49
50```ts
51import { BusinessError } from '@kit.BasicServicesKit';
52
53// 发布公共事件回调
54function publishCB(err: BusinessError) {
55  if (err) {
56    console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
57  } else {
58    console.info("publish success");
59  }
60}
61// 发布公共事件
62try {
63  commonEventManager.publish("event", publishCB);
64} catch (error) {
65  let err: BusinessError = error as BusinessError;
66  console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
67}
68```
69
70## commonEventManager.publish
71
72publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\<void>): void
73
74发布公共事件。使用callback异步回调。
75
76**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
77
78**系统能力：** SystemCapability.Notification.CommonEvent
79
80**参数：**
81
82| 参数名     | 类型                   | 必填 | 说明                   |
83| -------- | ---------------------- | ---- | ---------------------- |
84| event    | string                 | 是   | 表示要发布的公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。  |
85| options  | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是   | 表示发布公共事件的属性。 |
86| callback | syncCallback\<void>   | 是   | 表示被指定的回调方法。  |
87
88**错误码：**
89
90以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
91
92| 错误码ID | 错误信息                            |
93| -------- | ----------------------------------- |
94| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.      |
95| 1500004  | A third-party application cannot send system common events.                |
96| 1500007  | Failed to send the message to the common event service. |
97| 1500008  | Failed to initialize the common event service. |
98| 1500009  | Failed to obtain system parameters.  |
99
100**示例：**
101
102```ts
103import { BusinessError } from '@kit.BasicServicesKit';
104
105// 公共事件相关信息
106let options:commonEventManager.CommonEventPublishData = {
107  code: 0,			 // 公共事件的初始代码
108  data: "initial data",// 公共事件的初始数据
109  isOrdered: true	 // 有序公共事件
110}
111// 发布公共事件回调
112function publishCB(err: BusinessError) {
113  if (err) {
114    console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
115  } else {
116    console.info("publish success");
117  }
118}
119// 发布公共事件
120try {
121  commonEventManager.publish("event", options, publishCB);
122} catch (error) {
123  let err: BusinessError = error as BusinessError;
124  console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
125}
126```
127
128## commonEventManager.createSubscriber
129
130createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void
131
132创建订阅者。使用callback异步回调。
133
134**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
135
136**系统能力：** SystemCapability.Notification.CommonEvent
137
138**参数：**
139
140| 参数名          | 类型                                                         | 必填 | 说明                       |
141| ------------- | ------------------------------------------------------------ | ---- | -------------------------- |
142| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)        | 是   | 表示订阅信息。             |
143| callback      | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 是   | 表示创建订阅者的回调方法。 |
144
145**错误码：**
146
147以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
148
149| 错误码ID | 错误信息                            |
150| -------- | ----------------------------------- |
151| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.      |
152
153**示例：**
154
155```ts
156import { BusinessError } from '@kit.BasicServicesKit';
157
158// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
159let subscriber:commonEventManager.CommonEventSubscriber;
160// 订阅者信息
161let subscribeInfo:commonEventManager.CommonEventSubscribeInfo = {
162  events: ["event"]
163};
164// 创建订阅者回调
165function createCB(err: BusinessError, commonEventSubscriber:commonEventManager.CommonEventSubscriber) {
166  if(!err) {
167    console.info("createSubscriber success");
168    subscriber = commonEventSubscriber;
169  } else {
170    console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
171  }
172}
173// 创建订阅者
174try {
175  commonEventManager.createSubscriber(subscribeInfo, createCB);
176} catch (error) {
177  let err: BusinessError = error as BusinessError;
178  console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
179}
180```
181
182## commonEventManager.createSubscriber
183
184createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber>
185
186创建订阅者。使用Promise异步回调。
187
188**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
189
190**系统能力：** SystemCapability.Notification.CommonEvent
191
192**参数：**
193
194| 参数名          | 类型                                                  | 必填 | 说明           |
195| ------------- | ----------------------------------------------------- | ---- | -------------- |
196| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 是   | 表示订阅信息。 |
197
198**返回值：**
199| 类型                                                      | 说明             |
200| --------------------------------------------------------- | ---------------- |
201| Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 以Promise形式返回订阅者对象。 |
202
203**错误码：**
204
205以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
206
207| 错误码ID | 错误信息                            |
208| -------- | ----------------------------------- |
209| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.      |
210
211**示例：**
212
213```ts
214import { BusinessError } from '@kit.BasicServicesKit';
215
216// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
217let subscriber:commonEventManager.CommonEventSubscriber;
218// 订阅者信息
219let subscribeInfo:commonEventManager.CommonEventSubscribeInfo = {
220  events: ["event"]
221};
222// 创建订阅者
223commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:commonEventManager.CommonEventSubscriber) => {
224  console.info("createSubscriber success");
225  subscriber = commonEventSubscriber;
226}).catch((err: BusinessError) => {
227  console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
228});
229```
230
231## commonEventManager.createSubscriberSync<sup>10+</sup>
232
233createSubscriberSync(subscribeInfo: CommonEventSubscribeInfo): CommonEventSubscriber
234
235createSubscriber的同步接口。
236
237**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
238
239**系统能力：** SystemCapability.Notification.CommonEvent
240
241**参数：**
242
243| 参数名          | 类型                                                  | 必填 | 说明           |
244| ------------- | ----------------------------------------------------- | ---- | -------------- |
245| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 是   | 表示订阅信息。 |
246
247**返回值：**
248| 类型                                                      | 说明             |
249| --------------------------------------------------------- | ---------------- |
250| [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 返回订阅者对象。 |
251
252**错误码：**
253
254以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
255
256| 错误码ID | 错误信息                            |
257| -------- | ----------------------------------- |
258| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.      |
259
260**示例：**
261
262```ts
263import { BusinessError } from '@kit.BasicServicesKit';
264
265// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
266let subscriber: commonEventManager.CommonEventSubscriber;
267// 订阅者信息
268let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
269  events: ["event"]
270};
271// 创建订阅者
272try {
273  subscriber = commonEventManager.createSubscriberSync(subscribeInfo);
274} catch (error) {
275  let err: BusinessError = error as BusinessError;
276  console.error(`createSubscriberSync failed, code is ${err.code}, message is ${err.message}`);
277}
278```
279
280## commonEventManager.subscribe
281
282subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\<CommonEventData>): void
283
284订阅公共事件。使用callback异步回调。
285
286**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
287
288**系统能力：** SystemCapability.Notification.CommonEvent
289
290**参数：**
291
292| 参数名       | 类型                                                | 必填 | 说明                             |
293| ---------- | ---------------------------------------------------- | ---- | -------------------------------- |
294| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)     | 是   | 表示订阅者对象。                 |
295| callback   | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | 是   | 表示接收公共事件数据的回调函数。 |
296
297**错误码：**
298
299以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
300
301| 错误码ID | 错误信息                            |
302| -------- | ----------------------------------- |
303| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.      |
304| 801  | capability not supported.               |
305| 1500007  | Failed to send the message to the common event service. |
306| 1500008  | Failed to initialize the common event service. |
307
308**示例：**
309
310```ts
311import { BusinessError } from '@kit.BasicServicesKit';
312
313// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
314let subscriber:commonEventManager.CommonEventSubscriber;
315// 订阅者信息
316let subscribeInfo:commonEventManager.CommonEventSubscribeInfo = {
317  events: ["event"]
318};
319// 订阅公共事件回调
320function SubscribeCB(err: BusinessError, data:commonEventManager.CommonEventData) {
321  if (err) {
322    console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
323  } else {
324    console.info("subscribe success, Consume callback " + JSON.stringify(data));
325  }
326}
327// 创建订阅者回调
328function createCB(err: BusinessError, commonEventSubscriber:commonEventManager.CommonEventSubscriber) {
329  if(!err) {
330    console.info("createSubscriber success");
331    subscriber = commonEventSubscriber;
332    // 订阅公共事件
333    try {
334      commonEventManager.subscribe(subscriber, SubscribeCB);
335    } catch (error) {
336      let err: BusinessError = error as BusinessError;
337      console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
338    }
339  } else {
340    console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
341  }
342}
343// 创建订阅者
344try {
345  commonEventManager.createSubscriber(subscribeInfo, createCB);
346} catch (error) {
347  let err: BusinessError = error as BusinessError;
348  console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
349}
350```
351
352## commonEventManager.unsubscribe
353
354unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void
355
356取消订阅公共事件。使用callback异步回调。
357
358**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
359
360**系统能力：** SystemCapability.Notification.CommonEvent
361
362**参数：**
363
364| 参数名       | 类型                                             | 必填 | 说明                     |
365| ---------- | ----------------------------------------------- | ---- | ------------------------ |
366| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 是   | 表示订阅者对象。         |
367| callback   | AsyncCallback\<void>                            | 否   | 表示取消订阅的回调方法。 |
368
369**错误码：**
370
371以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
372
373| 错误码ID | 错误信息                            |
374| -------- | ----------------------------------- |
375| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.      |
376| 801  | capability not supported.               |
377| 1500007  | Failed to send the message to the common event service. |
378| 1500008  | Failed to initialize the common event service. |
379
380**示例：**
381
382```ts
383import { BusinessError } from '@kit.BasicServicesKit';
384
385// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
386let subscriber:commonEventManager.CommonEventSubscriber;
387// 订阅者信息
388let subscribeInfo:commonEventManager.CommonEventSubscribeInfo = {
389  events: ["event"]
390};
391// 订阅公共事件回调
392function subscribeCB(err: BusinessError, data:commonEventManager.CommonEventData) {
393  if (err) {
394    console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
395  } else {
396    console.info("subscribe success, Consume callback " + JSON.stringify(data));
397  }
398}
399// 创建订阅者回调
400function createCB(err: BusinessError, commonEventSubscriber:commonEventManager.CommonEventSubscriber) {
401  if (err) {
402    console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
403  } else {
404    console.info("createSubscriber success");
405    subscriber = commonEventSubscriber;
406    // 订阅公共事件
407    try {
408      commonEventManager.subscribe(subscriber, subscribeCB);
409    } catch (error) {
410      let err: BusinessError = error as BusinessError;
411      console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
412    }
413  }
414}
415// 取消订阅公共事件回调
416function unsubscribeCB(err: BusinessError) {
417  if (err) {
418    console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`);
419  } else {
420    console.info("unsubscribe success");
421  }
422}
423// 创建订阅者
424try {
425  commonEventManager.createSubscriber(subscribeInfo, createCB);
426} catch (error) {
427  let err: BusinessError = error as BusinessError;
428  console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
429}
430
431// 取消订阅公共事件
432// 等待异步接口subscribe执行完毕，开发者根据实际业务选择是否需要添加setTimeout
433setTimeout(() => {
434  try {
435    commonEventManager.unsubscribe(subscriber, unsubscribeCB);
436  } catch (error) {
437    let err: BusinessError = error as BusinessError;
438    console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`);
439  }
440}, 500);
441```
442