@ohos.pluginComponent (PluginComponentManager)

The PluginComponentManager module provides APIs for the PluginComponent user to request components and data and send component templates and data. For details about how to display the PluginComponent template, see PluginComponent.

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 '@ohos.pluginComponent'

PluginComponentTemplate

Describes the PluginComponent template parameters.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
source string Yes Component template name.
bundleName string Yes Bundle name of the provider ability.

PluginComponentManager

KVObject

Stores information in key-value pairs in JSON format.

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.

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 No Component data value.
extraData KVObject No Additional data value.
jsonPath string No Path to the external.json file that stores the template path.

PushParameterForStage

Sets the parameters to be passed in the PluginManager.Push API in the stage model.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
owner Want Yes Ability information of the component provider.
target Want Yes Ability information of the component user.
name string Yes Component name.
data KVObject No Component data value.
extraData KVObject No 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.

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.

RequestParameterForStage

Sets the parameters to be passed in the PluginManager.Request API in the stage model.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
owner Want Yes Ability information of the component user.
target 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.

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.

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

OnPushEventCallback = (source: Want, template: PluginComponentTemplate, data: KVObject, extraData: KVObject) => void

Registers the listener for the push event.

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

function onPushListener(source, template, data, extraData) {
    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

OnRequestEventCallback = (source: Want, name: string, data: KVObject) => RequestEventResult

Registers the listener for the request event.

Parameters

Name Type Mandatory Description
source Want Yes Information about the request sender.
data KVObject Yes Data.
extraData KVObject Yes Additional data.

Example

function onRequestListener(source, name, data)
{
    console.error("onRequestListener");
    console.log("onRequestListener source=" + JSON.stringify(source));
    console.log("onRequestListener name=" + name);
    console.log("onRequestListener data=" + JSON.stringify(data));

    return {template:"ets/pages/plugin.js", data:data};
}

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.

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

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!");
    }
)

push

push(param: PushParameterForStage, callback: AsyncCallback<void>): void

Pushes the component and data to the component user.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
param PushParameterForStage Yes Information about the component user.
callback AsyncCallback<void> Yes Asynchronous callback used to return the result.

Example

pluginComponentManager.push(
    {
        owner:{
            bundleName:"com.example.provider",
            abilityName:"com.example.provider.MainAbility"
        },
        target: {
            bundleName: "com.example.provider",
            abilityName: "com.example.provider.MainAbility",
        },
        name: "ets/pages/plugin2.js",
        data: {
            "js": "ets/pages/plugin.js",
            "key_1": 1111, ,
        },
        extraData: {
            "extra_str": "this is push event"
        },
        jsonPath: "",
    },
    (err, data) => {
        console.log("push_callback:err: " ,JSON.stringify(err));
        console.log("push_callback:data: " , JSON.stringify(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.

Parameters

Name Type Mandatory Description
param RequestParameters Yes Information about the component request.
callback AsyncCallback<RequestCallbackParameters | void> Yes Asynchronous callback used to return the requested data.

Example

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))
    }
)

request

request(param: RequestParameterForStage, callback: AsyncCallback<RequestCallbackParameters>): void

Requests the component from the component provider.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
param RequestParameterForStage Yes Information about the component request.
callback AsyncCallback<RequestCallbackParameters | void> Yes Asynchronous callback used to return the requested data.

Example

pluginComponentManager.request(
    {
        owner:{
            bundleName:"com.example.provider",
            abilityName:"com.example.provider.MainAbility"
            },
        target: {
            bundleName: "com.example.provider",
            abilityName: "ets/pages/plugin2.js",
            },
        name: "plugintemplate",
        data: {
                "key_1": " myapplication plugin component test",
                },
        jsonPath: "",
    },
    (err, data) => {
        console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability)
        console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source)
    }
)

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.

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

    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"
}