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 '@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](../apis-ability-kit/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### RequestParameters 63 64Sets the parameters to be passed in the **PluginManager.Request** API in the FA model. 65 66**Model restriction**: This API can be used only in the FA model. 67 68**System capability**: SystemCapability.ArkUI.ArkUI.Full 69 70| Name | Type | Mandatory | Description | 71| -------- | ----------------------------------- | ---- | ---------------------------------------- | 72| want | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes | Ability information of the component provider. | 73| name | string | Yes | Name of the requested component. | 74| data | [KVObject](#kvobject) | Yes | Additional data. | 75| 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.| 76 77### RequestCallbackParameters 78 79Provides the result returned after the **PluginManager.Request** API is called. 80 81**System capability**: SystemCapability.ArkUI.ArkUI.Full 82 83| Name | Type | Mandatory | Description | 84| ----------------- | ---------------------------------------- | ---- | ----- | 85| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Component template.| 86| data | [KVObject](#kvobject) | Yes | Component data.| 87| extraData | [KVObject](#kvobject) | Yes | Additional data.| 88 89### RequestEventResult 90 91Provides the result returned after the request listener is registered and the requested event is received. 92 93**System capability**: SystemCapability.ArkUI.ArkUI.Full 94 95| Name | Type | Mandatory | Description | 96| --------- | --------------------- | ---- | ----- | 97| template | string | No | Component template.| 98| data | [KVObject](#kvobject) | No | Component data.| 99| extraData | [KVObject](#kvobject) | No | Additional data.| 100 101### OnPushEventCallback 102 103OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, 104 extraData: KVObject) => void 105 106Registers the listener for the push event. 107 108**Parameters** 109 110| Name | Type | Mandatory | Description | 111| --------- | ---------------------------------------- | ---- | ---------------------- | 112| source | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes | Information about the push request sender. | 113| template | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Name of the request component template for the push request sender.| 114| data | [KVObject](#kvobject) | Yes | Data. | 115| extraData | [KVObject](#kvobject) | Yes | Additional data. | 116 117**Example** 118 119```ts 120import pluginComponentManager from '@ohos.pluginComponent' 121import Want from '@ohos.app.ability.Want'; 122import PluginComponentTemplate from '@ohos.pluginComponent' 123function onPushListener(source: Want, template: PluginComponentTemplate, data: pluginComponentManager.KVObject, extraData: pluginComponentManager.KVObject) { 124 console.log("onPushListener template.source=" + template.source) 125 console.log("onPushListener source=" + JSON.stringify(source)) 126 console.log("onPushListener template=" + JSON.stringify(template)) 127 console.log("onPushListener data=" + JSON.stringify(data)) 128 console.log("onPushListener extraData=" + JSON.stringify(extraData)) 129} 130``` 131 132 133### OnRequestEventCallback 134 135OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult 136 137Registers the listener for the request event. 138 139**Parameters** 140 141| Name | Type | Mandatory | Description | 142| --------- | ----------------------------------- | ---- | ----------------- | 143| source | [Want](../apis-ability-kit/js-apis-application-want.md) | Yes | Information about the request sender.| 144| name | string | Yes | Template name. | 145| extraData | [KVObject](#kvobject) | Yes | Additional data. | 146 147**Example** 148 149```ts 150import pluginComponentManager from '@ohos.pluginComponent' 151import Want from '@ohos.app.ability.Want'; 152function onRequestListener(source:Want, name:string, data:pluginComponentManager.KVObject) { 153 console.error("onRequestListener"); 154 console.log("onRequestListener source=" + JSON.stringify(source)); 155 console.log("onRequestListener name=" + name); 156 console.log("onRequestListener data=" + JSON.stringify(data)); 157 let RtnData:Record<string,string|pluginComponentManager.KVObject> = { 'template': "ets/pages/plugin.js", 'data': data } 158 return RtnData; 159} 160``` 161 162### push 163 164push(param: PushParameters , callback: AsyncCallback<void>): void 165 166Pushes the component and data to the component user. 167 168**Model restriction**: This API can be used only in the FA model. 169 170**Parameters** 171| Name | Type | Mandatory | Description | 172| -------- | --------------------------------- | ---- | ------------ | 173| param | [PushParameters](#pushparameters) | Yes | Information about the component user. | 174| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.| 175 176**Example** 177 178```ts 179import pluginComponentManager from '@ohos.pluginComponent' 180pluginComponentManager.push( 181 { 182 want: { 183 bundleName: "com.example.provider", 184 abilityName: "com.example.provider.MainAbility", 185 }, 186 name: "plugintemplate", 187 data: { 188 "key_1": "plugin component test", 189 "key_2": 34234 190 }, 191 extraData: { 192 "extra_str": "this is push event" 193 }, 194 jsonPath: "", 195 }, 196 (err, data) => { 197 console.log("push_callback: push ok!"); 198 } 199) 200``` 201 202### request 203 204request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void 205 206Requests the component from the component provider. 207 208**Model restriction**: This API can be used only in the FA model. 209 210 211**Parameters** 212 213| Name | Type | Mandatory | Description | 214| -------- | ---------------------------------------- | ---- | ----------------------------------- | 215| param | [RequestParameters](#requestparameters) | Yes | Information about the component request. | 216| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.| 217 218**Example** 219 220```ts 221import pluginComponentManager from '@ohos.pluginComponent' 222pluginComponentManager.request( 223 { 224 want: { 225 bundleName: "com.example.provider", 226 abilityName: "com.example.provider.MainAbility", 227 }, 228 name: "plugintemplate", 229 data: { 230 "key_1": "plugin component test", 231 "key_2": 1111111 232 }, 233 jsonPath: "", 234 }, 235 (err, data) => { 236 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 237 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 238 console.log("request_callback: data=" + JSON.stringify(data.data)) 239 console.log("request_callback: extraData=" + JSON.stringify(data.extraData)) 240 } 241) 242``` 243 244### on 245 246on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void 247 248Listens 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. 249 250**Parameters** 251 252| Name | Type | Mandatory | Description | 253| --------- | ---------------------------------------- | ---- | ---------------------------------------- | 254| 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.| 255| 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.| 256 257**Example** 258 259```ts 260import pluginComponentManager from '@ohos.pluginComponent' 261import Want from '@ohos.app.ability.Want'; 262import {PluginComponentTemplate} from '@ohos.pluginComponent' 263function onPushListener(source:Want, template:PluginComponentTemplate, data:pluginComponentManager.KVObject, extraData:pluginComponentManager.KVObject) { 264 console.log("onPushListener template.source=" + template.source) 265 console.log("onPushListener source=" + JSON.stringify(source)) 266 console.log("onPushListener template=" + JSON.stringify(template)) 267 console.log("onPushListener data=" + JSON.stringify(data)) 268 console.log("onPushListener extraData=" + JSON.stringify(extraData)) 269} 270function onRequestListener(source:Want, name:string, data:pluginComponentManager.KVObject) { 271 console.error("onRequestListener"); 272 console.log("onRequestListener source=" + JSON.stringify(source)); 273 console.log("onRequestListener name=" + name); 274 console.log("onRequestListener data=" + JSON.stringify(data)); 275 let RtnData:Record<string,string|pluginComponentManager.KVObject> = { 'template': "ets/pages/plugin.js", 'data': data } 276 return RtnData; 277} 278pluginComponentManager.on("push", onPushListener) 279pluginComponentManager.on("request", onRequestListener) 280``` 281 282## About the external.json File 283 284The **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. 285 286**Example** 287 288```json 289{ 290 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 291 "plugintemplate2": "ets/pages/plugintemplate2.js" 292} 293 294``` 295