common-event-subscription.md 3.4 KB
Newer Older
Z
zhuhan 已提交
1
# 动态订阅公共事件
Z
zengyawen 已提交
2 3 4 5


## 场景介绍

Z
zhuhan 已提交
6
动态订阅是指当应用在运行状态时对某个公共事件进行订阅,在运行期间如果有订阅的事件发布那么订阅了这个事件的应用将会收到该事件及其传递的参数。例如,某应用希望在其运行期间收到电量过低的事件,并根据该事件降低其运行功耗,那么该应用便可动态订阅电量过低事件,收到该事件后关闭一些非必要的任务来降低功耗。订阅部分系统公共事件需要先[申请权限](../security/accesstoken-guidelines.md),订阅这些事件所需要的权限请见[公共事件权限列表](../reference/apis/js-apis-commonEventManager.md#support)
Z
zengyawen 已提交
7 8 9 10


## 接口说明

11
详细接口见[接口文档](../reference/apis/js-apis-commonEventManager.md#commoneventmanagersubscribe)
Z
zengyawen 已提交
12 13 14

| 接口名 | 接口描述 |
| -------- | -------- |
Z
zhuhan 已提交
15
| createSubscriber(subscribeInfo: [CommonEventSubscribeInfo](../reference/apis/js-apis-commonEventManager.md#commoneventsubscribeinfo), callback: AsyncCallback<[CommonEventSubscriber](../reference/apis/js-apis-inner-commonEvent-commonEventSubscriber.md#使用说明)>): void | 创建订阅者对象(callback) |
16
| createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise<CommonEventSubscriber> | 创建订阅者对象(promise) |
Z
zengyawen 已提交
17 18 19 20 21
| subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback): void | 订阅公共事件 |


## 开发步骤

22
1. 导入模块。
Z
zengyawen 已提交
23 24
   
   ```ts
25
   import commonEventManager from '@ohos.commonEventManager';
X
xuzhihao 已提交
26
   import Base from '@ohos.base';
Z
zengyawen 已提交
27 28
   ```

F
fangJinliang1 已提交
29
2. 创建订阅者信息,详细的订阅者信息数据类型及包含的参数请见[CommonEventSubscribeInfo](../reference/apis/js-apis-commonEventManager.md#commoneventsubscribeinfo)文档介绍。
Z
zengyawen 已提交
30 31 32
   
   ```ts
   // 用于保存创建成功的订阅者对象,后续使用其完成订阅及退订的动作
X
xuzhihao 已提交
33
   let subscriber: commonEventManager.CommonEventSubscriber | null = null;
Z
zengyawen 已提交
34
   // 订阅者信息
X
xuzhihao 已提交
35
   let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
36
     events: ["usual.event.SCREEN_OFF"], // 订阅灭屏公共事件
Z
zengyawen 已提交
37 38 39 40 41 42 43
   }
   ```

3. 创建订阅者,保存返回的订阅者对象subscriber,用于执行后续的订阅、退订等操作。
   
   ```ts
   // 创建订阅者回调
X
xuzhihao 已提交
44
   commonEventManager.createSubscriber(subscribeInfo, (err: Base.BusinessError, data: commonEventManager.CommonEventSubscriber) => {
45
     if (err) {
46 47
       console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
       return;
48
     }
49 50 51
     console.info('Succeeded in creating subscriber.');
     subscriber = data;
     // 订阅公共事件回调
Z
zengyawen 已提交
52 53 54
   })
   ```

F
fangJinliang1 已提交
55
4. 创建订阅回调函数,订阅回调函数会在接收到事件时触发。订阅回调函数返回的data内包含了公共事件的名称、发布者携带的数据等信息,公共事件数据的详细参数和数据类型请见[CommonEventData](../reference/apis/js-apis-commonEventManager.md#commoneventdata)文档介绍。
Z
zengyawen 已提交
56 57 58 59
   
   ```ts
   // 订阅公共事件回调
   if (subscriber !== null) {
X
xuzhihao 已提交
60
     commonEventManager.subscribe(subscriber, (err: Base.BusinessError, data: commonEventManager.CommonEventData) => {
61
       if (err) {
62 63
         console.error(`Failed to subscribe common event. Code is ${err.code}, message is ${err.message}`);
         return;
64 65
       }
     })
Z
zengyawen 已提交
66
   } else {
67
     console.error(`Need create subscriber`);
Z
zengyawen 已提交
68 69
   }
   ```