公共事件开发指导

场景介绍

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

接口说明

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

图1 公共事件基础类关系图 点击放大

CommonEventData

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

  • code为有序公共事件的结果码，data为有序公共事件的结果数据，仅用于有序公共事件场景。

  • intent不允许为空，否则发布公共事件失败。

    | 接口名 | 描述 | | ----------------------------------------------------- | ------------------------------------------ | | CommonEventData() | 创建公共事件数据。 | | CommonEventData(Intent intent) | 创建公共事件数据指定Intent。 | | CommonEventData(Intent intent, int code, String data) | 创建公共事件数据，指定Intent、code和data。 | | getIntent() | 获取公共事件Intent。 | | setCode(int code) | 设置有序公共事件的结果码。 | | getCode() | 获取有序公共事件的结果码。 | | setData(String data) | 设置有序公共事件的详细结果数据。 | | getData() | 获取有序公共事件的详细结果数据。 |

CommonEventPublishInfo

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

有序公共事件：主要场景是多个订阅者有依赖关系或者对处理顺序有要求，例如：高优先级订阅者可修改公共事件内容或处理结果，包括终止公共事件处理；或者低优先级订阅者依赖高优先级的处理结果等。

有序公共事件的订阅者可以通过[CommonEventSubscribeInfo](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ability-notification-fwk-common-event-0000000000029871#ZH-CN_TOPIC_0000001050988893__li1490625910238).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"    }  },  {    ...  }]

    | 接口名 | 描述 | | ---------------------------------------------------------- | ---------------------------------------------- | | CommonEventPublishInfo() | 创建公共事件信息。 | | CommonEventPublishInfo(CommonEventPublishInfo publishInfo) | 拷贝一个公共事件信息。 | | setSticky(boolean sticky） | 设置公共事件的粘性属性。 | | setOrdered(boolean ordered) | 设置公共事件的有序属性。 | | setSubscriberPermissions(String[] subscriberPermissions) | 设置公共事件订阅者的权限，多参数仅第一个生效。 |

CommonEventSubscribeInfo

CommonEventSubscribeInfo封装公共事件订阅相关信息，比如优先级、线程模式、事件范围等。

线程模式（ThreadMode）：设置订阅者的回调方法执行的线程模式。ThreadMode有HANDLER，POST，ASYNC，BACKGROUND四种模式，目前只支持HANDLER模式。

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

  • BACKGROUND：在后台线程执行。

    | 接口名 | 描述 | | ------------------------------------------------------- | -------------------------------------- | | CommonEventSubscribeInfo(MatchingSkills matchingSkills) | 创建公共事件订阅器指定matchingSkills。 | | CommonEventSubscribeInfo(CommonEventSubscribeInfo) | 拷贝公共事件订阅器对象。 | | setPriority(int priority) | 设置优先级，用于有序公共事件。 | | setThreadMode(ThreadMode threadMode) | 指定订阅者的回调函数运行在哪个线程上。 | | setPermission(String permission) | 设置发布者必须具备的权限。 | | setDeviceId(String deviceId) | 指定订阅哪台设备的公共事件。 |

CommonEventSubscriber

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

  • CommonEventSubscriber.AsyncCommonEventResult类处理有序公共事件异步执行，详见API参考。

  • 目前只能通过调用CommonEventManager的subscribeCommonEvent()进行订阅。

    | 接口名 | 描述 | | ------------------------------------------------------------ | ------------------------------------------------------------ | | CommonEventSubscriber(CommonEventSubscribeInfo subscribeInfo) | 构造公共事件订阅者实例。 | | onReceiveEvent(CommonEventData data) | 由开发者实现, 在接收到公共事件时被调用。 | | AsyncCommonEventResult goAsyncCommonEvent() | 设置有序公共事件异步执行。 | | setCodeAndData(int code, String data) | 设置有序公共事件的异步结果。 | | setData(String data) | 设置有序公共事件的异步结果数据。 | | setCode(int code) | 设置有序公共事件的异步结果码。 | | getData() | 获取有序公共事件的异步结果数据。 | | getCode() | 获取有序公共事件的异步结果码。 | | abortCommonEvent() | 取消当前的公共事件，仅对有序公共事件有效，取消后，公共事件不再向下一个订阅者传递。 | | getAbortCommonEvent() | 获取当前有序公共事件是否取消的状态。 | | clearAbortCommonEvent() | 清除当前有序公共事件abort状态。 | | isOrderedCommonEvent() | 查询当前公共事件的是否为有序公共事件。 | | isStickyCommonEvent() | 查询当前公共事件是否为粘性公共事件。 |

CommonEventManager

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

方法 描述
publishCommonEvent(CommonEventData eventData) 发布公共事件。
publishCommonEvent(CommonEventData event, CommonEventPublishInfo publishInfo) 发布公共事件指定发布信息。
publishCommonEvent(CommonEventData event, CommonEventPublishInfo publishInfo, CommonEventSubscriber resultSubscriber) 发布有序公共事件，指定发布信息和最后一个接收者。
subscribeCommonEvent(CommonEventSubscriber subscriber) 订阅公共事件。
unsubscribeCommonEvent(CommonEventSubscriber subscriber) 退订公共事件。

发布公共事件

开发者可以发布四种公共事件：无序的公共事件、带权限的公共事件、有序的公共事件、粘性的公共事件。

发布无序的公共事件：构造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对象，设置订阅者的权限。

  • 订阅者在config.json中申请所需的权限，各字段含义详见

    权限申请字段说明

    。

    说明

    非系统已定义的权限，需要先在config.json中自定义，才可以申请使用。详见权限定义字段说明

    "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"        }    }, {    ...    }]}

  2. 发布粘性公共事件。

    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) {    } }

  2. 构造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."); }

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

    EventRunner runner = EventRunner.create(); // EventRunner创建新线程，将耗时的操作放到新的线程上执行MyEventHandler myHandler = new MyEventHandler(runner); // MyEventHandler为EventHandler的派生类，在不同线程间分发和处理事件和Runnable任务@Overridepublic 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可供参考：

  • 分布式亲子早教系统

    基于分布式能力，实现一个多屏互动、跨设备协同的亲子早教系统。

  • 分布式输入法

    基于分布式能力，将手机作为智慧屏的虚拟控制器，控制文字输入和遥控播放。

results matching ""

    No results matching ""