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| Type | 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 55Defines the parameters required when using the **PluginManager.Push** API. 56 57**Atomic service API**: This API can be used in atomic services since API version 12. 58 59**System capability**: SystemCapability.ArkUI.ArkUI.Full 60 61| Name | Type | Mandatory | Description | 62| --------- | ----------------------------------- | ---- | ---------------------------------------- | 63| want | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes | Ability information of the component user. | 64| name | string | Yes | Component name. | 65| data | [KVObject](#kvobject) | Yes | Component data value. | 66| extraData | [KVObject](#kvobject) | Yes | Additional data value. | 67| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.| 68 69### RequestParameters 70 71Defines the parameters required when using the **PluginManager.Request** API. 72 73**Atomic service API**: This API can be used in atomic services since API version 12. 74 75**System capability**: SystemCapability.ArkUI.ArkUI.Full 76 77| Name | Type | Mandatory | Description | 78| -------- | ----------------------------------- | ---- | ---------------------------------------- | 79| want | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes | Ability information of the component provider. | 80| name | string | Yes | Name of the requested component. | 81| data | [KVObject](#kvobject) | Yes | Additional data. | 82| 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.| 83 84### RequestCallbackParameters 85 86Provides the result returned after the **PluginManager.Request** API is called. 87 88**Atomic service API**: This API can be used in atomic services since API version 12. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92| Name | Type | Mandatory | Description | 93| ----------------- | ---------------------------------------- | ---- | ----- | 94| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Component template.| 95| data | [KVObject](#kvobject) | Yes | Component data.| 96| extraData | [KVObject](#kvobject) | Yes | Additional data.| 97 98### RequestEventResult 99 100Provides the result returned after the request listener is registered and the requested event is received. 101 102**Atomic service API**: This API can be used in atomic services since API version 12. 103 104**System capability**: SystemCapability.ArkUI.ArkUI.Full 105 106| Type | Description | 107| --------------------- | ----- | 108| string | Component template.| 109| [KVObject](#kvobject) | Component data.| 110| [KVObject](#kvobject) | Additional data.| 111 112### OnPushEventCallback 113 114type OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, 115 extraData: KVObject) => void 116 117Registers the listener for the push event. 118 119**Atomic service API**: This API can be used in atomic services since API version 12. 120 121**System capability**: SystemCapability.ArkUI.ArkUI.Full 122 123**Parameters** 124 125| Name | Type | Mandatory | Description | 126| --------- | ---------------------------------------- | ---- | ---------------------- | 127| source | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes | Information about the push request sender. | 128| template | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Name of the request component template for the push request sender.| 129| data | [KVObject](#kvobject) | Yes | Data. | 130| extraData | [KVObject](#kvobject) | Yes | Additional data. | 131 132**Example** 133 134```ts 135import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI' 136import { Want } from '@kit.AbilityKit'; 137 138function onPushListener(source: Want, template: PluginComponentTemplate, data: pluginComponentManager.KVObject, extraData: pluginComponentManager.KVObject) { 139 console.log("onPushListener template.source=" + template.source) 140 console.log("onPushListener source=" + JSON.stringify(source)) 141 console.log("onPushListener template=" + JSON.stringify(template)) 142 console.log("onPushListener data=" + JSON.stringify(data)) 143 console.log("onPushListener extraData=" + JSON.stringify(extraData)) 144} 145``` 146 147 148### OnRequestEventCallback 149 150type OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult 151 152Registers the listener for the request event. 153 154**Atomic service API**: This API can be used in atomic services since API version 12. 155 156**System capability**: SystemCapability.ArkUI.ArkUI.Full 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| data | [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### pluginComponentManager.push 186 187push(param: PushParameters , callback: AsyncCallback<void>): 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<void> | 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<RequestCallbackParameters>): 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<[RequestCallbackParameters](#requestcallbackparameters)> | 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