CommonEvent开发指南

基本概念

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

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

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

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

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

接口列表

导入模块

import CommonEvent from '@ohos.commonevent';

创建公共事件订阅者

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

• CommonEventSubscribeInfo类型说明

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

• CommonEventSubscriber 类说明

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

• 创建订阅者接口（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)

  • 接口参数描述

• 返回值

  Promise

• 示例代码

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

订阅公共事件

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

• CommonEventData类型说明

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

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

  CommonEvent.subscribe(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封装公共事件发布相关数据、属性及限制等信息，包括公共事件类型（有序或无序）、订阅者所需权限等。

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

  CommonEvent.publish(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)

  • 接口参数描述

• 返回值

  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)

  • 接口参数描述

• 返回值

  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);

系统公共事件列表