@ohos.pluginComponent (PluginComponentManager)
The PluginComponentManager module provides APIs for the PluginComponent user to request components and data and send component templates and data.
NOTE
- The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Modules to Import
import { pluginComponentManager } from '@kit.ArkUI'
PluginComponentTemplate
Describes the PluginComponent template parameters.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| source | string | Yes | Component template name. |
| ability | string | Yes | Bundle name of the provider ability. |
PluginComponentManager
Implements a plugin component manager.
KVObject
type KVObject = { [key: string]: number | string | boolean | [] | KVObject }
Stores information in key-value pairs in JSON format.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Value Range | Description |
|---|---|
| [key: string] | Keyword. The value is a string and can be an empty string. |
| number | Key value of the number type. |
| string | Key value of the string type. The value can be an empty string. |
| boolean | Key value of the Boolean type. |
| [] | Key value. The value can be []. |
| KVObject | Key value of the KVObject type. |
PushParameters
Sets the parameters to be passed in the PluginManager.Push API in the FA model.
Model restriction: This API can be used only in the FA model.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| want | Want | Yes | Ability information of the component user. |
| name | string | Yes | Component name. |
| data | KVObject | Yes | Component data value. |
| extraData | KVObject | Yes | Additional data value. |
| jsonPath | string | No | Path to the external.json file that stores the template path. |
RequestParameters
Sets the parameters to be passed in the PluginManager.Request API in the FA model.
Model restriction: This API can be used only in the FA model.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| want | Want | Yes | Ability information of the component provider. |
| name | string | Yes | Name of the requested component. |
| data | KVObject | Yes | Additional data. |
| jsonPath | string | No | Path to the external.json file that stores the template path. Request communication is not triggered when jsonPath is not empty or not set. |
RequestCallbackParameters
Provides the result returned after the PluginManager.Request API is called.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| componentTemplate | PluginComponentTemplate | Yes | Component template. |
| data | KVObject | Yes | Component data. |
| extraData | KVObject | Yes | Additional data. |
RequestEventResult
Provides the result returned after the request listener is registered and the requested event is received.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| template | string | No | Component template. |
| data | KVObject | No | Component data. |
| extraData | KVObject | No | Additional data. |
OnPushEventCallback
type OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, extraData: KVObject) => void
Registers the listener for the push event.
Atomic service API: This API can be used in atomic services since API version 12.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| source | Want | Yes | Information about the push request sender. |
| template | PluginComponentTemplate | Yes | Name of the request component template for the push request sender. |
| data | KVObject | Yes | Data. |
| extraData | KVObject | Yes | Additional data. |
Example
import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI'
import { Want } from '@kit.AbilityKit';
function onPushListener(source: Want, template: PluginComponentTemplate, data: pluginComponentManager.KVObject, extraData: pluginComponentManager.KVObject) {
console.log("onPushListener template.source=" + template.source)
console.log("onPushListener source=" + JSON.stringify(source))
console.log("onPushListener template=" + JSON.stringify(template))
console.log("onPushListener data=" + JSON.stringify(data))
console.log("onPushListener extraData=" + JSON.stringify(extraData))
}
OnRequestEventCallback
type OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult
Registers the listener for the request event.
Atomic service API: This API can be used in atomic services since API version 12.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| source | Want | Yes | Information about the request sender. |
| name | string | Yes | Template name. |
| extraData | KVObject | Yes | Additional data. |
Example
import { pluginComponentManager } from '@kit.ArkUI'
import { Want } from '@kit.AbilityKit';
function onRequestListener(source: Want, name: string, data: pluginComponentManager.KVObject) {
console.error("onRequestListener");
console.log("onRequestListener source=" + JSON.stringify(source));
console.log("onRequestListener name=" + name);
console.log("onRequestListener data=" + JSON.stringify(data));
let RtnData: Record<string, string | pluginComponentManager.KVObject> = {
'template': "ets/pages/plugin.js",
'data': data
}
return RtnData;
}
push
push(param: PushParameters , callback: AsyncCallback<void>): void
Pushes the component and data to the component user.
Model restriction: This API can be used only in the FA model.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| param | PushParameters | Yes | Information about the component user. |
| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result. |
Example
import { pluginComponentManager } from '@kit.ArkUI'
pluginComponentManager.push(
{
want: {
bundleName: "com.example.provider",
abilityName: "com.example.provider.MainAbility",
},
name: "plugintemplate",
data: {
"key_1": "plugin component test",
"key_2": 34234
},
extraData: {
"extra_str": "this is push event"
},
jsonPath: "",
},
(err, data) => {
console.log("push_callback: push ok!");
}
)
request
request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void
Requests the component from the component provider.
Model restriction: This API can be used only in the FA model.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| param | RequestParameters | Yes | Information about the component request. |
| callback | AsyncCallback<RequestCallbackParameters> | Yes | Asynchronous callback used to return the requested data. |
Example
import { pluginComponentManager } from '@kit.ArkUI'
pluginComponentManager.request(
{
want: {
bundleName: "com.example.provider",
abilityName: "com.example.provider.MainAbility",
},
name: "plugintemplate",
data: {
"key_1": "plugin component test",
"key_2": 1111111
},
jsonPath: "",
},
(err, data) => {
console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability)
console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source)
console.log("request_callback: data=" + JSON.stringify(data.data))
console.log("request_callback: extraData=" + JSON.stringify(data.extraData))
}
)
on
on(eventType: string, callback: OnPushEventCallback | OnRequestEventCallback ): void
Listens for events of the request type and returns the requested data, or listens for events of the push type and receives the data pushed by the provider.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| eventType | string | Yes | Type of the event to listen for. The options are as follows: "push": The component provider pushes data to the component consumer. "request": The component consumer proactively requests data from the component provider. |
| callback | OnPushEventCallback | OnRequestEventCallback | Yes | Callback used to return the result. The type is OnPushEventCallback for the push event and OnRequestEventCallback for the request event. |
Example
import { pluginComponentManager, PluginComponentTemplate } from '@kit.ArkUI'
import { Want } from '@kit.AbilityKit';
function onPushListener(source:Want, template:PluginComponentTemplate, data:pluginComponentManager.KVObject, extraData:pluginComponentManager.KVObject) {
console.log("onPushListener template.source=" + template.source)
console.log("onPushListener source=" + JSON.stringify(source))
console.log("onPushListener template=" + JSON.stringify(template))
console.log("onPushListener data=" + JSON.stringify(data))
console.log("onPushListener extraData=" + JSON.stringify(extraData))
}
function onRequestListener(source:Want, name:string, data:pluginComponentManager.KVObject) {
console.error("onRequestListener");
console.log("onRequestListener source=" + JSON.stringify(source));
console.log("onRequestListener name=" + name);
console.log("onRequestListener data=" + JSON.stringify(data));
let RtnData:Record<string,string|pluginComponentManager.KVObject> = { 'template': "ets/pages/plugin.js", 'data': data }
return RtnData;
}
pluginComponentManager.on("push", onPushListener)
pluginComponentManager.on("request", onRequestListener)
About the external.json File
The external.json file is created by developers. It stores component names and template paths in key-value pairs. The component name is used as the keyword, and the corresponding template path is used as the value.
Example
{
"PluginProviderExample": "ets/pages/PluginProviderExample.js",
"plugintemplate2": "ets/pages/plugintemplate2.js"
}