HarmonyOS -公共事件开发指导
鸿蒙开发

HarmonyOS -公共事件开发指导

itemprop="discussionURL"Leave a comment

场景介绍

每个应用都可以订阅自己感兴趣的公共事件，订阅成功后且公共事件发布后，系统会把其发送给应用。这些公共事件可能来自系统、其他应用和应用自身。HarmonyOS提供了一套完整的API，支持用户订阅、发布和接收公共事件。发布公共事件需要借助CommonEventData对象，接收公共事件需要继承CommonEventSubscriber类并实现onReceiveEvent回调函数。

接口说明

公共事件相关基础类包含CommonEventData、CommonEventPublishInfo、CommonEventSubscribeInfo、CommonEventSubscriber和CommonEventManager。基础类之间的关系如下图所示：

图1 公共事件基础类关系图

CommonEventDataCommonEventData封装公共事件相关信息。用于在发布、分发和接收时处理数据。在构造CommonEventData对象时，相关参数需要注意以下事项：

  • code为有序公共事件的结果码，data为有序公共事件的结果数据，仅用于有序公共事件场景。
  • intent不允许为空，否则发布公共事件失败。

CommonEventPublishInfoCommonEventPublishInfo封装公共事件发布相关属性、限制等信息，包括公共事件类型（有序或粘性）、接收者权限等。

  • 有序公共事件：主要场景是多个订阅者有依赖关系或者对处理顺序有要求，例如：高优先级订阅者可修改公共事件内容或处理结果，包括终止公共事件处理；或者低优先级订阅者依赖高优先级的处理结果等。有序公共事件的订阅者可以通过CommonEventSubscribeInfo.setPriority()方法指定优先级，缺省为0，优先级范围[-1000, 1000]，值越大优先级越高。
  • 粘性公共事件：指公共事件的订阅动作是在公共事件发布之后进行，订阅者也能收到的公共事件类型。主要场景是由公共事件服务记录某些系统状态，如蓝牙、WLAN、充电等事件和状态。不使用粘性公共事件机制时，应用可以通过直接访问系统服务获取该状态；在状态变化时，系统服务、硬件需要提供类似observer等方式通知应用。发布粘性公共事件可以通过setSticky()方法设置， 发布粘性公共事件需要申请如下权限。声明请参考权限开发指导表1 reqPermissions权限申请字段说明。
"reqPermissions": [
  {
    "name": "ohos.permission.COMMONEVENT_STICKY",
    "reason": "Obtain the required permission",
    "usedScene": {
      "ability": [
        ".MainAbility"
      ],
      "when": "inuse"
    }
  },
  {
    ...
  }
]

CommonEventSubscribeInfo

CommonEventSubscribeInfo封装公共事件订阅相关信息，比如优先级、线程模式、事件范围等。线程模式（ThreadMode）：设置订阅者的回调方法执行的线程模式。ThreadMode有HANDLER，POST，ASYNC，BACKGROUND四种模式，目前只支持HANDLER模式。

  • HANDLER：在Ability的主线程上执行。
  • POST：在事件分发线程执行。
  • ASYNC：在一个新创建的异步线程执行。
  • BACKGROUND：在后台线程执行。

CommonEventSubscriberCommonEventSubscriber封装公共事件订阅者及相关参数。

  • CommonEventSubscriber.AsyncCommonEventResult类处理有序公共事件异步执行，详见API参考。
  • 目前只能通过调用CommonEventManager的subscribeCommonEvent()进行订阅。

CommonEventManager

CommonEventManager是为应用提供订阅、退订和发布公共事件的静态接口类。

发布公共事件

开发者可以发布四种公共事件：无序的公共事件、带权限的公共事件、有序的公共事件、粘性的公共事件。发布无序的公共事件：构造CommonEventData对象，设置Intent，通过构造operation对象把需要发布的公共事件信息传入intent对象。然后调用 CommonEventManager.publishCommonEvent(CommonEventData) 接口发布公共事件。 

try {
    Intent intent = new Intent();   
    Operation operation = new Intent.OperationBuilder()
            .withAction("com.my.test")
            .build();
    intent.setOperation(operation);
    CommonEventData eventData = new CommonEventData(intent);
    CommonEventManager.publishCommonEvent(eventData); 
    HiLog.info(LABEL_LOG, "Publish succeeded"); 
} catch (RemoteException e) {
    HiLog.error(LABEL_LOG, "Exception occurred during publishCommonEvent invocation."); 
}

发布携带权限的公共事件：构造CommonEventPublishInfo对象，设置订阅者的权限。

"reqPermissions": [
  {
    "name": "com.example.MyApplication.permission",
    "reason": "Obtain the required permission",
    "usedScene": {
      "ability": [
        ".MainAbility"
      ],
      "when": "inuse"
    }
  }, 
  {
    ...
  }
]

发布带权限的公共事件示例代码如下： 

Intent intent = new Intent();
Operation operation = new Intent.OperationBuilder()
        .withAction("com.my.test")
        .build();
intent.setOperation(operation);
CommonEventData eventData = new CommonEventData(intent);
CommonEventPublishInfo publishInfo = new CommonEventPublishInfo();
String[] permissions = {"com.example.MyApplication.permission"};
publishInfo.setSubscriberPermissions(permissions); // 设置权限
try {   
    CommonEventManager.publishCommonEvent(eventData, publishInfo); 
    HiLog.info(LABEL_LOG, "Publish succeeded"); 
} catch (RemoteException e) {
    HiLog.error(LABEL_LOG, "Exception occurred during publishCommonEvent invocation."); 
}

发布有序的公共事件：构造CommonEventPublishInfo对象，通过setOrdered(true)指定公共事件属性为有序公共事件，也可以指定一个最后的公共事件接收者。 

CommonEventSubscriber resultSubscriber = new MyCommonEventSubscriber();
CommonEventPublishInfo publishInfo = new CommonEventPublishInfo();
publishInfo.setOrdered(true); // 设置属性为有序公共事件
try {   
    CommonEventManager.publishCommonEvent(eventData, publishInfo, resultSubscriber); // 指定resultSubscriber为有序公共事件最后一个接收者。
} catch (RemoteException e) {
    HiLog.error(LABEL_LOG, "Exception occurred during publishCommonEvent invocation."); 
}

发布粘性公共事件：构造CommonEventPublishInfo对象，通过setSticky(true)指定公共事件属性为粘性公共事件。

  1. 发布者首先在config.json中申请发布粘性公共事件所需的权限，各字段含义详见权限申请字段说明。
{
    "reqPermissions": [{
        "name": "ohos.permission.COMMONEVENT_STICKY",
        "reason": "Obtain the required permission",
        "usedScene": {
           "ability": [
            ".MainAbility"
           ],
           "when": "inuse"
        }
    }, {
    ...
    }]
}

发布粘性公共事件。 

CommonEventPublishInfo publishInfo = new CommonEventPublishInfo();
publishInfo.setSticky(true); // 设置属性为粘性公共事件
try {   
    CommonEventManager.publishCommonEvent(eventData, publishInfo); 
} catch (RemoteException e) {
    HiLog.error(LABEL, "Exception occurred during publishCommonEvent invocation."); 
}

订阅公共事件

  1. 创建CommonEventSubscriber派生类，在onReceiveEvent()回调函数中处理公共事件。

说明

此处不能执行耗时操作，否则会阻塞UI线程，产生用户点击没有反应等异常。

class MyCommonEventSubscriber extends CommonEventSubscriber { 
     MyCommonEventSubscriber(CommonEventSubscribeInfo info) { 
         super(info);   
     }
     @Override 
     public void onReceiveEvent(CommonEventData commonEventData) {
     } 
 }

构造MyCommonEventSubscriber对象，调用CommonEventManager.subscribeCommonEvent()接口进行订阅。 

String event = "com.my.test";
MatchingSkills matchingSkills = new MatchingSkills();
matchingSkills.addEvent(event); // 自定义事件
matchingSkills.addEvent(CommonEventSupport.COMMON_EVENT_SCREEN_ON); // 亮屏事件
CommonEventSubscribeInfo subscribeInfo = new CommonEventSubscribeInfo(matchingSkills);
MyCommonEventSubscriber subscriber = new MyCommonEventSubscriber(subscribeInfo);
try {
    CommonEventManager.subscribeCommonEvent(subscriber); 
} catch (RemoteException e) {
    HiLog.error(LABEL, "Exception occurred during subscribeCommonEvent invocation."); 
}

如果订阅拥有指定权限应用发布的公共事件，发布者需要在config.json中申请权限，各字段含义详见权限申请字段说明。 

"reqPermissions": [
    {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "Obtain the required permission",
        "usedScene": {
            "ability": ["com.hmi.ivi.systemsetting.MainAbility"],
            "when": "inuse"
        }
    }
]

如果订阅的公共事件是有序的，可以调用setPriority(）指定优先级。 

String event = "com.my.test";
MatchingSkills matchingSkills = new MatchingSkills();
matchingSkills.addEvent(event); // 自定义事件

CommonEventSubscribeInfo subscribeInfo = new CommonEventSubscribeInfo(matchingSkills);
subscribeInfo.setPriority(100); // 设置优先级，优先级取值范围[-1000，1000]，值默认为0。
MyCommonEventSubscriber subscriber = new MyCommonEventSubscriber(subscribeInfo);
try {
     CommonEventManager.subscribeCommonEvent(subscriber); 
} catch (RemoteException e) {
     HiLog.error(LABEL, "Exception occurred during subscribeCommonEvent invocation."); 
}

针对在onReceiveEvent中不能执行耗时操作的限制，可以使用CommonEventSubscriber的goAsyncCommonEvent()来实现异步操作，函数返回后仍保持该公共事件活跃，且执行完成后必须调用AsyncCommonEventResult .finishCommonEvent()来结束。 

EventRunner runner = EventRunner.create(); // EventRunner创建新线程，将耗时的操作放到新的线程上执行
MyEventHandler myHandler = new MyEventHandler(runner); // MyEventHandler为EventHandler的派生类，在不同线程间分发和处理事件和Runnable任务
@Override
public void onReceiveEvent(CommonEventData commonEventData){
    final AsyncCommonEventResult result = goAsyncCommonEvent();

    Runnable task = new Runnable() {
        @Override
        public void run() {
            ........         // 待执行的操作，由开发者定义
            result.finishCommonEvent(); // 调用finish结束异步操作
        }
    };
    myHandler.postTask(task);
}

退订公共事件

在Ability的onStop()中调用CommonEventManager.unsubscribeCommonEvent()方法来退订公共事件。调用后，之前订阅的所有公共事件均被退订。 

try { 
    CommonEventManager.unsubscribeCommonEvent(subscriber);
 } catch (RemoteException e) {
    HiLog.error(LABEL, "Exception occurred during unsubscribeCommonEvent invocation.");
 }

相关实例

针对公共事件开发，有以下示例工程可供参考：

  • CommonEvent本示例演示了公共事件的订阅、发布和退订。

针对公共事件，有以下Codelabs可供参考：

  • 分布式输入法基于分布式能力，将手机作为智慧屏的虚拟控制器，控制文字输入和遥控播放。
  • 分布式亲子早教系统基于分布式能力，实现一个多屏互动、跨设备协同的亲子早教系统。
0 0 投票数
文章评分
订阅评论
提醒
0 评论
内联反馈
查看所有评论
0
希望看到您的想法，请您发表评论x