一、簡介

① 概念

• HarmonyOS 通過 CES（Common Event Service，公共事件服務）為應用程序提供訂閱、發布、退訂公共事件的能力，通過 ANS（Advanced Notification Service，即通知增強服務）系統服務來為應用程序提供發布通知的能力。
• 公共事件可分為系統公共事件和自定義公共事件：
• • 系統公共事件：系統將收集到的事件信息，根據系統策略發送給訂閱該事件的用戶程序。 公共事件包括：終端設備用戶可感知的亮滅屏事件，以及系統關鍵服務發布的系統事件（例如：USB 插拔，網絡連接，系統升級）等；
• • 自定義公共事件：應用自定義一些公共事件用來處理業務邏輯。
• 應用如果需要接收公共事件，需要訂閱相應的事件。

② 約束與限制

• 目前公共事件僅支持動態訂閱，部分系統事件需要具有指定的權限。
• 目前公共事件訂閱不支持多用戶。
• ThreadMode 表示線程模型，目前僅支持 HANDLER 模式，即在當前 UI 線程上執行回調函數。
• deviceId 用來指定訂閱本地公共事件還是遠端公共事件。deviceId 為 null、空字符串或本地設備 deviceId 時，表示訂閱本地公共事件，否則表示訂閱遠端公共事件。

③ 應用場景

• 每個應用都可以訂閱自己感興趣的公共事件，訂閱成功后且公共事件發布后，系統會把其發送給應用，這些公共事件可能來自系統、其它應用和應用自身。
• HarmonyOS 提供了一套完整的 API，支持用戶訂閱、發布和接收公共事件。發布公共事件需要借助 CommonEventData 對象，接收公共事件需要繼承 CommonEventSubscriber 類并實現 onReceiveEvent 回調函數。

三、公共事件的 API 說明

• 公共事件相關基礎類包含 CommonEventData、CommonEventPublishInfo、CommonEventSubscribeInfo、CommonEventSubscriber 和 CommonEventManager。基礎類之間的關系如下圖所示：

① CommonEventData

• CommonEventData 封裝公共事件相關信息，用于在發布、分發和接收時處理數據。
• 在構造 CommonEventData 對象時，相關參數需要注意以下事項：
• • code 為有序公共事件的結果碼，data 為有序公共事件的結果數據，僅用于有序公共事件場景。
• • intent 不允許為空，否則發布公共事件失敗。
• CommonEventData 主要 API：

接口名描述

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.setPriority() 方法指定優先級，缺省為 0，優先級范圍 [-1000, 1000]，值越大優先級越高。
• 粘性公共事件：指公共事件的訂閱動作是在公共事件發布之后進行，訂閱者也能收到的公共事件類型。主要場景是由公共事件服務記錄某些系統狀態，如藍牙、WLAN、充電等事件和狀態。不使用粘性公共事件機制時，應用可以通過直接訪問系統服務獲取該狀態；在狀態變化時，系統服務、硬件需要提供類似 observer 等方式通知應用。
• 發布粘性公共事件可以通過 setSticky() 方法設置， 發布粘性公共事件需要申請如下權限：

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

• CommonEventPublishInfo 主要接口：

接口名描述

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 主要接口：

接口名描述

CommonEventSubscribeInfo(MatchingSkills matchingSkills)	創建公共事件訂閱器指定matchingSkills
CommonEventSubscribeInfo(CommonEventSubscribeInfo)	拷貝公共事件訂閱器對象
setPriority(int priority)	設置優先級，用于有序公共事件
setThreadMode(ThreadMode threadMode)	指定訂閱者的回調函數運行在哪個線程上
setPermission(String permission)	設置發布者必須具備的權限
setDeviceId(String deviceId)	指定訂閱哪臺設備的公共事件

④ CommonEventSubscriber

• CommonEventSubscriber 封裝公共事件訂閱者及相關參數：
• • CommonEventSubscriber.AsyncCommonEventResult 類處理有序公共事件異步執行；
• • 目前只能通過調用 CommonEventManager 的 subscribeCommonEvent() 進行訂閱。
• CommonEventSubscriber 主要接口：

接口名描述

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 是為應用提供訂閱、退訂和發布公共事件的靜態接口類。
• 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 中申請所需的權限：

"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) 指定公共事件屬性為粘性公共事件。
• 發布者首先在 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."); }

五、訂閱公共事件

• 創建 CommonEventSubscriber 派生類，在 onReceiveEvent() 回調函數中處理公共事件：

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任務@Overridepublic void onReceiveEvent(CommonEventData commonEventData){final AsyncCommonEventResult result = goAsyncCommonEvent();Runnable task = new Runnable() {@Overridepublic 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.");}

總結

以上是生活随笔為你收集整理的HarmonyOS之公共事件的发布、订阅与退订的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。