diff --git a/zh-cn/application-dev/application-models/Readme-CN.md b/zh-cn/application-dev/application-models/Readme-CN.md index d8a9c2dee97c04930ca01acb19bc5c0035246097..ac4a7b305a68d81740da3613051eb97a7916b857 100644 --- a/zh-cn/application-dev/application-models/Readme-CN.md +++ b/zh-cn/application-dev/application-models/Readme-CN.md @@ -41,9 +41,12 @@ - [进程模型](process-model-stage.md) - 公共事件 - [公共事件简介](common-event-overview.md) - - [公共事件订阅](common-event-subscription.md) + - 公共事件订阅 + - [公共事件订阅概述](common-event-subscription-overview.md) + - [动态订阅公共事件](common-event-subscription.md) + - [静态订阅公共事件（仅对系统应用开放）](common-event-static-subscription.md) + - [取消动态订阅公共事件](common-event-unsubscription.md) - [公共事件发布](common-event-publish.md) - - [公共事件取消订阅](common-event-unsubscription.md) - [后台服务](background-services.md) - 线程间通信 - [线程模型](thread-model-stage.md) diff --git a/zh-cn/application-dev/application-models/common-event-static-subscription.md b/zh-cn/application-dev/application-models/common-event-static-subscription.md new file mode 100644 index 0000000000000000000000000000000000000000..0793031c34371257282a9b5661f7b8182a0dab1a --- /dev/null +++ b/zh-cn/application-dev/application-models/common-event-static-subscription.md @@ -0,0 +1,107 @@ +# 静态订阅公共事件（仅对系统应用开放） + +## 场景介绍 + +静态订阅者在未接收订阅的目标事件时，处于未拉起状态，当系统或应用发布了指定的公共事件后，静态订阅者将被拉起，并执行onReceiveEvent回调，开发者可通过在onReceiveEvent回调中执行业务逻辑，实现当应用接收到特定公共事件时执行业务逻辑的目的。例如，某应用希望在设备开机的时候执行一些初始化任务，那么该应用可以静态订阅开机事件，在收到开机事件后会拉起该应用，然后执行初始化任务。静态订阅是通过配置文件声明和实现继承自StaticSubscriberExtensionAbility的类实现对公共事件的订阅。**需要注意的是，静态订阅公共事件对系统功耗有一定影响，建议谨慎使用**。 + + + +## 开发步骤 + +1. 静态订阅者声明 + + 声明一个静态订阅者，首先需要在工程中新建一个ExtensionAbility, 该ExtensionAbility从StaticSubscriberExtensionAbility派生，其代码实现如下： + + ```ts + import StaticSubscriberExtensionAbility from '@ohos.application.StaticSubscriberExtensionAbility' + + export default class StaticSubscriber extends StaticSubscriberExtensionAbility { + onReceiveEvent(event) { + console.log('onReceiveEvent, event:' + event.event); + } + } + ``` + + 开发者可以在onReceiveEvent中实现业务逻辑。 + + + +2. 静态订阅者工程配置 + + 在完成静态订阅者的代码实现后，需要将该订阅者配置到系统的module.json5中，配置形式如下： + + ```ts + { + "module": { + ...... + "extensionAbilities": [ + { + "name": "StaticSubscriber", + "srcEntrance": "./ets/StaticSubscriber/StaticSubscriber.ts", + "description": "$string:StaticSubscriber_desc", + "icon": "$media:icon", + "label": "$string:StaticSubscriber_label", + "type": "staticSubscriber", + "visible": true, + "metadata": [ + { + "name": "ohos.extension.staticSubscriber", + "resource": "$profile:subscribe" + } + ] + } + ] + ...... + } + } + ``` + + 上述json文件主要关注以下字段： + + - srcEntrance : 表示ExtensionAbility的入口文件路径，即步骤2中声明的静态订阅者所在的文件路径 + + - type: 表示ExtensionAbility的类型，对于静态订阅者需要声明为“staticSubscriber” + + - metadata: 表示ExtensionAbility的二级配置文件信息。由于不同的ExtensionAbility类型其配置信息不尽相同，因此需要使用不同的config文件表示其具体配置信息。 + - name：表示ExtensionAbility的类型名称，对于静态订阅类型，name必须声明为“ohos.extension.staticSubscriber”，否则无法识别为静态订阅者； + - resource: 字段表示ExtensionAbility的配置信息路径，由开发者自行定义，在本例中表示路径为“resources/base/profile/subscribe.json"。 + + metadata指向的二级配置文件的通常形式如下： + + ```ts + { + "commonEvents": [ + { + "name": "xxx", + "permission": "xxx", + "events":[ + "xxx" + ] + } + ] + } + ``` + + 需要注意二级配置文件必须按照此形式进行声明，否则会无法正确识别。下面对字段进行介绍： + + - name: 静态订阅ExtensionAbility的名称，需要和module.json5中声明的ExtensionAbility的name一致 + + - permission：订阅者要求的发布者需要具备的权限，对于发布了目标事件但不具备permission中声明的权限的发布者将被视为非法事件不予发布 + + - events: 订阅的目标事件列表 + +3. 静态订阅功能调试 + + 如果您希望在调试阶段尝试使用该功能，可修改设备系统配置文件/etc/static_subscriber_config.json,将待调试应用的包名添加至json文件中即可。 + + ```json + { + "xxx", + "ohos.extension.staticSubscriber", + "xxx" + } + ``` +## 相关示例 + +针对StaticSubscriberExtensionAbility开发，可参考如下实例：[StaticSubscriber：静态订阅（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StaticSubscriber) + diff --git a/zh-cn/application-dev/application-models/common-event-subscription-overview.md b/zh-cn/application-dev/application-models/common-event-subscription-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..83a4518283b9173dcbab7b7c8694eff9a2dd9704 --- /dev/null +++ b/zh-cn/application-dev/application-models/common-event-subscription-overview.md @@ -0,0 +1,7 @@ +# 公共事件订阅概述 + +​公共事件服务提供了动态订阅和静态订阅两种订阅方式。动态订阅与静态订阅最大的区别在于，动态订阅是应用运行时行为，而静态订阅是后台服务无需处于运行状态。 + +- 动态订阅：指订阅方在运行时调用公共事件订阅的API实现对公共事件的订阅，详见[动态订阅公共事件](common-event-subscription.md)。 + +- 静态订阅：订阅方通过配置文件声明和实现继承自StaticSubscriberExtensionAbility的类实现对公共事件的订阅，详见[静态订阅公共事件](common-event-static-subscription.md)。 \ No newline at end of file diff --git a/zh-cn/application-dev/application-models/common-event-subscription.md b/zh-cn/application-dev/application-models/common-event-subscription.md index 4d8742ff9ea9d5245e632a921f05ab976992d79c..70b9facc0572f0c2e75d483c6a43b0a388fd9647 100644 --- a/zh-cn/application-dev/application-models/common-event-subscription.md +++ b/zh-cn/application-dev/application-models/common-event-subscription.md @@ -1,9 +1,9 @@ -# 公共事件订阅 +# 动态订阅公共事件 ## 场景介绍 -当需要订阅某个公共事件，获取该公共事件传递的参数时，需要创建一个订阅者对象，用于作为订阅公共事件的载体，订阅公共事件并获取公共事件传递而来的参数。订阅部分系统公共事件需要先[申请权限](../security/accesstoken-guidelines.md)，订阅这些事件所需要的权限请见[公共事件权限列表](../reference/apis/js-apis-commonEventManager.md#support)。 +动态订阅是指当应用在运行状态时对某个公共事件进行订阅，在运行期间如果有订阅的事件发布那么订阅了这个事件的应用将会收到该事件及其传递的参数。例如，某应用希望在其运行期间收到电量过低的事件，并根据该事件降低其运行功耗，那么该应用便可动态订阅电量过低事件，收到该事件后关闭一些非必要的任务来降低功耗。订阅部分系统公共事件需要先[申请权限](../security/accesstoken-guidelines.md)，订阅这些事件所需要的权限请见[公共事件权限列表](../reference/apis/js-apis-commonEventManager.md#support)。 ## 接口说明 diff --git a/zh-cn/application-dev/application-models/common-event-unsubscription.md b/zh-cn/application-dev/application-models/common-event-unsubscription.md index cfb75aab186842944b9ba9945db2818734de9f1b..dd2eda1f9173cab1e98253dc28c532b158420c2d 100644 --- a/zh-cn/application-dev/application-models/common-event-unsubscription.md +++ b/zh-cn/application-dev/application-models/common-event-unsubscription.md @@ -1,9 +1,9 @@ -# 公共事件取消订阅 +# 取消动态订阅公共事件 ## 场景介绍 -订阅者完成业务需要时，需要主动取消订阅，订阅者通过下面方法取消订阅事件。 +动态订阅者完成业务需要时，需要主动取消订阅，订阅者通过调用[unsubscribe()](../reference/apis/js-apis-commonEventManager.md#commoneventmanagerunsubscribe)方法取消订阅事件。 ## 接口说明 @@ -21,7 +21,7 @@ import commonEvent from '@ohos.commonEventManager'; ``` -2. 根据[事件订阅章节](common-event-subscription.md)的步骤来订阅某个事件。 +2. 根据[动态订阅公共事件](common-event-subscription.md)章节的步骤来订阅某个事件。 3. 调用CommonEvent中的unsubscribe方法取消订阅某事件。