CommonEvent开发指南

基本概念

OpenHarmony通过CES（Common Event Service，公共事件服务）为应用程序提供订阅、发布、退订公共事件的能力。

公共事件可分为系统公共事件和自定义公共事件。

• 系统公共事件：系统将收集到的事件信息，根据系统策略发送给订阅该事件的用户程序。 例如：系统关键服务发布的系统事件（例如：hap安装，更新，卸载等）。

• 自定义公共事件：应用自定义一些公共事件用来实现跨应用的事件通信能力。

每个应用都可以按需订阅公共事件，订阅成功且公共事件发布，系统会把其发送给应用。这些公共事件可能来自系统、其他应用和应用自身。

接口列表

导入模块

import CommonEvent from '@ohos.commonevent';

创建公共事件订阅者

根据开发者设定的公共事件订阅相关信息（比如准备订阅的公共事件集等）创建公共事件订阅者对象。

• CommonEventSubscribeInfo类型说明

  CommonEventSubscribeInfo封装公共事件订阅相关信息，比如准备订阅的公共事件集、发布者必须具备的权限、发布者的设备ID、发布者的用户ID、优先级等。

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | —————————- | ———— | ——————- | —— | —————————————————————————————— | | events | 只读 | Array | 是 | 表示要订阅的公共事件集。 | | publisherPermission | 只读 | string | 否 | 表示发布者的权限。 | | publisherDeviceId | 只读 | int | 否 | 表示发布者的设备ID，该值必须是同一ohos网络上的现有设备ID。 | | userId | 只读 | int | 否 | 表示发布者的用户ID。默认值当前用户的ID。如果指定了此参数，则该值必须是系统中现有的用户ID。 | | priority | 只读 | int | 否 | 表示订阅者的优先级，范围为-100~1000，用于有序公共事件。 |

• CommonEventSubscriber 类说明

  CommonEventSubscriber封装公共事件订阅者及相关参数，主要接口如下。

  | 名称 | 参数 | 返回值 | 描述 | | ——————————- | ————————————————————————————- | ————————————————- | —————————————————————————————— | | getCode | callback: AsyncCallback | void | 获取公共事件的结果代码（callback形式） | | getCode | void | Promise | 获取公共事件的结果代码（Promise形式） | | setCode | code: number, callback: AsyncCallback | void | 设置有序公共事件的结果代码（callback形式） | | setCode | code: number | Promise | 设置有序公共事件的结果代码（Promise形式） | | getData | callback: AsyncCallback | void | 获取公共事件的结果数据（callback形式） | | getData | void | Promise | 获取公共事件的结果数据（Promise形式） | | setData | data: string, callback: AsyncCallback | void | 设置有序公共事件的结果数据（callback形式） | | setData | data: string | Promise | 设置有序公共事件的结果数据（Promise形式） | | setCodeAndData | code: number, data: string, callback: AsyncCallback | void | 设置有序公共事件的结果代码和结果数据（callback形式） | | setCodeAndData | code: number, data: string | Promise | 设置有序公共事件的结果代码和结果数据（Promise形式） | | isOrderedCommonEvent | callback: AsyncCallback | void | 查询当前公共事件的是否为有序公共事件，返回true代表是有序公共事件，false代表不是有序公共事件（callback形式） | | isOrderedCommonEvent | void | Promise | 查询当前公共事件的是否为有序公共事件，返回true代表是有序公共事件，false代表不是有序公共事件（Promise形式） | | abortCommonEvent | callback: AsyncCallback | void | 取消当前的公共事件，仅对有序公共事件有效，取消后，公共事件不再向下一个订阅者传递（callback形式） | | abortCommonEvent | void | Promise | 取消当前的公共事件，仅对有序公共事件有效，取消后，公共事件不再向下一个订阅者传递（Promise形式） | | clearAbortCommonEvent | callback: AsyncCallback | void | 清除当前有序公共事件abort状态（callback形式） | | clearAbortCommonEvent | void | Promise | 清除当前有序公共事件abort状态（Promise形式） | | getAbortCommonEvent | callback: AsyncCallback | void | 获取当前有序公共事件是否取消的状态（callback形式） | | getAbortCommonEvent | void | Promise | 获取当前有序公共事件是否取消的状态Promise形式） | | getSubscribeInfo | callback: AsyncCallback | void | 获取订阅者的订阅信息（callback形式） | | getSubscribeInfo | void | Promise | 获取订阅者的订阅信息（Promise形式） |

• 创建订阅者接口（callback形式）

  CommonEvent.createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback)

  • 接口参数描述

• 返回值

  void

• 示例代码

  var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
  //订阅者信息
  var subscribeInfo = {
    events: ["event"]
  };
  //创建订阅者回调
  function CreateSubscriberCallBack(err, data) {
    console.info("==========================>CreateSubscriberCallBack=======================>");
    subscriber = data;
  }
  //创建订阅者
  CommonEvent.createSubscriber(subscribeInfo, CreateSubscriberCallBack);

• 创建订阅者接口（Promise形式）

  CommonEvent.createSubscriber(subscribeInfo: CommonEventSubscribeInfo)

  • 接口参数描述

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | ——————- | ———— | ———————————— | —— | —————— | | subscribeInfo | 只读 | CommonEventSubscribeInfo | 是 | 表示订阅信息 |

  • 返回值

    Promise

  • 示例代码

  var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
  //订阅者信息
  var subscribeInfo = {
      events: ["event"]
  };
  //创建订阅者
  CommonEvent.createSubscriber(subscribeInfo).then((data) => {

    console.info("==========================>createSubscriberPromise=======================>");
  subscriber = data;

  }); ```

订阅公共事件

订阅公共事件，并指定公共事件订阅者对象和接收公共事件的回调函数。

• CommonEventData类型说明

  CommonEventData封装公共事件相关信息。用于在接收时处理数据。

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | ————— | ———— | —————————— | —— | ———————————————————————————- | | event | 只读 | string | 是 | 表示当前接收的公共事件名称 | | bundleName | 只读 | string | 否 | 表示包名称 | | code | 只读 | int | 否 | 表示公共事件的结果代码，用于传递int类型的数据 | | data | 只读 | string | 否 | 表示公共事件的自定义结果数据，用于传递string 类型的数据 | | parameters | 只读 | {[key: string]: any} | 否 | 表示公共事件的附加信息 |

• 订阅公共事件接口（callback形式）

  CommonEvent.subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback)

  • 接口参数描述

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | ————— | ———— | ——————————————— | —— | ——————————————— | | subscriber | 只读 | CommonEventSubscriber | 是 | 表示订阅者对象 | | callback | 只读 | AsyncCallback | 是 | 表示接收公共事件数据的回调函数 |

  • 返回值

    void

  • 示例代码

    无序事件：

    var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
    //订阅者信息
    var subscribeInfo = {
        events: ["event"]
    };
    //订阅公共事件回调
    function SubscribeCallBack(err, data) {
        console.info("==========================>SubscribeCallBack=======================>");
    }
    //创建订阅者回调
    function CreateSubscriberCallBack(err, data) {
        console.info("==========================>CreateSubscriberCallBack=======================>");
        subscriber = data;
        //订阅公共事件
        CommonEvent.subscribe(subscriber, SubscribeCallBack);
    }
    //创建订阅者
    CommonEvent.createSubscriber(subscribeInfo, CreateSubscriberCallBack);

    有序事件：

    var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
    //订阅者信息
    var subscribeInfo = {
        events: ["event"]
    };
    //设置有序公共事件的结果代码回调
    function SetCodeCallBack(err) {
        console.info("==========================>SetCodeCallBack=======================>");
    }
    //设置有序公共事件的结果数据回调
    function SetDataCallBack(err) {
        console.info("==========================>SetDataCallBack=======================>");
    }
    //完成本次有序公共事件处理回调
    function FinishCommonEventCallBack(err) {
        console.info("==========================>FinishCommonEventCallBack=======================>");
    }
    //订阅公共事件回调
    function SubscribeCallBack(err, data) {
        console.info("==========================>SubscribeCallBack=======================>");
        //设置有序公共事件的结果代码
        subscriber.setCode(0, SetCodeCallBack);
        //设置有序公共事件的结果数据
        subscriber.setData("publish_data_changed", SetDataCallBack);
        //完成本次有序公共事件处理
        subscriber.finishCommonEvent(FinishCommonEventCallBack)
    }
    //创建订阅者回调
    function CreateSubscriberCallBack(err, data) {
        console.info("==========================>CreateSubscriberCallBack=======================>");
        subscriber = data;
        //订阅公共事件
        CommonEvent.subscribe(subscriber, SubscribeCallBack);
    }
    //创建订阅者
    CommonEvent.createSubscriber(subscribeInfo, CreateSubscriberCallBack);

​

发布公共事件

发布指定事件名称的公共事件，并可携带事件相关数据、属性、限制等信息。

• CommonEventPublishData类型说明

  CommonEventPublishData封装公共事件发布相关数据、属性及限制等信息，包括公共事件类型（有序或无序）、订阅者所需权限等。

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | ——————————- | ———— | —————————— | —— | —————————————— | | bundleName | 只读 | string | 否 | 表示包名称 | | code | 只读 | int | 否 | 表示公共事件的结果代码 | | data | 只读 | string | 否 | 表示公共事件的自定义结果数据 | | subscriberPermissions | 只读 | Array | 否 | 表示订阅者所需的权限 | | isOrdered | 只读 | bool | 否 | 表示是否是有序事件 | | parameters | 只读 | {[key: string]: any} | 否 | 表示公共事件的附加信息 |

• 发布公共事件接口（callback形式）

  CommonEvent.publish(event: string, callback: AsyncCallback)

  • 接口参数描述

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | ———— | ———— | —————————- | —— | ———————————— | | event | 只读 | string | 是 | 表示要发送的公共事件名称 | | callback | 只读 | AsyncCallback | 是 | 表示被指定的回调方法 |

  • 返回值

    void

  • 示例代码

  //发布公共事件回调
  function PublishCallBack(err) {
      console.info("==========================>PublishCallBack=======================>");
      console.info("==========================>err:=======================>", err.code);
  }
  //发布公共事件
  CommonEvent.publish("publish_event", PublishCallBack);

• 发布公共事件指定发布信息接口（callback形式）

  CommonEvent.publish(event: string, options: CommonEventPublishData, callback: AsyncCallback)

  • 接口参数描述

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | ———— | ———— | ——————————— | —— | ———————————— | | event | 只读 | string | 是 | 表示要发布的公共事件名称 | | options | 只读 | CommonEventPublishData | 是 | 表示发布公共事件的属性 | | callback | 只读 | AsyncCallback | 是 | 表示被指定的回调方法 |

  • 返回值

    void

  • 示例代码

  //公共事件相关信息
  var options = {
        code: 0;                //公共事件的初始代码
        data: "initial data";    //公共事件的初始数据
        isOrdered: true;        //有序公共事件
  }
  //发布公共事件回调
  function PublishCallBack(err) {
        console.info("==========================>PublishCallBack=======================>");
  }
  //发布公共事件
  CommonEvent.publish("publish_event", options, PublishCallBack);

取消订阅公共事件

• 取消订阅公共事件接口（callback形式）

  CommonEvent.unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback)

  • 接口参数描述

  | 名称 | 读写属性 | 类型 | 必填 | 描述 | | ————— | ———— | ——————————- | —— | ——————————— | | subscriber | 只读 | CommonEventSubscriber | 是 | 表示订阅者对象 | | callback | 只读 | AsyncCallback | 是 | 表示取消订阅的回调方法 |

  • 返回值

    void

  • 示例代码

  var subscriber;    //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
  //订阅者信息
  var subscribeInfo = {
      events: ["event"]
  };
  //订阅公共事件回调
  function SubscribeCallBack(err, data) {
      console.info("==========================>SubscribeCallBack=======================>");
  }
  //创建订阅者回调
  function CreateSubscriberCallBack(err, data) {
      console.info("==========================>CreateSubscriberCallBack=======================>");
      subscriber = data;
      //订阅公共事件
      CommonEvent.subscribe(subscriber, SubscribeCallBack);
  }
  //取消订阅公共事件回调
  function UnsubscribeCallBack(err) {
      console.info("==========================>UnsubscribeCallBack=======================>");
  }
  //创建订阅者
  CommonEvent.createSubscriber(subscribeInfo, CreateSubscriberCallBack);
  //取消订阅公共事件
  CommonEvent.unsubscribe(subscriber, UnsubscribeCallBack);

系统公共事件列表