• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.pluginComponent (PluginComponentManager)
2
3The **PluginComponentManager** module provides APIs for the **PluginComponent** user to request components and data and send component templates and data.
4
5>  **NOTE**
6>
7>  - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import { pluginComponentManager } from '@kit.ArkUI';
13```
14
15## PluginComponentTemplate
16
17Describes the **PluginComponent** template parameters.
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23| Name   | Type  | Mandatory| Description                       |
24| ------- | ------ | ---- | --------------------------- |
25| source  | string | Yes  | Component template name.               |
26| ability | string | Yes  | Bundle name of the provider ability.|
27
28## pluginComponentManager
29
30Implements a plugin component manager.
31
32### KVObject
33
34type KVObject = { [key: string]: number | string | boolean | [] | KVObject }
35
36Defines a key-value pair data structure that conforms to JSON format.
37
38**Atomic service API**: This API can be used in atomic services since API version 12.
39
40**System capability**: SystemCapability.ArkUI.ArkUI.Full
41
42| Name   | Type  | Mandatory| Description                       |
43| ------- | ------ | ---- | --------------------------- |
44|  [key: string]  | number \| string \| boolean \| [] \| [KVObject](#kvobject)  | Yes  | Key-value pair:<br>**number**: numeric value type.<br> **string**: string value type. The value can be an empty string.<br> **boolean**: boolean value type.<br> **[]**: empty array value.<br>**[KVObject](#kvobject)**: nested KVObject value type.           |
45
46
47### PushParameters
48
49Defines the parameters required when using the **PluginManager.Push** API.
50
51**Atomic service API**: This API can be used in atomic services since API version 12.
52
53**System capability**: SystemCapability.ArkUI.ArkUI.Full
54
55| Name       | Type                                 | Mandatory  | Description                                      |
56| --------- | ----------------------------------- | ---- | ---------------------------------------- |
57| want      | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes   | Ability information of the component user.                         |
58| name      | string                              | Yes   | Component name.                                   |
59| data      | [KVObject](#kvobject)               | Yes   | Component data value.                                  |
60| extraData | [KVObject](#kvobject)               | Yes   | Additional data value.                                  |
61| jsonPath  | string                              | No   | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.|
62
63### RequestParameters
64
65Defines the parameters required when using the **PluginManager.Request** API.
66
67**Atomic service API**: This API can be used in atomic services since API version 12.
68
69**System capability**: SystemCapability.ArkUI.ArkUI.Full
70
71| Name      | Type                                 | Mandatory  | Description                                      |
72| -------- | ----------------------------------- | ---- | ---------------------------------------- |
73| want     | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes   | Ability information of the component provider.                         |
74| name     | string                              | Yes   | Name of the requested component.                                 |
75| data     | [KVObject](#kvobject)               | Yes   | Additional data.                                   |
76| jsonPath | string                              | No   | Path to the [external.json](#about-the-externaljson-file) file that stores the template path. Request communication is not triggered when **jsonPath** is not empty or not set.|
77
78### RequestCallbackParameters
79
80Provides the result returned after the **PluginManager.Request** API is called.
81
82**Atomic service API**: This API can be used in atomic services since API version 12.
83
84**System capability**: SystemCapability.ArkUI.ArkUI.Full
85
86| Name               | Type                                      | Mandatory  | Description   |
87| ----------------- | ---------------------------------------- | ---- | ----- |
88| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | Yes   | Component template.|
89| data              | [KVObject](#kvobject)                    | Yes   | Component data.|
90| extraData         | [KVObject](#kvobject)                    | Yes   | Additional data.|
91
92### RequestEventResult
93
94Provides the result returned after the request listener is registered and the requested event is received.
95
96**Atomic service API**: This API can be used in atomic services since API version 12.
97
98**System capability**: SystemCapability.ArkUI.ArkUI.Full
99
100| Name       | Type                   | Mandatory  | Description   |
101| --------- | --------------------- | ---- | ----- |
102| template  | string                | No   | Component template.|
103| data      | [KVObject](#kvobject) | No   | Component data.|
104| extraData | [KVObject](#kvobject) | No   | Additional data.|
105
106### OnPushEventCallback
107
108type OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject,
109    extraData: KVObject) => void
110
111Registers the listener for the push event.
112
113**Atomic service API**: This API can be used in atomic services since API version 12.
114
115**System capability**: SystemCapability.ArkUI.ArkUI.Full
116
117**Parameters**
118
119| Name       | Type                                      | Mandatory  | Description                    |
120| --------- | ---------------------------------------- | ---- | ---------------------- |
121| source    | [Want](../apis-ability-kit/js-apis-application-want.md)      | Yes   | Information about the push request sender.        |
122| template  | [PluginComponentTemplate](#plugincomponenttemplate) | Yes   | Name of the request component template for the push request sender.|
123| data      | [KVObject](#kvobject)                    | Yes   | Data.                   |
124| extraData | [KVObject](#kvobject)                    | Yes   | Additional data.                 |
125
126**Example**
127
128```ts
129import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI';
130import { Want } from '@kit.AbilityKit';
131
132function onPushListener(source: Want, template: PluginComponentTemplate, data: pluginComponentManager.KVObject, extraData: pluginComponentManager.KVObject) {
133  console.log("onPushListener template.source=" + template.source);
134  console.log("onPushListener source=" + JSON.stringify(source));
135  console.log("onPushListener template=" + JSON.stringify(template));
136  console.log("onPushListener data=" + JSON.stringify(data));
137  console.log("onPushListener extraData=" + JSON.stringify(extraData));
138}
139```
140
141
142### OnRequestEventCallback
143
144type OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult
145
146Registers the listener for the request event.
147
148**Atomic service API**: This API can be used in atomic services since API version 12.
149
150**System capability**: SystemCapability.ArkUI.ArkUI.Full
151
152**Parameters**
153
154| Name       | Type                                 | Mandatory  | Description               |
155| --------- | ----------------------------------- | ---- | ----------------- |
156| source    | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes   | Information about the request sender.|
157| name      | string                              | Yes   | Template name.            |
158| data | [KVObject](#kvobject)               | Yes   | Additional data.            |
159
160**Return value**
161
162| Type                                      | Description                                                      |
163| ---------------------------------------- | --------------------------------------------------------- |
164| [RequestEventResult](#requesteventresult) | Provides the result returned after the request listener is registered and the requested event is received.|
165
166**Example**
167
168```ts
169import { pluginComponentManager } from '@kit.ArkUI';
170import { Want } from '@kit.AbilityKit';
171
172function onRequestListener(source: Want, name: string, data: pluginComponentManager.KVObject) {
173  console.error("onRequestListener");
174  console.log("onRequestListener source=" + JSON.stringify(source));
175  console.log("onRequestListener name=" + name);
176  console.log("onRequestListener data=" + JSON.stringify(data));
177  let RtnData: Record<string, string | pluginComponentManager.KVObject> = {
178    'template': "ets/pages/plugin.js",
179    'data': data,
180  }
181  return RtnData;
182}
183```
184
185### pluginComponentManager.push
186
187push(param: PushParameters , callback: AsyncCallback&lt;void&gt;): void
188
189Pushes the component and data to the component user.
190
191**Atomic service API**: This API can be used in atomic services since API version 12.
192
193**System capability**: SystemCapability.ArkUI.ArkUI.Full
194
195**Parameters**
196| Name     | Type                               | Mandatory  | Description          |
197| -------- | --------------------------------- | ---- | ------------ |
198| param    | [PushParameters](#pushparameters) | Yes   | Information about the component user. |
199| callback | AsyncCallback&lt;void&gt;         | Yes   | Asynchronous callback used to return the result.|
200
201**Example**
202
203```ts
204import { pluginComponentManager } from '@kit.ArkUI';
205pluginComponentManager.push(
206  {
207    want: {
208      bundleName: "com.example.provider",
209      abilityName: "com.example.provider.MainAbility",
210    },
211    name: "plugintemplate",
212    data: {
213      "key_1": "plugin component test",
214      "key_2": 34234,
215    },
216    extraData: {
217      "extra_str": "this is push event",
218    },
219    jsonPath: "",
220  },
221  (err, data) => {
222    console.log("push_callback: push ok!");
223  }
224)
225```
226
227### pluginComponentManager.request
228
229request(param: RequestParameters, callback: AsyncCallback&lt;RequestCallbackParameters&gt;): void
230
231Requests the component from the component provider.
232
233**Atomic service API**: This API can be used in atomic services since API version 12.
234
235**System capability**: SystemCapability.ArkUI.ArkUI.Full
236
237
238**Parameters**
239
240| Name  | Type                                                        | Mandatory| Description                                                        |
241| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
242| param    | [RequestParameters](#requestparameters)                      | Yes  | Information about the component request.                                    |
243| callback | AsyncCallback&lt;[RequestCallbackParameters](#requestcallbackparameters)&gt; | Yes  | Asynchronous callback used to return the requested data.|
244
245**Example**
246
247```ts
248import { pluginComponentManager } from '@kit.ArkUI';
249pluginComponentManager.request(
250  {
251    want: {
252      bundleName: "com.example.provider",
253      abilityName: "com.example.provider.MainAbility",
254    },
255    name: "plugintemplate",
256    data: {
257      "key_1": "plugin component test",
258      "key_2": 1111111,
259    },
260    jsonPath: "",
261  },
262  (err, data) => {
263    console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability);
264    console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source);
265    console.log("request_callback: data=" + JSON.stringify(data.data));
266    console.log("request_callback: extraData=" + JSON.stringify(data.extraData));
267  }
268)
269```
270
271### pluginComponentManager.on
272
273on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void
274
275Listens for events of the request type and returns the requested data, or listens for events of the push type and receives the data pushed by the provider.
276
277**Atomic service API**: This API can be used in atomic services since API version 12.
278
279**System capability**: SystemCapability.ArkUI.ArkUI.Full
280
281**Parameters**
282
283| Name      | Type                                      | Mandatory  | Description                                      |
284| --------- | ---------------------------------------- | ---- | ---------------------------------------- |
285| eventType | string                                   | Yes   | Type of the event to listen for. The options are as follows:<br>**"push"**: The component provider pushes data to the component user.<br>**"request"**: The component user proactively requests data from the component provider.|
286| callback  | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | Yes   | Callback used to return the result. The type is [OnPushEventCallback](#onpusheventcallback) for the push event and [OnRequestEventCallback](#onrequesteventcallback) for the request event.|
287
288**Example**
289
290```ts
291import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI';
292import { Want } from '@kit.AbilityKit';
293function onPushListener(source:Want, template:PluginComponentTemplate, data:pluginComponentManager.KVObject, extraData:pluginComponentManager.KVObject) {
294  console.log("onPushListener template.source=" + template.source);
295  console.log("onPushListener source=" + JSON.stringify(source));
296  console.log("onPushListener template=" + JSON.stringify(template));
297  console.log("onPushListener data=" + JSON.stringify(data));
298  console.log("onPushListener extraData=" + JSON.stringify(extraData));
299}
300function onRequestListener(source:Want, name:string, data:pluginComponentManager.KVObject) {
301  console.error("onRequestListener");
302  console.log("onRequestListener source=" + JSON.stringify(source));
303  console.log("onRequestListener name=" + name);
304  console.log("onRequestListener data=" + JSON.stringify(data));
305  let RtnData:Record<string,string|pluginComponentManager.KVObject> = { 'template': "ets/pages/plugin.js", 'data': data };
306  return RtnData;
307}
308pluginComponentManager.on("push", onPushListener);
309pluginComponentManager.on("request", onRequestListener);
310```
311
312## About the external.json File
313
314The **external.json** file is created by developers. It stores component names and template paths in key-value pairs. The component name is used as the keyword, and the corresponding template path is used as the value.
315
316**Example**
317
318```json
319{
320  "PluginProviderExample": "ets/pages/PluginProviderExample.js",
321  "plugintemplate2": "ets/pages/plugintemplate2.js"
322}
323
324```
325