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<void>): 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<void> | 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<RequestCallbackParameters>): 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<[RequestCallbackParameters](#requestcallbackparameters)> | 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