1# @ohos.pluginComponent (PluginComponentManager) 2 3用于给插件组件的使用者请求组件与数据，使用者发送组件模板和数据。如需实现插件模板的显示，请参考[PluginComponent](../arkui-ts/ts-basic-components-plugincomponent.md)。 4 5> **说明：** 6> 7> - 本模块首批接口从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 导入模块 10 11```js 12import pluginComponentManager from '@ohos.pluginComponent' 13``` 14 15## PluginComponentTemplate 16 17Plugin组件模板参数。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21| 参数 | 类型 | 必填 | 描述 | 22| ---------- | ------ | ---- | --------------------------- | 23| source | string | 是 | 组件模板名。 | 24| bundleName | string | 是 | 提供者Ability的bundleName。 | 25 26 27## PluginComponentManager 28 29### KVObject 30 31以键值对形式存储信息，符合json格式。 32 33**系统能力：** SystemCapability.ArkUI.ArkUI.Full 34 35 36| 取值范围 | 说明 | 37| --------------------- | ---------------------------------------- | 38| [key: string] | 关键字，数据类型为字符串，可取空字符串。 | 39| number | 键值，表示值类型为数字。 | 40| string | 键值，表示值类型为字符串，可取空字符串。 | 41| boolean | 键值，表示值类型为布尔值。 | 42| [] | 键值，可取值为[]。 | 43| [KVObject](#kvobject) | 键值，表示值类型为KVObject。 | 44 45 46### PushParameters 47 48用于设置FA模型下使用PluginManager.Push方法时候的需要传递的参数。 49 50**模型约束：** 此接口仅适用于FA模型。 51 52**系统能力：** SystemCapability.ArkUI.ArkUI.Full 53 54| 名称 | 类型 | 必填 | 说明 | 55| --------- | ----------------------------------- | ---- | -------------------------------------------------------------- | 56| want | [Want](js-apis-application-want.md) | 是 | 组件使用者Ability信息。 | 57| name | string | 是 | 组件名称。 | 58| data | [KVObject](#kvobject) | 否 | 组件数据值。 | 59| extraData | [KVObject](#kvobject) | 否 | 附加数据值。 | 60| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)件的路径。 | 61 62### PushParameterForStage 63 64用于设置Stage模型下使用PluginManager.Push方法时候的需要传递的参数。 65 66**模型约束：** 此接口仅适用于Stage模型。 67 68**系统接口：** 此接口为系统接口。 69 70**系统能力：** SystemCapability.ArkUI.ArkUI.Full 71 72| 名称 | 类型 | 必填 | 说明 | 73| --------- | ----------------------------------- | ---- | ---------------------------------------------------------------- | 74| owner | [Want](js-apis-application-want.md) | 是 | 组件提供方Ability信息。 | 75| target | [Want](js-apis-application-want.md) | 是 | 组件使用者Ability信息。 | 76| name | string | 是 | 组件名称。 | 77| data | [KVObject](#kvobject) | 否 | 组件数据值。 | 78| extraData | [KVObject](#kvobject) | 否 | 附加数据值。 | 79| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)文件的路径。 | 80 81### RequestParameters 82 83用于设置FA模型下使用PluginManager.Request方法时候的需要传递的参数。 84 85**模型约束：** 此接口仅适用于FA模型。 86 87**系统能力：** SystemCapability.ArkUI.ArkUI.Full 88 89| 名称 | 类型 | 必填 | 说明 | 90| -------- | ----------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- | 91| want | [Want](js-apis-application-want.md) | 是 | 组件提供者Ability信息。 | 92| name | string | 是 | 请求组件名称。 | 93| data | [KVObject](#kvobject) | 是 | 附加数据。 | 94| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)文件的路径。jsonPath字段不为空或者未设置的时候不触发Request通信。 | 95 96### RequestParameterForStage 97 98用于设置Stage模型下使用PluginManager.Request方法时候的需要传递的参数。 99 100**系统接口：** 此接口为系统接口。 101 102**模型约束：** 此接口仅适用于Stage模型。 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106| 名称 | 类型 | 必填 | 说明 | 107| -------- | ----------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- | 108| owner | [Want](js-apis-application-want.md) | 是 | 组件使用者Ability信息。 | 109| target | [Want](js-apis-application-want.md) | 是 | 组件提供者Ability信息。 | 110| name | string | 是 | 请求组件名称。 | 111| data | [KVObject](#kvobject) | 是 | 附加数据。 | 112| jsonPath | string | 否 | 存放模板路径的[external.json](#externaljson文件说明)文件的路径。jsonPath字段不为空或者未设置的时候不触发Request通信。 | 113 114### RequestCallbackParameters 115 116PluginManager.Request方法时候接收到的回调结果。 117 118**系统能力：** SystemCapability.ArkUI.ArkUI.Full 119 120| 名称 | 类型 | 必填 | 说明 | 121| ----------------- | ---------------------------------------------------- | ---- | ---------- | 122| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate)] | 是 | 组件模板。 | 123| data | [KVObject](#kvobject) | 是 | 组件数据。 | 124| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 125 126### RequestEventResult 127 128注册Request监听方法后，接受到的请求事件时候回应请求的数据类型。 129 130**系统能力：** SystemCapability.ArkUI.ArkUI.Full 131 132| 名称 | 类型 | 必填 | 说明 | 133| --------- | --------------------- | ---- | ---------- | 134| template | string | 否 | 组件模板。 | 135| data | [KVObject](#kvobject) | 否 | 组件数据。 | 136| extraData | [KVObject](#kvobject) | 否 | 附加数据。 | 137 138### OnPushEventCallback 139 140OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, 141 extraData: KVObject) => void 142 143对应Push事件的监听回调函数。 144 145**参数：** 146 147| 参数 | 类型 | 必填 | 说明 | 148| --------- | --------------------------------------------------- | ---- | ---------------------------------------- | 149| source | [Want](js-apis-application-want.md) | 是 | Push请求发送方相关信息。 | 150| template | [PluginComponentTemplate](#plugincomponenttemplate) | 是 | Push请求发送方相关信息请求组件模板名称。 | 151| data | [KVObject](#kvobject) | 是 | 数据。 | 152| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 153 154**示例：** 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 171对应request事件的监听回调函数。 172 173**参数：** 174 175| 参数 | 类型 | 必填 | 说明 | 176| --------- | ----------------------------------- | ---- | --------------------------- | 177| source | [Want](js-apis-application-want.md) | 是 | request请求发送方相关信息。 | 178| data | [KVObject](#kvobject) | 是 | 数据。 | 179| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 180 181**示例：** 182 183```js 184function onRequestListener(source, name, data) 185{ 186 console.error("onRequestListener"); 187 console.log("onRequestListener source=" + JSON.stringify(source)); 188 console.log("onRequestListener name=" + name); 189 console.log("onRequestListener data=" + JSON.stringify(data)); 190 191 return {template:"ets/pages/plugin.js", data:data}; 192} 193``` 194 195### push 196 197push(param: PushParameters , callback: AsyncCallback<void>): void 198 199组件提供者向组件使用者主动发送组件与数据。 200 201**模型约束：** 此接口仅适用于FA模型。 202 203**参数：** 204| 参数名 | 类型 | 必填 | 说明 | 205| -------- | --------------------------------- | ---- | ------------------------ | 206| param | [PushParameters](#pushparameters) | 是 | 组件使用者的详细信息。 | 207| callback | AsyncCallback<void> | 是 | 此次接口调用的异步回调。 | 208 209**示例：** 210 211```js 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, data) => { 229 console.log("push_callback: push ok!"); 230 } 231) 232``` 233 234### push 235 236push(param: PushParameterForStage, callback: AsyncCallback<void>): void 237 238组件提供者向组件使用者主动发送组件与数据。 239 240**系统接口：** 此接口为系统接口。 241 242**模型约束：** 此接口仅适用于Stage模型。 243 244**参数：** 245| 参数名 | 类型 | 必填 | 说明 | 246| -------- | ----------------------------------------------- | ---- | ------------------------ | 247| param | [PushParameterForStage](#pushparameterforstage) | 是 | 组件使用者的详细信息。 | 248| callback | AsyncCallback<void> | 是 | 此次接口调用的异步回调。 | 249 250**示例：** 251 252```js 253pluginComponentManager.push( 254 { 255 owner:{ 256 bundleName:"com.example.provider", 257 abilityName:"com.example.provider.MainAbility" 258 }, 259 target: { 260 bundleName: "com.example.provider", 261 abilityName: "com.example.provider.MainAbility", 262 }, 263 name: "ets/pages/plugin2.js", 264 data: { 265 "js": "ets/pages/plugin.js", 266 "key_1": 1111, , 267 }, 268 extraData: { 269 "extra_str": "this is push event" 270 }, 271 jsonPath: "", 272 }, 273 (err, data) => { 274 console.log("push_callback:err: " ,JSON.stringify(err)); 275 console.log("push_callback:data: " , JSON.stringify(data)); 276 console.log("push_callback: push ok!"); 277 } 278) 279``` 280 281 282### request 283 284request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void 285 286组件使用者向组件提供者主动请求组件。 287 288**模型约束：** 此接口仅适用于FA模型。 289 290 291**参数：** 292 293| 参数名 | 类型 | 必填 | 说明 | 294| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 295| param | [RequestParameters](#requestparameters) | 是 | 组件模板的详细请求信息。 | 296| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | 是 | 此次请求的异步回调， 通过回调接口的参数返回接受请求的数据。 | 297 298**示例：** 299 300```js 301pluginComponentManager.request( 302 { 303 want: { 304 bundleName: "com.example.provider", 305 abilityName: "com.example.provider.MainAbility", 306 }, 307 name: "plugintemplate", 308 data: { 309 "key_1": "plugin component test", 310 "key_2": 1111111 311 }, 312 jsonPath: "", 313 }, 314 (err, data) => { 315 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 316 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 317 console.log("request_callback: data=" + JSON.stringify(data.data)) 318 console.log("request_callback: extraData=" + JSON.stringify(data.extraData)) 319 } 320) 321``` 322 323 324### request 325 326request(param: RequestParameterForStage, callback: AsyncCallback<RequestCallbackParameters>): void 327 328组件使用者向组件提供者主动请求组件。 329 330**系统接口：** 此接口为系统接口。 331 332**模型约束：** 此接口仅适用于Stage模型。 333 334**参数：** 335 336| 参数名 | 类型 | 必填 | 说明 | 337| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 338| param | [RequestParameterForStage](#requestparameterforstage) | 是 | 组件模板的详细请求信息。 | 339| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | 是 | 此次请求的异步回调， 通过回调接口的参数返回接受请求的数据。 | 340 341**示例：** 342 343```js 344pluginComponentManager.request( 345 { 346 owner:{ 347 bundleName:"com.example.provider", 348 abilityName:"com.example.provider.MainAbility" 349 }, 350 target: { 351 bundleName: "com.example.provider", 352 abilityName: "ets/pages/plugin2.js", 353 }, 354 name: "plugintemplate", 355 data: { 356 "key_1": " myapplication plugin component test", 357 }, 358 jsonPath: "", 359 }, 360 (err, data) => { 361 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 362 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 363 } 364) 365``` 366 367### on 368 369on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void 370 371提供者监听"request"类型的事件，给使用者返回通过request接口主动请求的数据；使用者监听"push"类型的事件，接收提供者通过push接口主动推送的数据。 372 373**参数：** 374 375| 参数名 | 类型 | 必填 | 说明 | 376| --------- | ---------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | 377| eventType | string | 是 | 监听的事件类型， 可选值为："push" 、"request"。<br/>"push”：指组件提供者向使用者主动推送数据。<br/>"request”：指组件使用者向提供者主动请求数据。 | 378| callback | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | 是 | 对应监听回调，push事件对应回调类型为[OnPushEventCallback](#onpusheventcallback)，request事件对应回调类型为[OnRequestEventCallback](#onrequesteventcallback) 。 | 379 380 381**示例：** 382 383```js 384 pluginComponentManager.on("push", onPushListener) 385 pluginComponentManager.on("request", onRequestListener) 386``` 387 388## external.json文件说明 389 390external.json文件由开发者创建。external.json中以键值对形式存放组件名称以及对应模板路径。以组件名称name作为关键字，对应模板路径作为值。 391 392**示例** 393 394```json 395{ 396 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 397 "plugintemplate2": "ets/pages/plugintemplate2.js" 398} 399