OpenHarmony公共事件基本原理

鸿蒙小青娃 2023-03-13 14:12:33

简介

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

公共事件根据发送方不同可分为系统公共事件和自定义公共事件。

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

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

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

img

commonEvent接口的方法如下：

img

名词解释

订阅者信息(CommonEventSubscribeInfo)

用于设置订阅的一些基本信息，在创建订阅者时使用。

名称读写属性类型必填描述
events只读Array<string>是表示订阅的公共事件，一个订阅者可以订阅多个公共事件。
publisherPermission只读string否表示发布者的权限。发布者必须具有该权限才可以发布公共事件给该订阅者，该订阅者只接收具有该权限的发布者发布的公共事件。
publisherDeviceId只读string否表示设备ID，该值必须是同一ohos网络上的现有设备ID。
userId只读number否表示用户ID。此参数是可选的，默认值当前用户的ID。如果指定了此参数，则该值必须是系统中现有的用户ID。
priority只读number否表示订阅者的优先级，值的范围是-100到1000。数值越大，订阅者的优先级别越高，在有序公共事件发布时越先接收到发布信息。

写法示例：

let subscribeInfo: any = {
    events: ["event1","event2"],
    userId: 100,
    priority: 200,
    ...
}

订阅者(Subscriber)

用于作为订阅公共事件的载体，订阅公共事件并获取公共事件传递而来的参数。详细信息请参考CommonEvent文档/CommonEventSubscriber

方法名称描述
getCode获取公共事件的结果代码
setCode设置公共事件的结果代码
getData获取公共事件的结果数据
setData设置公共事件的结果数据
setCodeAndData设置公共事件的结果代码和结果数据
isOrderedCommonEvent查询当前公共事件的是否为有序公共事件
isStickyCommonEvent检查当前公共事件是否为一个粘性事件
abortCommonEvent取消当前的公共事件，仅对有序公共事件有效，取消后，公共事件不再向下一个订阅者传递
clearAbortCommonEvent清除当前公共事件的取消状态，仅对有序公共事件有效
getAbortCommonEvent获取当前有序公共事件是否取消的状态
getSubscribeInfo获取订阅者的订阅信息
finishCommonEvent结束当前有序公共事件

公共事件数据(CommonEventData)

通过订阅者成功订阅公共事件之后，返回的订阅的公共事件的一些基本信息。

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

公共事件发布信息(CommonEventPublishData)

在发布公共事件时使用，用于设置发布的公共事件的一些基本信息。

名称类型必填描述
bundleNamestring否表示包名称。
codenumber否表示公共事件的结果代码。
datastring否表示公共事件的自定义结果数据。
subscriberPermissionsArray<string>否表示订阅者的权限。
isOrderedboolean否表示是否是有序事件。
isStickyboolean否表示是否是粘性事件。
parameters{[key: string]: any}否表示公共事件的附加信息。

有序公共事件：

当一个无序公共事件发布时，该公共事件的所有订阅者会同时收到发布信息。

当一个有序公共事件发布时，该公共事件的所有订阅者会根据优先级高低依次收到发布信息。

粘性公共事件：

非粘性公共事件： 公共事件的订阅动作必须在公共事件发布之前进行。

​ 必须订阅者先订阅，然后公共事件发布，订阅者才可以接收到公共事件发布的信息。

粘性公共事件： 公共事件的订阅动作可以在公共事件发布之后进行。

​ 可以先发布公共事件，然后订阅者再订阅，依然可以收到公共事件发布的信息。

公共事件开发指导：

订阅、退订公共事件

  1. 设置订阅信息(公共事件名称、订阅者优先级等)
  2. 使用订阅信息创建订阅者
  3. 使用订阅者订阅、退订

系统公共事件名称请参考CommonEvent文档/公共事件列表

//步骤一： 导入commonEvent模块
import commonEvent from "@ohos.commonEvent";

//步骤二： 创建订阅信息，订阅者信息的数据类型及包含的参数请参考名词解释
let subscribeInfo : any = {
    events : ["testEvent"],     //要订阅的公共事件
    userId : 100,                 //用户Id
    priority : 1,                //该订阅者的优先级
    ...
}

let subscriberA = undefined
    
//步骤三：创建订阅者
commonEvent.createSubscriber(subscribeInfo, (err, subscriber) => {
              if (err?.code) {
                console.log("[CommonEvent] CreateSubscriber CallBack err=" + JSON.stringify(err))
              } else {
                console.log("[CommonEvent] CreateSubscriber")
                this.subscriberA = subscriber   //将创建订阅者回调生成的订阅者赋给subscriberA
              }
            })
            
//步骤四： 订阅公共事件
commonEvent.subscribe(subscriberA, (err, data) => {
              if (err?.code) {
                console.log("[CommonEvent] SubscribeCallBack err=" + JSON.stringify(err))
              } else {
                console.log("[CommonEvent] SubscribeCallBack data=" + JSON.stringify(data))
              }
            })
            
//退订公共事件
commonEvent.unsubscribe(subscriberA, err=>{
    if(err?.code){
       console.log("[CommonEvent] unSubscribeCallBack err=" + JSON.stringify(err))
    }else{
        console.log("[CommonEvent] unSubscribeCallBack succeed")
    }
})

发布公共事件

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

import commonEvent from "@ohos.commonEvent";

//步骤一：设置公共事件发布信息，具体参数信息请参考名词解释
let commonEventPublishData = {
           data : "test data",
           isOrdered: true,          //设置为有序公共事件
           code : 13178,
           isSticky : true,        //设置为粘性公共事件
           parameters : {            //公共事件发布时，携带的参数
                   a : "aa",
                   b : 'bb',
                   c : 'cc'
           }
    }

//步骤二：发布公共事件testEvent
commonEvent.publish("testEvent", commonEventPublishData,(err) => {
              if (err?.code) {
                Logger.info("[CommonEvent] Publish CallBack err=" + JSON.stringify(err))
              } else {
                Logger.info("[CommonEvent] Publish testEvent succeed ")
              }
            })

开发示例

此处以应用间的公共事件发布、订阅为例，应用A发布公共事件，应用B订阅公共事件。

时序图如下：

img

应用A中代码如下：

三个操作： 创建订阅者、订阅、发布公共事件testEvent

import commonEvent from '@ohos.commonEvent';

@Entry
@Component
struct TestA {
  @State publishCount: number = 0
  @State createSubscriberCount: number = 0
  @State SubscribetestEventCount: number = 0

  subscriberOftestEvent : any = undefined

  build() {
    Row() {
      Column() {

          //步骤一：创建订阅者
        Button('Create Subscriber Of testEvent: '+ this.createSubscriberCount).type(ButtonType.Capsule).fontSize(30).margin({bottom: 15})
          .onClick(()=>{
            this.createSubscriberCount+=1

            let subscribeInfo: any= {
              events: ["testEvent"]
            }

            commonEvent.createSubscriber(subscribeInfo, (err, subscriber) => {
              if (err.code) {
                console.log("[CommonEvent]CreateSubscriberCallBack err=" + JSON.stringify(err))
              } else {
                console.log("[CommonEvent]CreateSubscriber")
                this.subscriberOftestEvent = subscriber
              }
            })

          })

        //步骤二：订阅公共事件testEvent
        Button('Subscribe testEvent: '+ this.SubscribetestEventCount).type(ButtonType.Capsule).fontSize(30).margin({bottom: 30})
          .onClick(()=>{
            console.log("come in !!!")
            this.SubscribetestEventCount+=1

            console.log(`this.subscriberOftestEvent : ${JSON.stringify(this.subscriberOftestEvent)}`)
            commonEvent.subscribe(this.subscriberOftestEvent, (err, data) => {

              if (err?.code) {
                console.log("[CommonEvent] SubscribeCallBack err=" + JSON.stringify(err))
              } else {
                this.SubscribetestEventCount+=1
                console.log("[CommonEvent] SubscribeCallBack data=" + JSON.stringify(data))
              }
            })

          })

        //步骤三：发布公共事件testEvent
        Button('Publish testEvent : ' + this.publishCount).fontSize(30).margin({bottom: 15})
          .onClick(()=>{
            this.publishCount+=1
            commonEvent.publish("testEvent", (err) => {
              console.log(`err${JSON.stringify(err)}`)
              if (err?.code) {
                console.log("[CommonEvent] PublishCallBack err=" + JSON.stringify(err))
              } else {
                console.log("[CommonEvent] Publish Succeed ")
              }
            })
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

应用B中代码如下：

只订阅应用A发布的公共事件testEvent

import commonEvent from '@ohos.commonEvent';

@Component
@Entry
struct TestB{

  @State dCount : number = 0
  @State result : string = "待订阅"
  @State createSubscriberInfo : string = "待创建"
  subscriber : any = undefined
  subscribeInfo: any= {
    events: ["testEvent"],
  }

  build(){
    Column(){
      Column(){

        //步骤一：创建订阅者
        Button('创建订阅者: '+ this.createSubscriberInfo).type(ButtonType.Capsule).fontSize(40)
          .onClick(()=>{

            //创建订阅者回调
            commonEvent.createSubscriber(this.subscribeInfo, (err, subscriber) => {
              if (err?.code) {
                console.log("[CommonEvent] CreateSubscriberCallBack err=" + JSON.stringify(err))
              } else {
                console.log("[CommonEvent] CreateSubscriber")
                this.subscriber = subscriber
                this.createSubscriberInfo = "Create subscriber succeed"
              }
            })

          })

        //步骤二：订阅
        Button('订阅公共事件testEvent: '+ this.dCount+this.result).type(ButtonType.Capsule).fontSize(40)
          .onClick(()=>{
            
            commonEvent.subscribe(this.subscriber, (err, data) => {
              if (err?.code) {
                console.log("[CommonEvent]SubscribeCallBack err=" + JSON.stringify(err))
              } else {
                this.dCount+=1
                console.log("[CommonEvent]SubscribeCallBack data=" + JSON.stringify(data))
                this.result = "receive, event = " + data.event + ", data = " + data.data + ", code = " + data.code
              }
            })
          })
      }
    }

  }

}

操作流程：

  1. A应用创建订阅者、订阅

  2. B应用创建订阅者、订阅

  3. A应用发布公共事件testEvent

    (顺序不能乱，因为这里发布的不是粘性公共事件)

公共事件调试助手cem

公共事件与通知提供了供开发者查看公共事件信息及通知信息、发布公共事件等一些调试功能的工具。

这些工具已经随系统集成，开发者进入shell环境，可以直接调用相关命令。

publish发布公共事件

参数如下表所示

参数参数说明
-e/--event必选参数，发布事件名称
-s/--sticky可选参数，发布粘性事件，默认发布非粘性事件
-o/--ordered可选参数，发布有序事件，默认发布无序事件
-c/--code可选参数，公共事件结果码
-d/--data可选参数，公共事件携带数据
-h/--help帮助信息

用法示例：

# 发布名称为testevent的公共事件
cem publish --event "testevent"

# 发布名称为testevent的粘性有序公共事件，该事件的结果码为100，携带数据内容为“this is data”
cem publish -e "testevent" -s -o -c 100 -d "this is data"

dump打印公共事件相关信息

参数如下表所示

参数参数说明
-a/--all打印开机以来所有已发送的公共事件及其具体信息
-e/--event查询特定名称事件的具体信息
-h/--help帮助信息

用法示例：

# 打印公共事件名称为testevent的具体信息
cem dump -e "testevent"

打印出来的信息如下：

Subscribers:    No information
Sticky Events:  No information
Pending Events: No information
History Events: Total 1 information
NO 1
        Time: 20170805 10:12 AM
        PID: 2099
        UID: 20010037
        USERID: ALL_USER                                        
        BundleName: com.ohos.dtest
        RequiredPermission:                            # 发布者所要求的权限
        IsSticky: false                                # 发布的事件是否是粘性事件
        IsOrdered: false                            # 发布的事件是否是有序事件
        IsSystemApp: false                            # 发布者是否是系统应用
        IsSystemEvent: false                        # 发布的事件是否是系统事件
        Want:
                Action: testevent                    # 发布的事件名称
                Entity:
                Scheme:
                Uri:
                Flags: 0
                Type:
                BundleName:
                AbilityName:
                DevicedID:
        Code: 0                                        # 有序事件的结果码，仅在有序事件下有效
        Data:                                        # 事件携带的数据
        HasLastSubscriber: false                    # 是否有最终订阅者，仅在有序事件下有效
        EventState: RECEIVED                        # 事件发送状态
        ReceiverTime: 0
        DispatchTime: 0
        ResultAbort: false                            # 事件是否被终止，仅在有序事件下有效
        Subscribers:    Total 1 subscribers            # 所有可以接收该事件的订阅者信息
        NO 1
                Time: 20170805 10:11 AM
                BundleName: com.ohos.dtest            # 事件订阅者的包名
                Priority: 0                            # 订阅者的优先级，仅在订阅有序
                USERID: ALL_USER                    # 作为子系统订阅者，没有指定用户ID的情况下，默认订阅所有的用户；                                                                            # 如果是三方应用，则只能订阅这个包对应的用户ID，且不允许订阅其他的用户。
                Permission:                            # 订阅者所要求的权限
                DevicedID:
                IsFreeze: false                         # 订阅者是否被冻结，被冻结的订阅者将无法收到事件
                FreezeTime:  -
                EventState: DELIVERED                 # 订阅者接收状态

  • 发布者EventState有三种状态：

    • IDLE表示没有订阅者或者有序事件正在等待处理下一个订阅者；
    • RECEIVEING表示该订阅者们仍然在处理该事件；
    • RECEIVED表示所有订阅已经处理完成，事件发送完成。

  • 订阅者EventState有四种状态：

    • PENDING表示订阅者仍在等待处理事件；
    • DELIVERED表示订阅者已经完成接收；
    • SKIPPED表示该订阅者不能接收该事件，常见于权限不匹配或者订阅者被冻结的情况下；
    • TIMEOUT仅出现在有序事件下，表示该订阅者处理事件超时。

参考文献

[1]OpenHarmony公共事件.https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-commonEvent.md

...全文
203 回复 打赏 收藏 转发到动态 举报
写回复
用AI写文章
回复
切换为时间正序
请发表友善的回复…
发表回复
Reactive Extension，用于 RxJava3 的 openharmony 特定绑定
Reactive Extension，用于 RxJava3 的 openharmony 特定绑定。该模块向 RxJava 添加了最少的类，使得在 openharmony 应用程序中编写响应式组件变得简单而轻松。 更具体地说，它提供了一个调度程序，用于在主线程或任何给定的事件运行器上进行调度。
HarmonyOS/OpenHarmony应用开发-ArkTS触摸事件onTouch
HarmonyOS/OpenHarmony应用开发-ArkTS触摸事件onTouch
赋能千行百业数字化转型，OpenHarmony生态成果即将亮相HDC2022
在万物智联时代，赋能千行百业实现数字化、智能化转型升级。为了给广大开发者、生态伙伴提供成果展示、共同探讨的舞台，OpenHarmony将通过松湖对话、行业论坛及公共展区等环节，聚焦不同行业场景下的优秀实践案例，搭建交流沟通平台，展现OpenHarmony生态成果。公共展区则为合作伙伴、开发者们提供成果展示的阵地，让大家共同见证OpenHarmony在教育、政务、金融、工业等各个领域落地的终端产品及丰硕成果，展示行业标杆案例，吸引更多软硬件伙伴加入OpenHarmony大家庭，使能千行百业。
ArkTS语言HarmonyOS/OpenHarmony应用开发-message事件刷新卡片内容
ArkTS语言HarmonyOS/OpenHarmony应用开发-message事件刷新卡片内容
赋能千行百业数字化转型，OpenHarmony生态新成果即将亮相HDC2022
在万物智联时代，赋能千行百业实现数字化、智能化转型升级。为了给广大开发者、生态伙伴提供成果展示、共同探讨的舞台，OpenHarmony将通过松湖对话、行业论坛及公共展区等环节，聚焦不同行业场景下的优秀实践案例，搭建交流沟通平台，展现OpenHarmony生态成果。公共展区则为合作伙伴、开发者们提供成果展示的阵地，让大家共同见证OpenHarmony在教育、政务、金融、工业等各个领域落地的终端产品及丰硕成果，展示行业标杆案例，吸引更多软硬件伙伴加入OpenHarmony大家庭，使能千行百业。
OpenHarmony开发者社区

422

社区成员

1,786

社区内容

发帖
与我相关
我的任务
社区描述
OpenHarmony开发者社区
其他 企业社区
社区管理员
  • csdnsqst0025
  • shewaliujingli
  • BaoWei
加入社区
  • 近7日
  • 近30日
  • 至今

加载中

查看更多榜单

试试用AI创作助手写篇文章吧

+ 用AI写文章