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. For details about how to display the **PluginComponent** template, see [PluginComponent](../arkui-ts/ts-basic-components-plugincomponent.md). 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```js 12import pluginComponentManager from '@ohos.pluginComponent' 13``` 14 15## PluginComponentTemplate 16 17Describes the **PluginComponent** template parameters. 18 19**System capability**: SystemCapability.ArkUI.ArkUI.Full 20 21| Name | Type | Mandatory| Description | 22| ---------- | ------ | ---- | --------------------------- | 23| source | string | Yes | Component template name. | 24| bundleName | string | Yes | Bundle name of the provider ability.| 25 26 27## PluginComponentManager 28 29### KVObject 30 31Stores information in key-value pairs in JSON format. 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35 36| Value Range | Description | 37| --------------------- | ---------------------------------------- | 38| [key: string] | Keyword. The value is a string and can be an empty string.| 39| number | Key value of the number type. | 40| string | Key value of the string type. The value can be an empty string.| 41| boolean | Key value of the Boolean type. | 42| [] | Key value. The value can be []. | 43| [KVObject](#kvobject) | Key value of the KVObject type. | 44 45 46### PushParameters 47 48Sets the parameters to be passed in the **PluginManager.Push** API in the FA model. 49 50**Model restriction**: This API can be used only in the FA model. 51 52**System capability**: SystemCapability.ArkUI.ArkUI.Full 53 54| Name | Type | Mandatory| Description | 55| --------- | ----------------------------------- | ---- | -------------------------------------------------------------- | 56| want | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. | 57| name | string | Yes | Component name. | 58| data | [KVObject](#kvobject) | No | Component data value. | 59| extraData | [KVObject](#kvobject) | No | Additional data value. | 60| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.| 61 62### PushParameterForStage 63 64Sets the parameters to be passed in the **PluginManager.Push** API in the stage model. 65 66**Model restriction**: This API can be used only in the stage model. 67 68**System API**: This is a system API. 69 70**System capability**: SystemCapability.ArkUI.ArkUI.Full 71 72| Name | Type | Mandatory| Description | 73| --------- | ----------------------------------- | ---- | ---------------------------------------------------------------- | 74| owner | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. | 75| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. | 76| name | string | Yes | Component name. | 77| data | [KVObject](#kvobject) | No | Component data value. | 78| extraData | [KVObject](#kvobject) | No | Additional data value. | 79| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.| 80 81### RequestParameters 82 83Sets the parameters to be passed in the **PluginManager.Request** API in the FA model. 84 85**Model restriction**: This API can be used only in the FA model. 86 87**System capability**: SystemCapability.ArkUI.ArkUI.Full 88 89| Name | Type | Mandatory| Description | 90| -------- | ----------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- | 91| want | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. | 92| name | string | Yes | Name of the requested component. | 93| data | [KVObject](#kvobject) | Yes | Additional data. | 94| 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.| 95 96### RequestParameterForStage 97 98Sets the parameters to be passed in the **PluginManager.Request** API in the stage model. 99 100**System API**: This is a system API. 101 102**Model restriction**: This API can be used only in the stage model. 103 104**System capability**: SystemCapability.ArkUI.ArkUI.Full 105 106| Name | Type | Mandatory| Description | 107| -------- | ----------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- | 108| owner | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. | 109| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. | 110| name | string | Yes | Name of the requested component. | 111| data | [KVObject](#kvobject) | Yes | Additional data. | 112| 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.| 113 114### RequestCallbackParameters 115 116Provides the result returned after the **PluginManager.Request** API is called. 117 118**System capability**: SystemCapability.ArkUI.ArkUI.Full 119 120| Name | Type | Mandatory| Description | 121| ----------------- | ---------------------------------------------------- | ---- | ---------- | 122| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate)] | Yes | Component template.| 123| data | [KVObject](#kvobject) | Yes | Component data.| 124| extraData | [KVObject](#kvobject) | Yes | Additional data.| 125 126### RequestEventResult 127 128Provides the result returned after the request listener is registered and the requested event is received. 129 130**System capability**: SystemCapability.ArkUI.ArkUI.Full 131 132| Name | Type | Mandatory| Description | 133| --------- | --------------------- | ---- | ---------- | 134| template | string | No | Component template.| 135| data | [KVObject](#kvobject) | No | Component data.| 136| extraData | [KVObject](#kvobject) | No | Additional data.| 137 138### OnPushEventCallback 139 140OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, 141 extraData: KVObject) => void 142 143Registers the listener for the push event. 144 145**Parameters** 146 147| Name | Type | Mandatory| Description | 148| --------- | --------------------------------------------------- | ---- | ---------------------------------------- | 149| source | [Want](js-apis-application-want.md) | Yes | Information about the push request sender. | 150| template | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Name of the request component template for the push request sender.| 151| data | [KVObject](#kvobject) | Yes | Data. | 152| extraData | [KVObject](#kvobject) | Yes | Additional data. | 153 154**Example** 155 156```js 157function onPushListener(source, template, data, extraData) { 158 console.log("onPushListener template.source=" + template.source) 159 console.log("onPushListener source=" + JSON.stringify(source)) 160 console.log("onPushListener template=" + JSON.stringify(template)) 161 console.log("onPushListener data=" + JSON.stringify(data)) 162 console.log("onPushListener extraData=" + JSON.stringify(extraData)) 163} 164``` 165 166 167### OnRequestEventCallback 168 169OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult 170 171Registers the listener for the request event. 172 173**Parameters** 174 175| Name | Type | Mandatory| Description | 176| --------- | ----------------------------------- | ---- | --------------------------- | 177| source | [Want](js-apis-application-want.md) | Yes | Information about the request sender.| 178| data | [KVObject](#kvobject) | Yes | Data. | 179| extraData | [KVObject](#kvobject) | Yes | Additional data. | 180 181**Example** 182 183```js 184function onRequestListener(source, name, data) 185{ 186 console.error("onRequestListener"); 187 console.log("onRequestListener source=" + JSON.stringify(source)); 188 console.log("onRequestListener name=" + name); 189 console.log("onRequestListener data=" + JSON.stringify(data)); 190 191 return {template:"ets/pages/plugin.js", data:data}; 192} 193``` 194 195### push 196 197push(param: PushParameters , callback: AsyncCallback<void>): void 198 199Pushes the component and data to the component user. 200 201**Model restriction**: This API can be used only in the FA model. 202 203**Parameters** 204| Name | Type | Mandatory| Description | 205| -------- | --------------------------------- | ---- | ------------------------ | 206| param | [PushParameters](#pushparameters) | Yes | Information about the component user. | 207| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.| 208 209**Example** 210 211```js 212pluginComponentManager.push( 213{ 214 want: { 215 bundleName: "com.example.provider", 216 abilityName: "com.example.provider.MainAbility", 217 }, 218 name: "plugintemplate", 219 data: { 220 "key_1": "plugin component test", 221 "key_2": 34234 222 }, 223 extraData: { 224 "extra_str": "this is push event" 225 }, 226 jsonPath: "", 227 }, 228 (err, data) => { 229 console.log("push_callback: push ok!"); 230 } 231) 232``` 233 234### push 235 236push(param: PushParameterForStage, callback: AsyncCallback<void>): void 237 238Pushes the component and data to the component user. 239 240**System API**: This is a system API. 241 242**Model restriction**: This API can be used only in the stage model. 243 244**Parameters** 245| Name | Type | Mandatory| Description | 246| -------- | ----------------------------------------------- | ---- | ------------------------ | 247| param | [PushParameterForStage](#pushparameterforstage) | Yes | Information about the component user. | 248| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.| 249 250**Example** 251 252```js 253pluginComponentManager.push( 254 { 255 owner:{ 256 bundleName:"com.example.provider", 257 abilityName:"com.example.provider.MainAbility" 258 }, 259 target: { 260 bundleName: "com.example.provider", 261 abilityName: "com.example.provider.MainAbility", 262 }, 263 name: "ets/pages/plugin2.js", 264 data: { 265 "js": "ets/pages/plugin.js", 266 "key_1": 1111, , 267 }, 268 extraData: { 269 "extra_str": "this is push event" 270 }, 271 jsonPath: "", 272 }, 273 (err, data) => { 274 console.log("push_callback:err: " ,JSON.stringify(err)); 275 console.log("push_callback:data: " , JSON.stringify(data)); 276 console.log("push_callback: push ok!"); 277 } 278) 279``` 280 281 282### request 283 284request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void 285 286Requests the component from the component provider. 287 288**Model restriction**: This API can be used only in the FA model. 289 290 291**Parameters** 292 293| Name | Type | Mandatory| Description | 294| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 295| param | [RequestParameters](#requestparameters) | Yes | Information about the component request. | 296| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.| 297 298**Example** 299 300```js 301pluginComponentManager.request( 302 { 303 want: { 304 bundleName: "com.example.provider", 305 abilityName: "com.example.provider.MainAbility", 306 }, 307 name: "plugintemplate", 308 data: { 309 "key_1": "plugin component test", 310 "key_2": 1111111 311 }, 312 jsonPath: "", 313 }, 314 (err, data) => { 315 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 316 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 317 console.log("request_callback: data=" + JSON.stringify(data.data)) 318 console.log("request_callback: extraData=" + JSON.stringify(data.extraData)) 319 } 320) 321``` 322 323 324### request 325 326request(param: RequestParameterForStage, callback: AsyncCallback<RequestCallbackParameters>): void 327 328Requests the component from the component provider. 329 330**System API**: This is a system API. 331 332**Model restriction**: This API can be used only in the stage model. 333 334**Parameters** 335 336| Name | Type | Mandatory| Description | 337| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 338| param | [RequestParameterForStage](#requestparameterforstage) | Yes | Information about the component request. | 339| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.| 340 341**Example** 342 343```js 344pluginComponentManager.request( 345 { 346 owner:{ 347 bundleName:"com.example.provider", 348 abilityName:"com.example.provider.MainAbility" 349 }, 350 target: { 351 bundleName: "com.example.provider", 352 abilityName: "ets/pages/plugin2.js", 353 }, 354 name: "plugintemplate", 355 data: { 356 "key_1": " myapplication plugin component test", 357 }, 358 jsonPath: "", 359 }, 360 (err, data) => { 361 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 362 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 363 } 364) 365``` 366 367### on 368 369on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void 370 371Listens 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. 372 373**Parameters** 374 375| Name | Type | Mandatory| Description | 376| --------- | ---------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | 377| 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. | 378| 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.| 379 380 381**Example** 382 383```js 384 pluginComponentManager.on("push", onPushListener) 385 pluginComponentManager.on("request", onRequestListener) 386``` 387 388## About the external.json File 389 390The **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. 391 392**Example** 393 394```json 395{ 396 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 397 "plugintemplate2": "ets/pages/plugintemplate2.js" 398} 399 400```