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| --------------------- | ---------------------------------------- | 45| [key: string] | 关键字，数据类型为字符串，可取空字符串。 | 46| number | 键值，表示值类型为数字。 | 47| string | 键值，表示值类型为字符串，可取空字符串。 | 48| boolean | 键值，表示值类型为布尔值。 | 49| [] | 键值，可取值为[]。 | 50| [KVObject](#kvobject) | 键值，表示值类型为KVObject。 | 51 52 53### PushParameters 54 55用于设置FA模型下使用PluginManager.Push方法时候的需要传递的参数。 56 57**模型约束：** 此接口仅适用于FA模型。 58 59**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 60 61**系统能力：** SystemCapability.ArkUI.ArkUI.Full 62 63| 名称 | 类型 | 必填 | 说明 | 64| --------- | ----------------------------------- | ---- | ---------------------------------------- | 65| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | 组件使用者Ability信息。 | 66| name | string | 是 | 组件名称。 | 67| data | [KVObject](#kvobject) | 是 | 组件数据值。 | 68| extraData | [KVObject](#kvobject) | 是 | 附加数据值。 | 69| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)件的路径。 | 70 71### RequestParameters 72 73用于设置FA模型下使用PluginManager.Request方法时候的需要传递的参数。 74 75**模型约束：** 此接口仅适用于FA模型。 76 77**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 78 79**系统能力：** SystemCapability.ArkUI.ArkUI.Full 80 81| 名称 | 类型 | 必填 | 说明 | 82| -------- | ----------------------------------- | ---- | ---------------------------------------- | 83| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | 组件提供者Ability信息。 | 84| name | string | 是 | 请求组件名称。 | 85| data | [KVObject](#kvobject) | 是 | 附加数据。 | 86| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)文件的路径。jsonPath字段不为空或者未设置的时候不触发Request通信。 | 87 88### RequestCallbackParameters 89 90PluginManager.Request方法时候接收到的回调结果。 91 92**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 93 94**系统能力：** SystemCapability.ArkUI.ArkUI.Full 95 96| 名称 | 类型 | 必填 | 说明 | 97| ----------------- | ---------------------------------------- | ---- | ----- | 98| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | 是 | 组件模板。 | 99| data | [KVObject](#kvobject) | 是 | 组件数据。 | 100| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 101 102### RequestEventResult 103 104注册Request监听方法后，接受到的请求事件时候回应请求的数据类型。 105 106**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110| 名称 | 类型 | 必填 | 说明 | 111| --------- | --------------------- | ---- | ----- | 112| template | string | 否 | 组件模板。 | 113| data | [KVObject](#kvobject) | 否 | 组件数据。 | 114| extraData | [KVObject](#kvobject) | 否 | 附加数据。 | 115 116### OnPushEventCallback 117 118type OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, 119 extraData: KVObject) => void 120 121对应Push事件的监听回调函数。 122 123**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 124 125**参数：** 126 127| 参数 | 类型 | 必填 | 说明 | 128| --------- | ---------------------------------------- | ---- | ---------------------- | 129| source | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | Push请求发送方相关信息。 | 130| template | [PluginComponentTemplate](#plugincomponenttemplate) | 是 | Push请求发送方相关信息请求组件模板名称。 | 131| data | [KVObject](#kvobject) | 是 | 数据。 | 132| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 133 134**示例：** 135 136```ts 137import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI' 138import { Want } from '@kit.AbilityKit'; 139 140function onPushListener(source: Want, template: PluginComponentTemplate, data: pluginComponentManager.KVObject, extraData: pluginComponentManager.KVObject) { 141 console.log("onPushListener template.source=" + template.source) 142 console.log("onPushListener source=" + JSON.stringify(source)) 143 console.log("onPushListener template=" + JSON.stringify(template)) 144 console.log("onPushListener data=" + JSON.stringify(data)) 145 console.log("onPushListener extraData=" + JSON.stringify(extraData)) 146} 147``` 148 149 150### OnRequestEventCallback 151 152type OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult 153 154对应request事件的监听回调函数。 155 156**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 157 158**参数：** 159 160| 参数 | 类型 | 必填 | 说明 | 161| --------- | ----------------------------------- | ---- | ----------------- | 162| source | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | request请求发送方相关信息。 | 163| name | string | 是 | 模板名称。 | 164| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 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### push 186 187push(param: PushParameters , callback: AsyncCallback<void>): void 188 189组件提供者向组件使用者主动发送组件与数据。 190 191**模型约束：** 此接口仅适用于FA模型。 192 193**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 194 195**系统能力：** SystemCapability.ArkUI.ArkUI.Full 196 197**参数：** 198| 参数名 | 类型 | 必填 | 说明 | 199| -------- | --------------------------------- | ---- | ------------ | 200| param | [PushParameters](#pushparameters) | 是 | 组件使用者的详细信息。 | 201| callback | AsyncCallback<void> | 是 | 此次接口调用的异步回调。 | 202 203**示例：** 204 205```ts 206import { pluginComponentManager } from '@kit.ArkUI' 207pluginComponentManager.push( 208 { 209 want: { 210 bundleName: "com.example.provider", 211 abilityName: "com.example.provider.MainAbility", 212 }, 213 name: "plugintemplate", 214 data: { 215 "key_1": "plugin component test", 216 "key_2": 34234 217 }, 218 extraData: { 219 "extra_str": "this is push event" 220 }, 221 jsonPath: "", 222 }, 223 (err, data) => { 224 console.log("push_callback: push ok!"); 225 } 226) 227``` 228 229### request 230 231request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void 232 233组件使用者向组件提供者主动请求组件。 234 235**模型约束：** 此接口仅适用于FA模型。 236 237**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 238 239**系统能力：** SystemCapability.ArkUI.ArkUI.Full 240 241 242**参数：** 243 244| 参数名 | 类型 | 必填 | 说明 | 245| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 246| param | [RequestParameters](#requestparameters) | 是 | 组件模板的详细请求信息。 | 247| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters)> | 是 | 此次请求的异步回调， 通过回调接口的参数返回接受请求的数据。 | 248 249**示例：** 250 251```ts 252import { pluginComponentManager } from '@kit.ArkUI' 253pluginComponentManager.request( 254 { 255 want: { 256 bundleName: "com.example.provider", 257 abilityName: "com.example.provider.MainAbility", 258 }, 259 name: "plugintemplate", 260 data: { 261 "key_1": "plugin component test", 262 "key_2": 1111111 263 }, 264 jsonPath: "", 265 }, 266 (err, data) => { 267 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 268 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 269 console.log("request_callback: data=" + JSON.stringify(data.data)) 270 console.log("request_callback: extraData=" + JSON.stringify(data.extraData)) 271 } 272) 273``` 274 275### on 276 277on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void 278 279提供者监听"request"类型的事件，给使用者返回通过request接口主动请求的数据；使用者监听"push"类型的事件，接收提供者通过push接口主动推送的数据。 280 281**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 282 283**系统能力：** SystemCapability.ArkUI.ArkUI.Full 284 285**参数：** 286 287| 参数名 | 类型 | 必填 | 说明 | 288| --------- | ---------------------------------------- | ---- | ---------------------------------------- | 289| eventType | string | 是 | 监听的事件类型， 可选值为："push" 、"request"。<br/>"push”：指组件提供者向使用者主动推送数据。<br/>"request”：指组件使用者向提供者主动请求数据。 | 290| callback | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | 是 | 对应监听回调，push事件对应回调类型为[OnPushEventCallback](#onpusheventcallback)，request事件对应回调类型为[OnRequestEventCallback](#onrequesteventcallback) 。 | 291 292**示例：** 293 294```ts 295import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI' 296import { Want } from '@kit.AbilityKit'; 297function onPushListener(source:Want, template:PluginComponentTemplate, data:pluginComponentManager.KVObject, extraData:pluginComponentManager.KVObject) { 298 console.log("onPushListener template.source=" + template.source) 299 console.log("onPushListener source=" + JSON.stringify(source)) 300 console.log("onPushListener template=" + JSON.stringify(template)) 301 console.log("onPushListener data=" + JSON.stringify(data)) 302 console.log("onPushListener extraData=" + JSON.stringify(extraData)) 303} 304function onRequestListener(source:Want, name:string, data:pluginComponentManager.KVObject) { 305 console.error("onRequestListener"); 306 console.log("onRequestListener source=" + JSON.stringify(source)); 307 console.log("onRequestListener name=" + name); 308 console.log("onRequestListener data=" + JSON.stringify(data)); 309 let RtnData:Record<string,string|pluginComponentManager.KVObject> = { 'template': "ets/pages/plugin.js", 'data': data } 310 return RtnData; 311} 312pluginComponentManager.on("push", onPushListener) 313pluginComponentManager.on("request", onRequestListener) 314``` 315 316## external.json文件说明 317 318external.json文件由开发者创建。external.json中以键值对形式存放组件名称以及对应模板路径。以组件名称name作为关键字，对应模板路径作为值。 319 320**示例** 321 322```json 323{ 324 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 325 "plugintemplate2": "ets/pages/plugintemplate2.js" 326} 327 328```