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
36Stores information in key-value pairs in 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
43| Value Range             | Description                                    |
44| --------------------- | ---------------------------------------- |
45| [key: string]         | Keyword. The value is a string and can be an empty string. |
46| number                | Key value of the number type.                |
47| string                | Key value of the string type. The value can be an empty string. |
48| boolean               | Key value of the Boolean type.              |
49| []                    | Key value. The value can be [].                      |
50| [KVObject](#kvobject) | Key value of the KVObject type.            |
51
52
53### PushParameters
54
55Sets the parameters to be passed in the **PluginManager.Push** API in the FA model.
56
57**Model restriction**: This API can be used only in the FA model.
58
59**Atomic service API**: This API can be used in atomic services since API version 12.
60
61**System capability**: SystemCapability.ArkUI.ArkUI.Full
62
63| Name       | Type                                 | Mandatory  | Description                                      |
64| --------- | ----------------------------------- | ---- | ---------------------------------------- |
65| want      | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes   | Ability information of the component user.                         |
66| name      | string                              | Yes   | Component name.                                   |
67| data      | [KVObject](#kvobject)               | Yes   | Component data value.                                  |
68| extraData | [KVObject](#kvobject)               | Yes   | Additional data value.                                  |
69| jsonPath  | string                              | No   | Path to the [external.json](#about-the-externaljson-file) file that stores the template path. |
70
71### RequestParameters
72
73Sets the parameters to be passed in the **PluginManager.Request** API in the FA model.
74
75**Model restriction**: This API can be used only in the FA model.
76
77**Atomic service API**: This API can be used in atomic services since API version 12.
78
79**System capability**: SystemCapability.ArkUI.ArkUI.Full
80
81| Name      | Type                                 | Mandatory  | Description                                      |
82| -------- | ----------------------------------- | ---- | ---------------------------------------- |
83| want     | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes   | Ability information of the component provider.                         |
84| name     | string                              | Yes   | Name of the requested component.                                 |
85| data     | [KVObject](#kvobject)               | Yes   | Additional data.                                   |
86| 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. |
87
88### RequestCallbackParameters
89
90Provides the result returned after the **PluginManager.Request** API is called.
91
92**Atomic service API**: This API can be used in atomic services since API version 12.
93
94**System capability**: SystemCapability.ArkUI.ArkUI.Full
95
96| Name               | Type                                      | Mandatory  | Description   |
97| ----------------- | ---------------------------------------- | ---- | ----- |
98| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | Yes   | Component template. |
99| data              | [KVObject](#kvobject)                    | Yes   | Component data. |
100| extraData         | [KVObject](#kvobject)                    | Yes   | Additional data. |
101
102### RequestEventResult
103
104Provides the result returned after the request listener is registered and the requested event is received.
105
106**Atomic service API**: This API can be used in atomic services since API version 12.
107
108**System capability**: SystemCapability.ArkUI.ArkUI.Full
109
110| Name       | Type                   | Mandatory  | Description   |
111| --------- | --------------------- | ---- | ----- |
112| template  | string                | No   | Component template. |
113| data      | [KVObject](#kvobject) | No   | Component data. |
114| extraData | [KVObject](#kvobject) | No   | Additional data. |
115
116### OnPushEventCallback
117
118type OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject,
119    extraData: KVObject) => void
120
121Registers the listener for the push event.
122
123**Atomic service API**: This API can be used in atomic services since API version 12.
124
125**Parameters**
126
127| Name       | Type                                      | Mandatory  | Description                    |
128| --------- | ---------------------------------------- | ---- | ---------------------- |
129| source    | [Want](../apis-ability-kit/js-apis-application-want.md)      | Yes   | Information about the push request sender.        |
130| template  | [PluginComponentTemplate](#plugincomponenttemplate) | Yes   | Name of the request component template for the push request sender. |
131| data      | [KVObject](#kvobject)                    | Yes   | Data.                   |
132| extraData | [KVObject](#kvobject)                    | Yes   | Additional data.                 |
133
134**Example**
135
136```ts
137import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI'
138import { Want } from '@kit.AbilityKit';
139
140function onPushListener(source: Want, template: PluginComponentTemplate, data: pluginComponentManager.KVObject, extraData: pluginComponentManager.KVObject) {
141  console.log("onPushListener template.source=" + template.source)
142  console.log("onPushListener source=" + JSON.stringify(source))
143  console.log("onPushListener template=" + JSON.stringify(template))
144  console.log("onPushListener data=" + JSON.stringify(data))
145  console.log("onPushListener extraData=" + JSON.stringify(extraData))
146}
147```
148
149
150### OnRequestEventCallback
151
152type OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult
153
154Registers the listener for the request event.
155
156**Atomic service API**: This API can be used in atomic services since API version 12.
157
158**Parameters**
159
160| Name       | Type                                 | Mandatory  | Description               |
161| --------- | ----------------------------------- | ---- | ----------------- |
162| source    | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes   | Information about the request sender. |
163| name      | string                              | Yes   | Template name.            |
164| extraData | [KVObject](#kvobject)               | Yes   | Additional data.            |
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### push
186
187push(param: PushParameters , callback: AsyncCallback&lt;void&gt;): void
188
189Pushes the component and data to the component user.
190
191**Model restriction**: This API can be used only in the FA model.
192
193**Atomic service API**: This API can be used in atomic services since API version 12.
194
195**System capability**: SystemCapability.ArkUI.ArkUI.Full
196
197**Parameters**
198| Name     | Type                               | Mandatory  | Description          |
199| -------- | --------------------------------- | ---- | ------------ |
200| param    | [PushParameters](#pushparameters) | Yes   | Information about the component user. |
201| callback | AsyncCallback&lt;void&gt;         | Yes   | Asynchronous callback used to return the result. |
202
203**Example**
204
205```ts
206import { pluginComponentManager } from '@kit.ArkUI'
207pluginComponentManager.push(
208  {
209    want: {
210      bundleName: "com.example.provider",
211      abilityName: "com.example.provider.MainAbility",
212    },
213    name: "plugintemplate",
214    data: {
215      "key_1": "plugin component test",
216      "key_2": 34234
217    },
218    extraData: {
219      "extra_str": "this is push event"
220    },
221    jsonPath: "",
222  },
223  (err, data) => {
224    console.log("push_callback: push ok!");
225  }
226)
227```
228
229### request
230
231request(param: RequestParameters, callback: AsyncCallback&lt;RequestCallbackParameters&gt;): void
232
233Requests the component from the component provider.
234
235**Model restriction**: This API can be used only in the FA model.
236
237**Atomic service API**: This API can be used in atomic services since API version 12.
238
239**System capability**: SystemCapability.ArkUI.ArkUI.Full
240
241
242**Parameters**
243
244| Name  | Type                                                        | Mandatory | Description                                                        |
245| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
246| param    | [RequestParameters](#requestparameters)                      | Yes  | Information about the component request.                                    |
247| callback | AsyncCallback&lt;[RequestCallbackParameters](#requestcallbackparameters)&gt; | Yes  | Asynchronous callback used to return the requested data. |
248
249**Example**
250
251```ts
252import { pluginComponentManager } from '@kit.ArkUI'
253pluginComponentManager.request(
254  {
255    want: {
256      bundleName: "com.example.provider",
257      abilityName: "com.example.provider.MainAbility",
258    },
259    name: "plugintemplate",
260    data: {
261      "key_1": "plugin component test",
262      "key_2": 1111111
263    },
264    jsonPath: "",
265  },
266  (err, data) => {
267    console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability)
268    console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source)
269    console.log("request_callback: data=" + JSON.stringify(data.data))
270    console.log("request_callback: extraData=" + JSON.stringify(data.extraData))
271  }
272)
273```
274
275### on
276
277on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void
278
279Listens 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.
280
281**Atomic service API**: This API can be used in atomic services since API version 12.
282
283**System capability**: SystemCapability.ArkUI.ArkUI.Full
284
285**Parameters**
286
287| Name      | Type                                      | Mandatory  | Description                                      |
288| --------- | ---------------------------------------- | ---- | ---------------------------------------- |
289| 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 consumer.<br>**"request"**: The component consumer proactively requests data from the component provider. |
290| 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. |
291
292**Example**
293
294```ts
295import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI'
296import { Want } from '@kit.AbilityKit';
297function onPushListener(source:Want, template:PluginComponentTemplate, data:pluginComponentManager.KVObject, extraData:pluginComponentManager.KVObject) {
298  console.log("onPushListener template.source=" + template.source)
299  console.log("onPushListener source=" + JSON.stringify(source))
300  console.log("onPushListener template=" + JSON.stringify(template))
301  console.log("onPushListener data=" + JSON.stringify(data))
302  console.log("onPushListener extraData=" + JSON.stringify(extraData))
303}
304function onRequestListener(source:Want, name:string, data:pluginComponentManager.KVObject) {
305  console.error("onRequestListener");
306  console.log("onRequestListener source=" + JSON.stringify(source));
307  console.log("onRequestListener name=" + name);
308  console.log("onRequestListener data=" + JSON.stringify(data));
309  let RtnData:Record<string,string|pluginComponentManager.KVObject> = { 'template': "ets/pages/plugin.js", 'data': data }
310  return RtnData;
311}
312pluginComponentManager.on("push", onPushListener)
313pluginComponentManager.on("request", onRequestListener)
314```
315
316## About the external.json File
317
318The **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.
319
320**Example**
321
322```json
323{
324  "PluginProviderExample": "ets/pages/PluginProviderExample.js",
325  "plugintemplate2": "ets/pages/plugintemplate2.js"
326}
327
328```
329