• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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> | 是   | 回调函数。当公共事件发布成功时，err为undefined，否则为错误对象。 |
35
36**错误码：**
37
38以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
39
40| 错误码ID | 错误信息                            |
41| -------- | ----------------------------------- |
42| 401     | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. |
43| 1500007  | Failed to send the message to the common event service. |
44| 1500008  | Failed to initialize the common event service. |
45| 1500009  | Failed to obtain system parameters.  |
46
47**示例：**
48
49```ts
50import { BusinessError } from '@kit.BasicServicesKit';
51
52// 发布公共事件回调
53function publishCB(err: BusinessError) {
54  if (err) {
55    console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`);
56    return;
57  }
58  console.info(`Succeeded in publishing common event.`);
59}
60// 发布公共事件
61try {
62  commonEventManager.publish('event', publishCB);
63} catch (error) {
64  let err: BusinessError = error as BusinessError;
65  console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`);
66}
67```
68
69## commonEventManager.publish
70
71publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\<void>): void
72
73发布公共事件。使用callback异步回调。
74
75**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
76
77**系统能力：** SystemCapability.Notification.CommonEvent
78
79**参数：**
80
81| 参数名     | 类型                   | 必填 | 说明                   |
82| -------- | ---------------------- | ---- | ---------------------- |
83| event    | string                 | 是   | 表示要发布的公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。  |
84| options  | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是   | 表示发布公共事件的属性。 |
85| callback | syncCallback\<void>   | 是   | 回调函数。当公共事件发布成功时，err为undefined，否则为错误对象。  |
86
87**错误码：**
88
89以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
90
91| 错误码ID | 错误信息                            |
92| -------- | ----------------------------------- |
93| 401     | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed.      |
94| 1500007  | Failed to send the message to the common event service. |
95| 1500008  | Failed to initialize the common event service. |
96| 1500009  | Failed to obtain system parameters.  |
97
98**示例：**
99
100```ts
101import { BusinessError } from '@kit.BasicServicesKit';
102
103// 公共事件相关信息，以发布有序公共事件为例
104let options: commonEventManager.CommonEventPublishData = {
105  code: 0,
106  data: 'initial data',
107  isOrdered: true // 有序公共事件
108}
109// 发布公共事件回调
110function publishCB(err: BusinessError) {
111  if (err) {
112    console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`);
113    return;
114  }
115  console.info(`Succeeded in publishing common event.`);
116}
117// 发布公共事件
118try {
119  commonEventManager.publish('event', options, publishCB);
120} catch (error) {
121  let err: BusinessError = error as BusinessError;
122  console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`);
123}
124```
125
126## commonEventManager.createSubscriber
127
128createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void
129
130创建订阅者。使用callback异步回调。
131
132**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
133
134**系统能力：** SystemCapability.Notification.CommonEvent
135
136**参数：**
137
138| 参数名          | 类型                                                         | 必填 | 说明                       |
139| ------------- | ------------------------------------------------------------ | ---- | -------------------------- |
140| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)        | 是   | 表示订阅信息。             |
141| callback      | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 是   | 回调函数。当公共事件订阅者创建成功时，err为undefined，否则为错误对象。 |
142
143**错误码：**
144
145以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
146
147| 错误码ID | 错误信息                            |
148| -------- | ----------------------------------- |
149| 401     | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed.    |
150
151**示例：**
152
153```ts
154import { BusinessError } from '@kit.BasicServicesKit';
155
156// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
157let subscriber: commonEventManager.CommonEventSubscriber;
158// 订阅者信息
159let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
160  events: ['event']
161};
162// 创建订阅者回调
163function createCB(err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) {
164  if(!err) {
165    console.info(`Succeeded in creating subscriber.`);
166    subscriber = commonEventSubscriber;
167    return;
168  }
169  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
170}
171// 创建订阅者
172try {
173  commonEventManager.createSubscriber(subscribeInfo, createCB);
174} catch (error) {
175  let err: BusinessError = error as BusinessError;
176  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
177}
178```
179
180## commonEventManager.createSubscriber
181
182createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber>
183
184创建订阅者。使用Promise异步回调。
185
186**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
187
188**系统能力：** SystemCapability.Notification.CommonEvent
189
190**参数：**
191
192| 参数名          | 类型                                                  | 必填 | 说明           |
193| ------------- | ----------------------------------------------------- | ---- | -------------- |
194| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 是   | 表示订阅信息。 |
195
196**返回值：**
197| 类型                                                      | 说明             |
198| --------------------------------------------------------- | ---------------- |
199| Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 以Promise形式返回订阅者对象。 |
200
201**错误码：**
202
203以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
204
205| 错误码ID | 错误信息                            |
206| -------- | ----------------------------------- |
207| 401     | PParameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed.      |
208
209**示例：**
210
211```ts
212import { BusinessError } from '@kit.BasicServicesKit';
213
214// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
215let subscriber: commonEventManager.CommonEventSubscriber;
216// 订阅者信息
217let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
218  events: ['event']
219};
220// 创建订阅者
221commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber: commonEventManager.CommonEventSubscriber) => {
222  console.info(`Succeeded in creating subscriber.`);
223  subscriber = commonEventSubscriber;
224}).catch((err: BusinessError) => {
225  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
226});
227```
228
229## commonEventManager.createSubscriberSync<sup>10+</sup>
230
231createSubscriberSync(subscribeInfo: CommonEventSubscribeInfo): CommonEventSubscriber
232
233createSubscriber的同步接口。
234
235**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
236
237**系统能力：** SystemCapability.Notification.CommonEvent
238
239**参数：**
240
241| 参数名          | 类型                                                  | 必填 | 说明           |
242| ------------- | ----------------------------------------------------- | ---- | -------------- |
243| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 是   | 表示订阅信息。 |
244
245**返回值：**
246| 类型                                                      | 说明             |
247| --------------------------------------------------------- | ---------------- |
248| [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 返回订阅者对象。 |
249
250**错误码：**
251
252以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
253
254| 错误码ID | 错误信息                            |
255| -------- | ----------------------------------- |
256| 401     | PParameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed.      |
257
258**示例：**
259
260```ts
261import { BusinessError } from '@kit.BasicServicesKit';
262
263// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
264let subscriber: commonEventManager.CommonEventSubscriber;
265// 订阅者信息
266let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
267  events: ['event']
268};
269// 创建订阅者
270try {
271  subscriber = commonEventManager.createSubscriberSync(subscribeInfo);
272} catch (error) {
273  let err: BusinessError = error as BusinessError;
274  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
275}
276```
277
278## commonEventManager.subscribe
279
280subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\<CommonEventData>): void
281
282订阅公共事件。使用callback异步回调。
283
284**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
285
286**系统能力：** SystemCapability.Notification.CommonEvent
287
288**参数：**
289
290| 参数名       | 类型                                                | 必填 | 说明                             |
291| ---------- | ---------------------------------------------------- | ---- | -------------------------------- |
292| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)     | 是   | 表示订阅者对象。                 |
293| callback   | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | 是   | 回调函数。当公共事件订阅成功后，事件触发时执行的回调函数；否则订阅失败时，err为错误对象。 |
294
295**错误码：**
296
297以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
298
299| 错误码ID | 错误信息                            |
300| -------- | ----------------------------------- |
301| 401     | PParameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed.      |
302| 801  | capability not supported.               |
303| 1500007  | Failed to send the message to the common event service. |
304| 1500008  | Failed to initialize the common event service. |
305
306**示例：**
307
308```ts
309import { BusinessError } from '@kit.BasicServicesKit';
310
311// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
312let subscriber: commonEventManager.CommonEventSubscriber;
313// 订阅者信息
314let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
315  events: ['event']
316};
317// 订阅公共事件回调
318function SubscribeCB(err: BusinessError, data: commonEventManager.CommonEventData) {
319  if (err) {
320    console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
321    return;
322  }
323  console.info(`Succeeded in subscribing, data is ${JSON.stringify(data)}`);
324}
325// 创建订阅者回调
326function createCB(err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) {
327  if(!err) {
328    console.info(`Succeeded in creating subscriber.`);
329    subscriber = commonEventSubscriber;
330    // 订阅公共事件
331    try {
332      commonEventManager.subscribe(subscriber, SubscribeCB);
333    } catch (error) {
334      let err: BusinessError = error as BusinessError;
335      console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
336    }
337    return;
338  }
339  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
340}
341// 创建订阅者
342try {
343  commonEventManager.createSubscriber(subscribeInfo, createCB);
344} catch (error) {
345  let err: BusinessError = error as BusinessError;
346  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
347}
348```
349
350## commonEventManager.unsubscribe
351
352unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void
353
354取消订阅公共事件。使用callback异步回调。
355
356**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
357
358**系统能力：** SystemCapability.Notification.CommonEvent
359
360**参数：**
361
362| 参数名       | 类型                                             | 必填 | 说明                     |
363| ---------- | ----------------------------------------------- | ---- | ------------------------ |
364| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 是   | 表示订阅者对象。         |
365| callback   | AsyncCallback\<void>                            | 否   | 回调函数。当取消公共事件订阅成功时，err为undefined，否则为错误对象。 |
366
367**错误码：**
368
369以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。
370
371| 错误码ID | 错误信息                            |
372| -------- | ----------------------------------- |
373| 401     | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed.      |
374| 801  | capability not supported.               |
375| 1500007  | Failed to send the message to the common event service. |
376| 1500008  | Failed to initialize the common event service. |
377
378**示例：**
379
380```ts
381import { BusinessError } from '@kit.BasicServicesKit';
382
383// 定义订阅者，用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
384let subscriber: commonEventManager.CommonEventSubscriber | undefined;
385// 订阅者信息
386let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
387  events: ['event']
388};
389// 订阅公共事件回调
390function subscribeCB(err: BusinessError, data: commonEventManager.CommonEventData) {
391  if (err) {
392    console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
393    return;
394  }
395  console.info(`Succeeded in subscribing, data is ${JSON.stringify(data)}`);
396}
397// 创建订阅者回调
398function createCB(err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) {
399  if (err) {
400    console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
401    return;
402  }
403  console.info(`Succeeded in creating subscriber.`);
404  subscriber = commonEventSubscriber;
405  // 订阅公共事件
406  try {
407    commonEventManager.subscribe(subscriber, subscribeCB);
408  } catch (error) {
409    let err: BusinessError = error as BusinessError;
410    console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
411  }
412}
413// 取消订阅公共事件回调
414function unsubscribeCB(err: BusinessError) {
415  if (err) {
416    console.error(`Failed to unsubscribe. Code is ${err.code}, message is ${err.message}`);
417    return;
418  }
419  // subscriber不再使用时需要将其置为undefined，避免内存泄露
420  subscriber = undefined;
421  console.info(`Succeeded in unsubscribing.`);
422}
423// 创建订阅者
424try {
425  commonEventManager.createSubscriber(subscribeInfo, createCB);
426} catch (error) {
427  let err: BusinessError = error as BusinessError;
428  console.error(`Failed to create subscriber. 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(`Failed to unsubscribe. Code is ${err.code}, message is ${err.message}`);
439  }
440}, 500);
441```
442
443## CommonEventData<sup>10+</sup>
444
445type CommonEventData = _CommonEventData
446
447公共事件的数据。
448
449**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
450
451**系统能力：** SystemCapability.Notification.CommonEvent
452
453| 类型 | 说明 |
454| --- | --- |
455| [_CommonEventData](js-apis-inner-commonEvent-commonEventData.md) | 表示公共事件的数据。 |
456
457## CommonEventSubscriber<sup>10+</sup>
458
459type CommonEventSubscriber = _CommonEventSubscriber
460
461描述公共事件的订阅者。
462
463**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
464
465**系统能力：** SystemCapability.Notification.CommonEvent
466
467| 类型 | 说明 |
468| --- | --- |
469| [_CommonEventSubscriber](js-apis-inner-commonEvent-commonEventSubscriber.md) | 描述公共事件的订阅者。 |
470
471## CommonEventSubscribeInfo<sup>10+</sup>
472
473type CommonEventSubscribeInfo = _CommonEventSubscribeInfo
474
475用于表示订阅者的信息。
476
477**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
478
479**系统能力：** SystemCapability.Notification.CommonEvent
480
481| 类型 | 说明 |
482| --- | --- |
483| [_CommonEventSubscribeInfo](js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 用于表示订阅者的信息。 |
484
485## CommonEventPublishData<sup>10+</sup>
486
487type CommonEventPublishData = _CommonEventPublishData
488
489描述公共事件内容和属性。
490
491**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
492
493**系统能力：** SystemCapability.Notification.CommonEvent
494
495| 类型 | 说明 |
496| --- | --- |
497| [_CommonEventPublishData](js-apis-inner-commonEvent-commonEventPublishData.md) | 描述公共事件内容和属性。 |
498
499