• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 静态订阅公共事件（仅对系统应用开放）
2
3## 场景介绍
4
5静态订阅者在未接收订阅的目标事件时，处于未拉起状态。当系统或应用发布了指定的公共事件后，静态订阅者将被拉起，并执行[`onReceiveEvent()`](../../reference/apis-basic-services-kit/js-apis-application-staticSubscriberExtensionAbility-sys.md#staticsubscriberextensionabilityonreceiveevent)回调。
6
7开发者可以通过在[`onReceiveEvent()`](../../reference/apis-basic-services-kit/js-apis-application-staticSubscriberExtensionAbility-sys.md#staticsubscriberextensionabilityonreceiveevent)回调中执行业务逻辑，实现当应用接收到特定公共事件时执行业务逻辑的目的。例如，应用希望在设备开机时执行一些初始化任务，那么该应用可以静态订阅开机事件，在收到开机事件后会拉起该应用，然后执行初始化任务。
8
9静态订阅是通过配置文件声明和实现继承自[StaticSubscriberExtensionAbility](../../reference/apis-basic-services-kit/js-apis-application-staticSubscriberExtensionAbility-sys.md)的类实现对公共事件的订阅。
10
11> **说明：**
12>
13> 静态订阅公共事件对系统功耗有一定影响，建议谨慎使用。
14
15## 生命周期
16
17[StaticSubscriberExtensionAbility](../../reference/apis-basic-services-kit/js-apis-application-staticSubscriberExtensionAbility-sys.md)在[`onReceiveEvent()`](../../reference/apis-basic-services-kit/js-apis-application-staticSubscriberExtensionAbility-sys.md#staticsubscriberextensionabilityonreceiveevent)执行完`15秒`后销毁。
18
19## 开发步骤
20
211. 静态订阅者声明。
22
23   声明一个静态订阅者，首先需要在工程中新建一个ExtensionAbility，该ExtensionAbility从[StaticSubscriberExtensionAbility](../../reference/apis-basic-services-kit/js-apis-application-staticSubscriberExtensionAbility-sys.md)派生。
24
25   开发者可以在[`onReceiveEvent()`](../../reference/apis-basic-services-kit/js-apis-application-staticSubscriberExtensionAbility-sys.md#staticsubscriberextensionabilityonreceiveevent)回调中实现业务逻辑。
26
27   ```ts
28   import { commonEventManager, StaticSubscriberExtensionAbility } from '@kit.BasicServicesKit';
29   import { hilog } from '@kit.PerformanceAnalysisKit';
30
31   const TAG: string = 'StaticSubscriber';
32   const DOMAIN_NUMBER: number = 0xFF00;
33
34   export default class StaticSubscriber extends StaticSubscriberExtensionAbility {
35     onReceiveEvent(event: commonEventManager.CommonEventData): void {
36       hilog.info(DOMAIN_NUMBER, TAG, 'onReceiveEvent, event: ' + event.event);
37       //...
38     }
39   }
40   ```
41
422. 静态订阅者工程配置。
43
44   在完成静态订阅者的代码实现后，需要在[module.json5配置文件](../../quick-start/module-configuration-file.md)中进行配置订阅者信息。
45
46   ```json
47   {
48     "module": {
49   	// ...
50       "extensionAbilities": [
51         {
52           "name": "StaticSubscriber",
53           "srcEntry": "./ets/staticsubscriber/StaticSubscriber.ets",
54           "description": "$string:StaticSubscriber_desc",
55           "icon": "$media:app_icon",
56           "label": "$string:StaticSubscriber_label",
57           "type": "staticSubscriber",
58           "exported": false,
59           "metadata": [
60             {
61               "name": "ohos.extension.staticSubscriber",
62               "resource": "$profile:subscribe"
63             }
64           ]
65         }
66       ],
67   	// ...
68     }
69   }
70   ```
71
72   其中部分字段解释如下：
73
74   - srcEntry：表示ExtensionAbility的入口文件路径，即步骤2中声明的静态订阅者所在的文件路径。
75
76   - type：表示ExtensionAbility的类型，对于静态订阅者需要声明为`staticSubscriber`。
77
78   - metadata：表示ExtensionAbility的二级配置文件信息。由于不同的ExtensionAbility类型其配置信息不尽相同，因此需要使用不同的config文件表示其具体配置信息。
79        - name：表示ExtensionAbility的类型名称，对于静态订阅类型，name必须声明为`ohos.extension.staticSubscriber`，否则无法识别为静态订阅者。
80        - resource：字段表示ExtensionAbility的配置信息路径，由开发者自行定义，在本例中表示路径为`resources/base/profile/subscribe.json`。
81
82
833. 配置metadata指向的二级配置文件subscribe.json。
84
85   > **说明：**
86   >
87   > 二级配置文件必须按照此形式进行声明，否则会无法正确识别。
88
89   ```json
90   {
91     "commonEvents": [
92       {
93         "name": "StaticSubscriber",
94         "permission": "",
95         "events": [
96           "usual.event.AIRPLANE_MODE"
97         ]
98       }
99     ]
100   }
101   ```
102
103   commonEvents标签标识订阅者配置静态订阅事件，轻量级设备上不支持此标签和子标签。标签值为对象数组类型，包含name、permission、events三个子标签。
104
105   **表1** commonEvents标签说明
106
107   | **属性名称** | **含义**                                                     | **数据类型** | **是否可缺省**             |
108   | ------------ | ------------------------------------------------------------ | ------------ | -------------------------- |
109   | name         | 标识静态订阅ExtensionAbility的名称，需要和module.json5中声明的ExtensionAbility的name一致。 | 字符串       | 该标签不可缺省。           |
110   | permission   | 标识订阅者要求的发布者需要具备的权限。                       | 字符串       | 该标签可缺省，缺省值为空。 |
111   | events       | 标识订阅的目标事件列表。                                     | 字符串数组   | 该标签不可缺省。           |
112
1134. 修改设备的[预置配置文件](https://gitee.com/openharmony/vendor_hihope/blob/OpenHarmony-5.0.3-Release/rk3568/preinstall-config/install_list_capability.json)。预置配置文件在设备上的路径为`/system/variant/phone/base/etc/app/install_list_capability.json`，设备开机启动时会读取该配置文件，在应用安装时会对在文件中配置的`allowCommonEvent`公共事件类型进行授权。预授权配置文件字段内容包括`bundleName`、`app_signature`和`allowCommonEvent`。
114
115   - `bundleName`字段配置为应用的Bundle名称。
116   - `app_signature`字段配置为应用的指纹信息。指纹信息的配置请参见[应用特权配置指南](../../../device-dev/subsystems/subsys-app-privilege-config-guide.md#install_list_capabilityjson中配置)，或者通过[bm工具](../../tools/bm-tool.md)获取并填写该应用的`appId`。
117   - `allowCommonEvent`字段配置为允许静态广播拉起的公共事件项。
118
119   ```json
120   [
121     // ...
122     {
123       "bundleName": "com.samples.stageprocessthread", // Bundle名称
124       "app_signature": ["****"], // 指纹信息
125       "allowCommonEvent": ["usual.event.AIRPLANE_MODE"] // 允许静态广播拉起的公共事件项
126     }
127   ]
128   ```
129
130   > **说明**：
131   >
132   > 当前仅支持预置应用配置该文件。
133
134## 相关实例
135
136针对StaticSubscriberExtensionAbility开发，可参考如下实例：
137
138- [静态订阅（ArkTS）（Full SDK）（API10）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-5.0.3-Release/code/SystemFeature/ApplicationModels/StaticSubscriber)
139