1# @ohos.pluginComponent (PluginComponentManager) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @dutie123--> 5<!--Designer: @lmleon--> 6<!--Tester: @fredyuan0912--> 7<!--Adviser: @HelloCrease--> 8 9用于给插件组件的使用方请求组件与数据，使用方发送组件模板和数据。 10 11> **说明：** 12> 13> - 本模块首批接口从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## 导入模块 16 17```ts 18import { pluginComponentManager } from '@kit.ArkUI'; 19``` 20 21## PluginComponentTemplate 22 23Plugin组件模板参数。 24 25**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29| 名称 | 类型 | 只读 | 可选 | 说明 | 30| ------- | ------ | ---- | ---- | --------------------------- | 31| source | string | 否 | 否 | 组件模板名。 | 32| ability | string | 否 | 否 | 提供方Ability的bundleName。 | 33 34## pluginComponentManager 35 36插件组件管理器。 37 38### KVObject 39 40type KVObject = { [key: string]: number | string | boolean | [] | KVObject } 41 42以键值对形式存储信息，符合json格式。 43 44**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 45 46**系统能力：** SystemCapability.ArkUI.ArkUI.Full 47 48| 名称 | 类型 | 必填 | 说明 | 49| ------- | ------ | ---- | --------------------------- | 50| [key: string] | number \| string \| boolean \| [] \| [KVObject](#kvobject) | 是 | 键值对形式存储。<br/>number：键值，表示值类型为数字。<br/> string：键值，表示值类型为字符串，可取空字符串。<br/> boolean：键值，表示值类型为布尔值。<br/> []：键值，可取值为[]。<br/>[KVObject](#kvobject)：键值，表示值类型为KVObject。 | 51 52 53### PushParameters 54 55使用PluginManager.Push方法时需要传递的参数。 56 57**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.ArkUI.ArkUI.Full 60 61| 名称 | 类型 | 只读 | 可选 | 说明 | 62| --------- | ----------------------------------- | ---- | ---- | ---------------------------------------- | 63| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 否 | 否 | 组件使用方Ability信息。 | 64| name | string | 否 | 否 | 组件名称。 | 65| data | [KVObject](#kvobject) | 否 | 否 | 组件数据。 | 66| extraData | [KVObject](#kvobject) | 否 | 否 | 附加数据。 | 67| jsonPath | string | 否 | 是 | 存放模板路径的[external.json](#externaljson文件说明)文件的路径。 | 68 69### RequestParameters 70 71使用PluginManager.Request方法时需要传递的参数。 72 73**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 74 75**系统能力：** SystemCapability.ArkUI.ArkUI.Full 76 77| 名称 | 类型 | 只读 | 可选 | 说明 | 78| -------- | ----------------------------------- | ---- | ---- |---------------------------------------- | 79| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 否 | 否 | 组件提供方Ability信息。 | 80| name | string | 否 | 否 | 请求组件名称。 | 81| data | [KVObject](#kvobject) | 否 | 否 | 组件数据。 | 82| jsonPath | string | 否 | 是 | 存放模板路径的[external.json](#externaljson文件说明)文件的路径。当jsonPath字段不为空时不触发Request通信。 | 83 84### RequestCallbackParameters 85 86PluginManager.Request方法接收到的回调结果。 87 88**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92| 名称 | 类型 | 只读 | 可选 | 说明 | 93| ----------------- | ---------------------------------------- | ---- | ---- | ----- | 94| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | 否 | 否 | 组件模板。 | 95| data | [KVObject](#kvobject) | 否 | 否 | 组件数据。 | 96| extraData | [KVObject](#kvobject) | 否 | 否 | 附加数据。 | 97 98### RequestEventResult 99 100注册Request监听方法后，接收到请求事件时回应请求的数据类型。 101 102**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106| 名称 | 类型 | 只读 | 可选 | 说明 | 107| --------- | --------------------- | ---- | ---- | ----- | 108| template | string | 否 | 是 | 组件模板。 | 109| data | [KVObject](#kvobject) | 否 | 是 | 组件数据。 | 110| extraData | [KVObject](#kvobject) | 否 | 是 | 附加数据。 | 111 112### OnPushEventCallback 113 114type OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, 115 extraData: KVObject) => void 116 117对应Push事件的监听回调函数。 118 119**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 120 121**系统能力：** SystemCapability.ArkUI.ArkUI.Full 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| --------- | ---------------------------------------- | ---- | ---------------------- | 127| source | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | Push请求发送方相关信息。 | 128| template | [PluginComponentTemplate](#plugincomponenttemplate) | 是 | 请求组件模板名称。 | 129| data | [KVObject](#kvobject) | 是 | 数据。 | 130| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 131 132**示例：** 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.info("onPushListener template.source=" + template.source); 140 console.info("onPushListener source=" + JSON.stringify(source)); 141 console.info("onPushListener template=" + JSON.stringify(template)); 142 console.info("onPushListener data=" + JSON.stringify(data)); 143 console.info("onPushListener extraData=" + JSON.stringify(extraData)); 144} 145``` 146 147 148### OnRequestEventCallback 149 150type OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult 151 152对应request事件的监听回调函数。 153 154**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 155 156**系统能力：** SystemCapability.ArkUI.ArkUI.Full 157 158**参数：** 159 160| 参数名 | 类型 | 必填 | 说明 | 161| --------- | ----------------------------------- | ---- | ----------------- | 162| source | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | request请求发送方相关信息。 | 163| name | string | 是 | 模板名称。 | 164| data | [KVObject](#kvobject) | 是 | 数据。 | 165 166**返回值：** 167 168| 类型 | 说明 | 169| ---------------------------------------- | --------------------------------------------------------- | 170| [RequestEventResult](#requesteventresult) | 注册Request监听方法后，接收到请求事件时回应请求的数据类型。 | 171 172**示例：** 173 174```ts 175import { pluginComponentManager } from '@kit.ArkUI'; 176import { Want } from '@kit.AbilityKit'; 177 178function onRequestListener(source: Want, name: string, data: pluginComponentManager.KVObject) { 179 console.info("onRequestListener"); 180 console.info("onRequestListener source=" + JSON.stringify(source)); 181 console.info("onRequestListener name=" + name); 182 console.info("onRequestListener data=" + JSON.stringify(data)); 183 let RtnData: Record<string, string | pluginComponentManager.KVObject> = { 184 'template': "ets/pages/plugin.js", 185 'data': data, 186 } 187 return RtnData; 188} 189``` 190 191### pluginComponentManager.push 192 193push(param: PushParameters , callback: AsyncCallback<void>): void 194 195组件提供方向组件使用方主动发送组件和数据。 196 197**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 198 199**系统能力：** SystemCapability.ArkUI.ArkUI.Full 200 201**参数：** 202| 参数名 | 类型 | 必填 | 说明 | 203| -------- | --------------------------------- | ---- | ------------ | 204| param | [PushParameters](#pushparameters) | 是 | 组件使用方的详细信息。 | 205| callback | AsyncCallback<void> | 是 | 此次接口调用的异步回调。 | 206 207**示例：** 208 209```ts 210import { pluginComponentManager } from '@kit.ArkUI'; 211 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) => { 229 console.info("push_callback: push ok!"); 230 } 231) 232``` 233 234### pluginComponentManager.request 235 236request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void 237 238组件使用方向组件提供方主动请求组件。 239 240**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 241 242**系统能力：** SystemCapability.ArkUI.ArkUI.Full 243 244 245**参数：** 246 247| 参数名 | 类型 | 必填 | 说明 | 248| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 249| param | [RequestParameters](#requestparameters) | 是 | 组件模板的详细请求信息。 | 250| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters)> | 是 | 此次请求的异步回调，通过回调接口的参数返回接收请求的数据。 | 251 252**示例：** 253 254```ts 255import { pluginComponentManager } from '@kit.ArkUI'; 256 257pluginComponentManager.request( 258 { 259 want: { 260 bundleName: "com.example.provider", 261 abilityName: "com.example.provider.MainAbility", 262 }, 263 name: "plugintemplate", 264 data: { 265 "key_1": "plugin component test", 266 "key_2": 1111111, 267 }, 268 jsonPath: "", 269 }, 270 (err, data) => { 271 console.info("request_callback: componentTemplate.ability=" + data.componentTemplate.ability); 272 console.info("request_callback: componentTemplate.source=" + data.componentTemplate.source); 273 console.info("request_callback: data=" + JSON.stringify(data.data)); 274 console.info("request_callback: extraData=" + JSON.stringify(data.extraData)); 275 } 276) 277``` 278 279### pluginComponentManager.on 280 281on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void 282 283提供方监听"request"类型的事件，给使用方返回通过request接口主动请求的数据；使用方监听"push"类型的事件，接收提供方通过push接口主动推送的数据。 284 285**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 286 287**系统能力：** SystemCapability.ArkUI.ArkUI.Full 288 289**参数：** 290 291| 参数名 | 类型 | 必填 | 说明 | 292| --------- | ---------------------------------------- | ---- | ---------------------------------------- | 293| eventType | string | 是 | 监听的事件类型， 可选值为："push" 、"request"。<br/>"push”：指组件提供方向使用方主动推送数据。<br/>"request”：指组件使用方向提供方主动请求数据。 | 294| callback | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | 是 | 对应监听回调，push事件对应回调类型为[OnPushEventCallback](#onpusheventcallback)，request事件对应回调类型为[OnRequestEventCallback](#onrequesteventcallback) 。 | 295 296**示例：** 297 298```ts 299import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI'; 300import { Want } from '@kit.AbilityKit'; 301 302function onPushListener(source:Want, template:PluginComponentTemplate, data:pluginComponentManager.KVObject, extraData:pluginComponentManager.KVObject) { 303 console.info("onPushListener template.source=" + template.source); 304 console.info("onPushListener source=" + JSON.stringify(source)); 305 console.info("onPushListener template=" + JSON.stringify(template)); 306 console.info("onPushListener data=" + JSON.stringify(data)); 307 console.info("onPushListener extraData=" + JSON.stringify(extraData)); 308} 309function onRequestListener(source:Want, name:string, data:pluginComponentManager.KVObject) { 310 console.info("onRequestListener"); 311 console.info("onRequestListener source=" + JSON.stringify(source)); 312 console.info("onRequestListener name=" + name); 313 console.info("onRequestListener data=" + JSON.stringify(data)); 314 let RtnData:Record<string,string|pluginComponentManager.KVObject> = { 'template': "ets/pages/plugin.js", 'data': data }; 315 return RtnData; 316} 317pluginComponentManager.on("push", onPushListener); 318pluginComponentManager.on("request", onRequestListener); 319``` 320 321## external.json文件说明 322 323external.json文件由开发者创建。external.json中以键值对形式存放组件名称以及对应模板路径。以组件名称name作为关键字，对应模板路径作为值。 324 325**示例** 326 327```json 328{ 329 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 330 "plugintemplate2": "ets/pages/plugintemplate2.js" 331} 332 333```