• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 静态订阅公共事件（仅对系统应用开放）
2
3## 场景介绍
4
5静态订阅者在未接收订阅的目标事件时，处于未拉起状态。当系统或应用发布了指定的公共事件后，静态订阅者将被拉起，并执行[`onReceiveEvent()`](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent)回调。
6
7开发者可以通过在[`onReceiveEvent()`](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent)回调中执行业务逻辑，实现当应用接收到特定公共事件时执行业务逻辑的目的。例如，应用希望在设备开机时执行一些初始化任务，那么该应用可以静态订阅开机事件，在收到开机事件后会拉起该应用，然后执行初始化任务。
8
9静态订阅是通过配置文件声明和实现继承自[`StaticSubscriberExtensionAbility`](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md)的类实现对公共事件的订阅。
10
11> **说明：**
12>
13> 需要注意的是，静态订阅公共事件对系统功耗有一定影响，建议谨慎使用。
14
15## 开发步骤
16
171. 静态订阅者声明。
18
19   声明一个静态订阅者，首先需要在工程中新建一个ExtensionAbility，该ExtensionAbility从StaticSubscriberExtensionAbility派生。
20
21   开发者可以在[`onReceiveEvent()`](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent)回调中实现业务逻辑。
22
23   ```ts
24   import StaticSubscriberExtensionAbility from '@ohos.application.StaticSubscriberExtensionAbility'
25
26   export default class StaticSubscriber extends StaticSubscriberExtensionAbility {
27     onReceiveEvent(event) {
28       console.info('onReceiveEvent, event: ' + event.event);
29     }
30   }
31   ```
32
332. 静态订阅者工程配置。
34
35   在完成静态订阅者的代码实现后，需要在[module.json5配置文件](../quick-start/module-configuration-file.md)中进行配置订阅者信息。
36
37   ```ts
38   {
39     "module": {
40       ...
41       "extensionAbilities": [
42         {
43           "name": "StaticSubscriber",
44           "srcEntry": "./ets/staticsubscriber/StaticSubscriber.ts",
45           "description": "$string:StaticSubscriber_desc",
46           "icon": "$media:icon",
47           "label": "$string:StaticSubscriber_label",
48           "type": "staticSubscriber",
49           "exported": true,
50           "metadata": [
51             {
52               "name": "ohos.extension.staticSubscriber",
53               "resource": "$profile:subscribe"
54             }
55           ]
56         }
57       ]
58       ...
59     }
60   }
61   ```
62
63   其中部分字段解释如下：
64
65   - srcEntry：表示ExtensionAbility的入口文件路径，即步骤2中声明的静态订阅者所在的文件路径。
66
67   - type：表示ExtensionAbility的类型，对于静态订阅者需要声明为`staticSubscriber`。
68
69   - metadata：表示ExtensionAbility的二级配置文件信息。由于不同的ExtensionAbility类型其配置信息不尽相同，因此需要使用不同的config文件表示其具体配置信息。
70        - name：表示ExtensionAbility的类型名称，对于静态订阅类型，name必须声明为`ohos.extension.staticSubscriber`，否则无法识别为静态订阅者。
71        - resource：字段表示ExtensionAbility的配置信息路径，由开发者自行定义，在本例中表示路径为`resources/base/profile/subscribe.json`。
72
73
743. 配置metadata指向的二级配置文件。
75
76   ```json
77   {
78     "commonEvents": [
79       {
80         "name": "xxx",
81         "permission": "xxx",
82         "events":[
83           "xxx"
84         ]
85       }
86     ]
87   }
88   ```
89
90   需要注意二级配置文件必须按照此形式进行声明，否则会无法正确识别。部分字段解释如下：
91
92   - name: 静态订阅ExtensionAbility的名称，需要和module.json5中声明的ExtensionAbility的name一致。
93   - permission：订阅者要求的发布者需要具备的权限，对于发布了目标事件但不具备permission中声明的权限的发布者将被视为非法事件不予发布。
94   - events：订阅的目标事件列表。
95
964. 修改设备的[预置配置文件](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json)。[预置配置文件](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json)在设备上的路径为`/system/etc/app/install_list_permission.json`，设备开机启动时会读取该配置文件，在应用安装会对在文件中配置的`allowCommonEvent`公共事件类型进行授权。预授权配置文件字段内容包括`bundleName`、`app_signature`和`allowCommonEvent`。
97
98   - `bundleName`字段配置为应用的Bundle名称。
99   - `app_signature`字段配置为应用的指纹信息。指纹信息的配置参见[应用特权配置指南](../../device-dev/subsystems/subsys-app-privilege-config-guide.md#install_list_capabilityjson中配置)。
100   - `allowCommonEvent`字段配置为允许静态广播拉起的公共事件项。
101
102   > **说明**：当前仅支持预置应用配置该文件。
103
104   ```json
105   [
106     ...
107     {
108       "bundleName": "com.example.myapplication", // Bundle名称
109       "app_signature": ["****"], // 指纹信息
110       "allowCommonEvent": ["usual.event.A", "usual.event.B"], // 允许静态广播拉起的公共事件项
111       ]
112     }
113   ]
114   ```
115
116## 相关示例
117
118针对StaticSubscriberExtensionAbility开发，可参考如下实例：
119
120- [StaticSubscriber：静态订阅（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/SystemFeature/ApplicationModels/StaticSubscriber)
121
122