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) | Yes | Component data value. | 59| extraData | [KVObject](#kvobject) | Yes | 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) | Yes | Component data value. | 78| extraData | [KVObject](#kvobject) | Yes | 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| name | string | Yes | Template name. | 179| extraData | [KVObject](#kvobject) | Yes | Additional data. | 180 181**Example** 182 183```js 184function onRequestListener(source, name, data) { 185 console.error("onRequestListener"); 186 console.log("onRequestListener source=" + JSON.stringify(source)); 187 console.log("onRequestListener name=" + name); 188 console.log("onRequestListener data=" + JSON.stringify(data)); 189 190 return { template: "ets/pages/plugin.js", data: data }; 191} 192``` 193 194### push 195 196push(param: PushParameters , callback: AsyncCallback<void>): void 197 198Pushes the component and data to the component user. 199 200**Model restriction**: This API can be used only in the FA model. 201 202**Parameters** 203| Name | Type | Mandatory| Description | 204| -------- | --------------------------------- | ---- | ------------------------ | 205| param | [PushParameters](#pushparameters) | Yes | Information about the component user. | 206| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.| 207 208**Example** 209 210```js 211pluginComponentManager.push( 212 { 213 want: { 214 bundleName: "com.example.provider", 215 abilityName: "com.example.provider.MainAbility", 216 }, 217 name: "plugintemplate", 218 data: { 219 "key_1": "plugin component test", 220 "key_2": 34234 221 }, 222 extraData: { 223 "extra_str": "this is push event" 224 }, 225 jsonPath: "", 226 }, 227 (err, data) => { 228 console.log("push_callback: push ok!"); 229 } 230) 231``` 232 233### push 234 235push(param: PushParameterForStage, callback: AsyncCallback<void>): void 236 237Pushes the component and data to the component user. 238 239**System API**: This is a system API. 240 241**Model restriction**: This API can be used only in the stage model. 242 243**Parameters** 244| Name | Type | Mandatory| Description | 245| -------- | ----------------------------------------------- | ---- | ------------------------ | 246| param | [PushParameterForStage](#pushparameterforstage) | Yes | Information about the component user. | 247| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.| 248 249**Example** 250 251```js 252pluginComponentManager.push( 253 { 254 owner: { 255 bundleName: "com.example.provider", 256 abilityName: "com.example.provider.MainAbility" 257 }, 258 target: { 259 bundleName: "com.example.provider", 260 abilityName: "com.example.provider.MainAbility", 261 }, 262 name: "ets/pages/plugin2.js", 263 data: { 264 "js": "ets/pages/plugin.js", 265 "key_1": 1111, , 266 }, 267 extraData: { 268 "extra_str": "this is push event" 269 }, 270 jsonPath: "", 271 }, 272 (err, data) => { 273 console.log("push_callback:err: ", JSON.stringify(err)); 274 console.log("push_callback:data: ", JSON.stringify(data)); 275 console.log("push_callback: push ok!"); 276 } 277) 278``` 279 280 281### request 282 283request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void 284 285Requests the component from the component provider. 286 287**Model restriction**: This API can be used only in the FA model. 288 289 290**Parameters** 291 292| Name | Type | Mandatory| Description | 293| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 294| param | [RequestParameters](#requestparameters) | Yes | Information about the component request. | 295| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.| 296 297**Example** 298 299```js 300pluginComponentManager.request( 301 { 302 want: { 303 bundleName: "com.example.provider", 304 abilityName: "com.example.provider.MainAbility", 305 }, 306 name: "plugintemplate", 307 data: { 308 "key_1": "plugin component test", 309 "key_2": 1111111 310 }, 311 jsonPath: "", 312 }, 313 (err, data) => { 314 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 315 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 316 console.log("request_callback: data=" + JSON.stringify(data.data)) 317 console.log("request_callback: extraData=" + JSON.stringify(data.extraData)) 318 } 319) 320``` 321 322 323### request 324 325request(param: RequestParameterForStage, callback: AsyncCallback<RequestCallbackParameters>): void 326 327Requests the component from the component provider. 328 329**System API**: This is a system API. 330 331**Model restriction**: This API can be used only in the stage model. 332 333**Parameters** 334 335| Name | Type | Mandatory| Description | 336| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 337| param | [RequestParameterForStage](#requestparameterforstage) | Yes | Information about the component request. | 338| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.| 339 340**Example** 341 342```js 343pluginComponentManager.request( 344 { 345 owner: { 346 bundleName: "com.example.provider", 347 abilityName: "com.example.provider.MainAbility" 348 }, 349 target: { 350 bundleName: "com.example.provider", 351 abilityName: "ets/pages/plugin2.js", 352 }, 353 name: "plugintemplate", 354 data: { 355 "key_1": " myapplication plugin component test", 356 }, 357 jsonPath: "", 358 }, 359 (err, data) => { 360 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 361 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 362 } 363) 364``` 365 366### on 367 368on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void 369 370Listens 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. 371 372**Parameters** 373 374| Name | Type | Mandatory| Description | 375| --------- | ---------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | 376| 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. | 377| 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.| 378 379 380**Example** 381 382```js 383pluginComponentManager.on("push", onPushListener) 384pluginComponentManager.on("request", onRequestListener) 385``` 386 387## About the external.json File 388 389The **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. 390 391**Example** 392 393```json 394{ 395 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 396 "plugintemplate2": "ets/pages/plugintemplate2.js" 397} 398 399```