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