1# @ohos.pluginComponent (PluginComponentManager) 2 3用于给插件组件的使用方请求组件与数据，使用方发送组件模板和数据。 4 5> **说明：** 6> 7> - 本模块首批接口从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 导入模块 10 11```ts 12import { pluginComponentManager } from '@kit.ArkUI' 13``` 14 15## PluginComponentTemplate 16 17Plugin组件模板参数。 18 19**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 20 21**系统能力：** SystemCapability.ArkUI.ArkUI.Full 22 23| 名称 | 类型 | 必填 | 说明 | 24| ------- | ------ | ---- | --------------------------- | 25| source | string | 是 | 组件模板名。 | 26| ability | string | 是 | 提供方Ability的bundleName。 | 27 28## pluginComponentManager 29 30插件组件管理器。 31 32### KVObject 33 34type KVObject = { [key: string]: number | string | boolean | [] | KVObject } 35 36以键值对形式存储信息，符合json格式。 37 38**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 39 40**系统能力：** SystemCapability.ArkUI.ArkUI.Full 41 42| 名称 | 类型 | 必填 | 说明 | 43| ------- | ------ | ---- | --------------------------- | 44| [key: string] | number \| string \| boolean \| [] \| [KVObject](#kvobject) | 是 | 键值对形式存储。<br/>number：键值，表示值类型为数字。<br/> string：键值，表示值类型为字符串，可取空字符串。<br/> boolean：键值，表示值类型为布尔值。<br/> []：键值，可取值为[]。<br/>[KVObject](#kvobject)：键值，表示值类型为KVObject。 | 45 46 47### PushParameters 48 49使用PluginManager.Push方法时候的需要传递的参数。 50 51**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55| 名称 | 类型 | 必填 | 说明 | 56| --------- | ----------------------------------- | ---- | ---------------------------------------- | 57| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | 组件使用方Ability信息。 | 58| name | string | 是 | 组件名称。 | 59| data | [KVObject](#kvobject) | 是 | 组件数据值。 | 60| extraData | [KVObject](#kvobject) | 是 | 附加数据值。 | 61| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)件的路径。 | 62 63### RequestParameters 64 65使用PluginManager.Request方法时候的需要传递的参数。 66 67**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 68 69**系统能力：** SystemCapability.ArkUI.ArkUI.Full 70 71| 名称 | 类型 | 必填 | 说明 | 72| -------- | ----------------------------------- | ---- | ---------------------------------------- | 73| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | 组件提供方Ability信息。 | 74| name | string | 是 | 请求组件名称。 | 75| data | [KVObject](#kvobject) | 是 | 附加数据。 | 76| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)文件的路径。jsonPath字段不为空或者未设置的时候不触发Request通信。 | 77 78### RequestCallbackParameters 79 80PluginManager.Request方法时候接收到的回调结果。 81 82**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.ArkUI.ArkUI.Full 85 86| 名称 | 类型 | 必填 | 说明 | 87| ----------------- | ---------------------------------------- | ---- | ----- | 88| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | 是 | 组件模板。 | 89| data | [KVObject](#kvobject) | 是 | 组件数据。 | 90| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 91 92### RequestEventResult 93 94注册Request监听方法后，接受到的请求事件时候回应请求的数据类型。 95 96**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 97 98**系统能力：** SystemCapability.ArkUI.ArkUI.Full 99 100| 名称 | 类型 | 必填 | 说明 | 101| --------- | --------------------- | ---- | ----- | 102| template | string | 否 | 组件模板。 | 103| data | [KVObject](#kvobject) | 否 | 组件数据。 | 104| extraData | [KVObject](#kvobject) | 否 | 附加数据。 | 105 106### OnPushEventCallback 107 108type OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, 109 extraData: KVObject) => void 110 111对应Push事件的监听回调函数。 112 113**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 114 115**系统能力：** SystemCapability.ArkUI.ArkUI.Full 116 117**参数：** 118 119| 参数名 | 类型 | 必填 | 说明 | 120| --------- | ---------------------------------------- | ---- | ---------------------- | 121| source | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | Push请求发送方相关信息。 | 122| template | [PluginComponentTemplate](#plugincomponenttemplate) | 是 | Push请求发送方相关信息请求组件模板名称。 | 123| data | [KVObject](#kvobject) | 是 | 数据。 | 124| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 125 126**示例：** 127 128```ts 129import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI' 130import { Want } from '@kit.AbilityKit'; 131 132function onPushListener(source: Want, template: PluginComponentTemplate, data: pluginComponentManager.KVObject, extraData: pluginComponentManager.KVObject) { 133 console.log("onPushListener template.source=" + template.source) 134 console.log("onPushListener source=" + JSON.stringify(source)) 135 console.log("onPushListener template=" + JSON.stringify(template)) 136 console.log("onPushListener data=" + JSON.stringify(data)) 137 console.log("onPushListener extraData=" + JSON.stringify(extraData)) 138} 139``` 140 141 142### OnRequestEventCallback 143 144type OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult 145 146对应request事件的监听回调函数。 147 148**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| --------- | ----------------------------------- | ---- | ----------------- | 156| source | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | request请求发送方相关信息。 | 157| name | string | 是 | 模板名称。 | 158| data | [KVObject](#kvobject) | 是 | 附加数据。 | 159 160**返回值：** 161 162| 类型 | 说明 | 163| ---------------------------------------- | --------------------------------------------------------- | 164| [RequestEventResult](#requesteventresult) | 注册Request监听方法后，接受到的请求事件时候回应请求的数据类型。 | 165 166**示例：** 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 189组件提供方向组件使用方主动发送组件与数据。 190 191**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 192 193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 194 195**参数：** 196| 参数名 | 类型 | 必填 | 说明 | 197| -------- | --------------------------------- | ---- | ------------ | 198| param | [PushParameters](#pushparameters) | 是 | 组件使用方的详细信息。 | 199| callback | AsyncCallback<void> | 是 | 此次接口调用的异步回调。 | 200 201**示例：** 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 231组件使用方向组件提供方主动请求组件。 232 233**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 234 235**系统能力：** SystemCapability.ArkUI.ArkUI.Full 236 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 242| param | [RequestParameters](#requestparameters) | 是 | 组件模板的详细请求信息。 | 243| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters)> | 是 | 此次请求的异步回调， 通过回调接口的参数返回接受请求的数据。 | 244 245**示例：** 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 275提供方监听"request"类型的事件，给使用方返回通过request接口主动请求的数据；使用方监听"push"类型的事件，接收提供方通过push接口主动推送的数据。 276 277**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 278 279**系统能力：** SystemCapability.ArkUI.ArkUI.Full 280 281**参数：** 282 283| 参数名 | 类型 | 必填 | 说明 | 284| --------- | ---------------------------------------- | ---- | ---------------------------------------- | 285| eventType | string | 是 | 监听的事件类型， 可选值为："push" 、"request"。<br/>"push”：指组件提供方向使用方主动推送数据。<br/>"request”：指组件使用方向提供方主动请求数据。 | 286| callback | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | 是 | 对应监听回调，push事件对应回调类型为[OnPushEventCallback](#onpusheventcallback)，request事件对应回调类型为[OnRequestEventCallback](#onrequesteventcallback) 。 | 287 288**示例：** 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## external.json文件说明 313 314external.json文件由开发者创建。external.json中以键值对形式存放组件名称以及对应模板路径。以组件名称name作为关键字，对应模板路径作为值。 315 316**示例** 317 318```json 319{ 320 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 321 "plugintemplate2": "ets/pages/plugintemplate2.js" 322} 323 324```