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| name | string | 是 | 模板名称。 | 179| extraData | [KVObject](#kvobject) | 是 | 附加数据。 | 180 181**示例：** 182 183```js 184function onRequestListener(source, name, data) { 185 console.error("onRequestListener"); 186 console.log("onRequestListener source=" + JSON.stringify(source)); 187 console.log("onRequestListener name=" + name); 188 console.log("onRequestListener data=" + JSON.stringify(data)); 189 190 return { template: "ets/pages/plugin.js", data: data }; 191} 192``` 193 194### push 195 196push(param: PushParameters , callback: AsyncCallback<void>): void 197 198组件提供者向组件使用者主动发送组件与数据。 199 200**模型约束：** 此接口仅适用于FA模型。 201 202**参数：** 203| 参数名 | 类型 | 必填 | 说明 | 204| -------- | --------------------------------- | ---- | ------------------------ | 205| param | [PushParameters](#pushparameters) | 是 | 组件使用者的详细信息。 | 206| callback | AsyncCallback<void> | 是 | 此次接口调用的异步回调。 | 207 208**示例：** 209 210```js 211pluginComponentManager.push( 212 { 213 want: { 214 bundleName: "com.example.provider", 215 abilityName: "com.example.provider.MainAbility", 216 }, 217 name: "plugintemplate", 218 data: { 219 "key_1": "plugin component test", 220 "key_2": 34234 221 }, 222 extraData: { 223 "extra_str": "this is push event" 224 }, 225 jsonPath: "", 226 }, 227 (err, data) => { 228 console.log("push_callback: push ok!"); 229 } 230) 231``` 232 233### push 234 235push(param: PushParameterForStage, callback: AsyncCallback<void>): void 236 237组件提供者向组件使用者主动发送组件与数据。 238 239**系统接口：** 此接口为系统接口。 240 241**模型约束：** 此接口仅适用于Stage模型。 242 243**参数：** 244| 参数名 | 类型 | 必填 | 说明 | 245| -------- | ----------------------------------------------- | ---- | ------------------------ | 246| param | [PushParameterForStage](#pushparameterforstage) | 是 | 组件使用者的详细信息。 | 247| callback | AsyncCallback<void> | 是 | 此次接口调用的异步回调。 | 248 249**示例：** 250 251```js 252pluginComponentManager.push( 253 { 254 owner: { 255 bundleName: "com.example.provider", 256 abilityName: "com.example.provider.MainAbility" 257 }, 258 target: { 259 bundleName: "com.example.provider", 260 abilityName: "com.example.provider.MainAbility", 261 }, 262 name: "ets/pages/plugin2.js", 263 data: { 264 "js": "ets/pages/plugin.js", 265 "key_1": 1111, , 266 }, 267 extraData: { 268 "extra_str": "this is push event" 269 }, 270 jsonPath: "", 271 }, 272 (err, data) => { 273 console.log("push_callback:err: ", JSON.stringify(err)); 274 console.log("push_callback:data: ", JSON.stringify(data)); 275 console.log("push_callback: push ok!"); 276 } 277) 278``` 279 280 281### request 282 283request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void 284 285组件使用者向组件提供者主动请求组件。 286 287**模型约束：** 此接口仅适用于FA模型。 288 289 290**参数：** 291 292| 参数名 | 类型 | 必填 | 说明 | 293| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 294| param | [RequestParameters](#requestparameters) | 是 | 组件模板的详细请求信息。 | 295| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | 是 | 此次请求的异步回调， 通过回调接口的参数返回接受请求的数据。 | 296 297**示例：** 298 299```js 300pluginComponentManager.request( 301 { 302 want: { 303 bundleName: "com.example.provider", 304 abilityName: "com.example.provider.MainAbility", 305 }, 306 name: "plugintemplate", 307 data: { 308 "key_1": "plugin component test", 309 "key_2": 1111111 310 }, 311 jsonPath: "", 312 }, 313 (err, data) => { 314 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 315 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 316 console.log("request_callback: data=" + JSON.stringify(data.data)) 317 console.log("request_callback: extraData=" + JSON.stringify(data.extraData)) 318 } 319) 320``` 321 322 323### request 324 325request(param: RequestParameterForStage, callback: AsyncCallback<RequestCallbackParameters>): void 326 327组件使用者向组件提供者主动请求组件。 328 329**系统接口：** 此接口为系统接口。 330 331**模型约束：** 此接口仅适用于Stage模型。 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 说明 | 336| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- | 337| param | [RequestParameterForStage](#requestparameterforstage) | 是 | 组件模板的详细请求信息。 | 338| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | 是 | 此次请求的异步回调， 通过回调接口的参数返回接受请求的数据。 | 339 340**示例：** 341 342```js 343pluginComponentManager.request( 344 { 345 owner: { 346 bundleName: "com.example.provider", 347 abilityName: "com.example.provider.MainAbility" 348 }, 349 target: { 350 bundleName: "com.example.provider", 351 abilityName: "ets/pages/plugin2.js", 352 }, 353 name: "plugintemplate", 354 data: { 355 "key_1": " myapplication plugin component test", 356 }, 357 jsonPath: "", 358 }, 359 (err, data) => { 360 console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) 361 console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) 362 } 363) 364``` 365 366### on 367 368on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void 369 370提供者监听"request"类型的事件，给使用者返回通过request接口主动请求的数据；使用者监听"push"类型的事件，接收提供者通过push接口主动推送的数据。 371 372**参数：** 373 374| 参数名 | 类型 | 必填 | 说明 | 375| --------- | ---------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | 376| eventType | string | 是 | 监听的事件类型， 可选值为："push" 、"request"。<br/>"push”：指组件提供者向使用者主动推送数据。<br/>"request”：指组件使用者向提供者主动请求数据。 | 377| callback | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | 是 | 对应监听回调，push事件对应回调类型为[OnPushEventCallback](#onpusheventcallback)，request事件对应回调类型为[OnRequestEventCallback](#onrequesteventcallback) 。 | 378 379 380**示例：** 381 382```js 383pluginComponentManager.on("push", onPushListener) 384pluginComponentManager.on("request", onRequestListener) 385``` 386 387## external.json文件说明 388 389external.json文件由开发者创建。external.json中以键值对形式存放组件名称以及对应模板路径。以组件名称name作为关键字，对应模板路径作为值。 390 391**示例** 392 393```json 394{ 395 "PluginProviderExample": "ets/pages/PluginProviderExample.js", 396 "plugintemplate2": "ets/pages/plugintemplate2.js" 397} 398 399```