@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	Yes	Component data value.
extraData	KVObject	Yes	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	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.

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

import pluginComponentManager from '@ohos.pluginComponent'
import Want from '@ohos.app.ability.Want';
import PluginComponentTemplate from '@ohos.pluginComponent'
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

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.
name	string	Yes	Template name.
extraData	KVObject	Yes	Additional data.

Example

import pluginComponentManager from '@ohos.pluginComponent'
import Want from '@ohos.app.ability.Want';
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.

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

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

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

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

import pluginComponentManager from '@ohos.pluginComponent'
import Want from '@ohos.app.ability.Want';
import {PluginComponentTemplate} from '@ohos.pluginComponent'
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"
}