diff --git a/en/application-dev/reference/apis/js-apis-plugincomponent.md b/en/application-dev/reference/apis/js-apis-plugincomponent.md new file mode 100644 index 0000000000000000000000000000000000000000..740fd72e50247da5bdae3b573c1e115c8cdcd0e5 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-plugincomponent.md @@ -0,0 +1,400 @@ +# @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](../arkui-ts/ts-basic-components-plugincomponent.md). + +> **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 + +```js +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](#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](js-apis-application-want.md) | Yes | Ability information of the component user. | +| name | string | Yes | Component name. | +| data | [KVObject](#kvobject) | No | Component data value. | +| extraData | [KVObject](#kvobject) | No | Additional data value. | +| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) 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](js-apis-application-want.md) | Yes | Ability information of the component provider. | +| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. | +| name | string | Yes | Component name. | +| data | [KVObject](#kvobject) | No | Component data value. | +| extraData | [KVObject](#kvobject) | No | Additional data value. | +| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) 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](js-apis-application-want.md) | Yes | Ability information of the component provider. | +| name | string | Yes | Name of the requested component. | +| data | [KVObject](#kvobject) | Yes | Additional data. | +| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) 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](js-apis-application-want.md) | Yes | Ability information of the component user. | +| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. | +| name | string | Yes | Name of the requested component. | +| data | [KVObject](#kvobject) | Yes | Additional data. | +| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) 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](#plugincomponenttemplate)] | Yes | Component template.| +| data | [KVObject](#kvobject) | Yes | Component data.| +| extraData | [KVObject](#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](#kvobject) | No | Component data.| +| extraData | [KVObject](#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](js-apis-application-want.md) | Yes | Information about the push request sender. | +| template | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Name of the request component template for the push request sender.| +| data | [KVObject](#kvobject) | Yes | Data. | +| extraData | [KVObject](#kvobject) | Yes | Additional data. | + +**Example** + +```js +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](js-apis-application-want.md) | Yes | Information about the request sender.| +| data | [KVObject](#kvobject) | Yes | Data. | +| extraData | [KVObject](#kvobject) | Yes | Additional data. | + +**Example** + +```js +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](#pushparameters) | Yes | Information about the component user. | +| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.| + +**Example** + +```js +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](#pushparameterforstage) | Yes | Information about the component user. | +| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.| + +**Example** + +```js +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](#requestparameters) | Yes | Information about the component request. | +| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.| + +**Example** + +```js +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](#requestparameterforstage) | Yes | Information about the component request. | +| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.| + +**Example** + +```js +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](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | Yes | Callback used to return the result. The type is [OnPushEventCallback](#onpusheventcallback) for the push event and [OnRequestEventCallback](#onrequesteventcallback) for the request event.| + + +**Example** + +```js + 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** + +```json +{ + "PluginProviderExample": "ets/pages/PluginProviderExample.js", + "plugintemplate2": "ets/pages/plugintemplate2.js" +} + +``` \ No newline at end of file diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-plugincomponent.md b/en/application-dev/reference/arkui-ts/ts-basic-components-plugincomponent.md index cee680621ce514b190bbddd8248647bbef0394bc..041045dc6986adfcc82696f3df7d314aaabccbe7 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-plugincomponent.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-plugincomponent.md @@ -1,14 +1,11 @@ # PluginComponent -The **\** allows the UI provided by an external application to be displayed in the application. +The **\** allows the UI provided by an external application to be displayed in the application. To implement the update through inter-process communication (IPC), see [@ohos.pluginComponent](../apis/js-apis-plugincomponent.md). > **NOTE** > > - This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version. -> -> - The APIs provided by this component are system APIs. - ## Child Components @@ -23,166 +20,41 @@ Creates a **PluginComponent** to display the UI provided by an external applicat **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| value | {
template: PluginComponentTemplate,
data: KVObject
} | Yes | **template**: template of the **PluginComponent**, which is bound to the component defined by the provider.
**data**: data passed to the **PluginComponent** provider.| +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------- | +| value | {
template: [PluginComponentTemplate](#plugincomponenttemplate),
data: [KVObject](../apis/js-apis-plugincomponent.md#kvobject)
} | Yes | **template**: template of the **PluginComponent**, which is bound to the component defined by the provider.
**data**: data passed to the **PluginComponent** provider.| ## PluginComponentTemplate -| Name | Type | Description | -| ------- | ------ | ----------------------- | -| source | string | Component template name. | -| ability | string | Name of the provider ability.| +| Name | Type | Description | +| ---------- | ------ | --------------------------- | +| source | string | Component template name. | +| bundleName | string | Bundle name of the provider ability.| ## Events -| Name | Description | -| ---------------------------------------- | ---------------------------------------- | -| onComplete(callback: () => void) | Triggered when the component loading is complete. | +| Name | Description | +| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| onComplete(callback: () => void) | Triggered when the component loading is complete. | | onError(callback: (info: { errcode: number, msg: string }) => void) | Triggered when an error occurs during component loading.
**errcode**: error code.
**msg**: error information.| - -## PluginComponentManager - -Provides APIs for the **PluginComponent**. You can use these APIs to request components and data and send component templates and data. - - -## Modules to Import - - -``` -import pluginComponentManager from '@ohos.plugincomponent' -``` - - -## push - -push(param: PushParameters, callback: AsyncCallback<void>): void - -Pushes the component and data to the component user. - -**Parameters** - -| Name | Type | Mandatory | Description | -| -------- | ------------------------- | ---- | -------------------------------- | -| param | PushParameters | Yes | Information about the component user. For details, see **PushParameters**.| -| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result. | - -**PushParameters** - -| 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 of the **external.json** file that stores template paths. | - -**Example** - -For details, see [PluginComponent Provider](#plugincomponent-provider). - - -## request - -request(param: RequestParameters, callback: AsyncCallback<RequestCallbackParameters>): void - -Requests the component from the component provider. - -**Parameters** - -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | ------------------------------------ | -| param | RequestParameters | Yes | Information about the component request. For details, see **RequestParameters**.| -| callback | AsyncCallback**"push"**: The component provider pushes data to the component user.
**"request"**: The component user proactively requests data from the component provider.| -| callback | OnPushEventCallback \| OnRequestEventCallback | Yes | Callback used to return the result. For details, see **callback**. | - -**callback** - -| Name | Type | Description | -| ---------------------- | ---------------------------------------- | ---------------------------------------- | -| OnRequestEventCallback | (source: Want,
name: string,
data: KVObject ) =>RequestEventResult | Callback for the data request event.
**source**: ability information of the component requester.
**name**: name of the requested component.
**data**: additional data.
Return value: request data and result.| -| OnPushEventCallback | (source: Want,
template: PluginComponentTemplate,
data: KVObject,
extraData: KVObject
) => void | Callback used to receive the data pushed by the component provider.
**source**: ability information of the component provider.
**template**: component template.
**data**: component update data.
**extraData**: additional data.| - -**RequestEventResult** - -| Name | Type | Description | -| --------- | -------- | ---------- | -| template | string | Component name.| -| data | KVObject | Component data.| -| extraData | KVObject | Additional data.| - -**Example** - -For details, see [PluginComponent Tools](#plugincomponent-tools). - -**KVObject** - -| Name | Type | Description | -| ---- | ---------------------------------------- | ---------------------------------------- | -| key | number \| string \| boolean \| Array \| KVObject | Key of the **KVObject**. **KVObject** uses **key** and **value** to store data. If **key** is of the string type, **value** can be of the number, string, boolean, array type or another **KVObject**.| - - -**Description of the external.json file** - -The **external.json** file is created by developers. This file stores component names and template paths in key-value pairs. The component name is the key, and the corresponding template path is the value. - -**Example** - -For details, see [external.json](#externaljson). - ## Example ### PluginComponent User - ```ts //PluginUserExample.ets -import plugin from "plugin_component.js" +import plugin from "./plugin_component.js" @Entry @Component struct PluginUserExample { @StorageLink("plugincount") plugincount: Object[] = [ - { source: 'plugincomponent1', ability: 'com.example.plugin' }, - { source: 'plugintemplate', ability: 'com.example.myapplication' }, - { source: 'plugintemplate', ability: 'com.example.myapplication' }] + { source: 'plugincomponent1', bundleName: 'com.example.plugin' }, + { source: 'plugintemplate', bundleName: 'com.example.myapplication' }, + { source: 'plugintemplate', bundleName: 'com.example.myapplication' }] build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { @@ -209,7 +81,7 @@ struct PluginUserExample { }) ForEach(this.plugincount, item => { PluginComponent({ - template: { source: 'plugincomponent1', ability: 'com.example.plugin' }, + template: { source: 'PluginProviderExample', bundleName: 'com.example.plugin' }, data: { 'countDownStartValue': 'new countDownStartValue' } }).size({ width: 500, height: 100 }) .onComplete(() => { @@ -230,7 +102,7 @@ struct PluginUserExample { ```ts //PluginProviderExample.ets -import plugin from "plugin_component.js" +import plugin from "./plugin_component.js" @Entry @Component @@ -270,7 +142,7 @@ struct PluginProviderExample { ### PluginComponent Tools - +#### FA Model ```js //plugin_component.js import pluginComponentManager from '@ohos.pluginComponent' @@ -308,10 +180,10 @@ export default { pluginComponentManager.push( { want: { - bundleName: "com.example.myapplication", - abilityName: "com.example.myapplication.MainAbility", + bundleName: "com.example.plugin", + abilityName: "com.example.myapplication.PluginProviderExample", }, - name: "plugintemplate", + name: "PluginProviderExample", data: { "key_1": "plugin component test", "key_2": 34234 @@ -330,10 +202,10 @@ export default { // The component user proactively sends data. pluginComponentManager.request({ want: { - bundleName: "com.example.myapplication", - abilityName: "com.example.myapplication.MainAbility", + bundleName: "com.example.plugin", + abilityName: "com.example.myapplication.PluginProviderExample", }, - name: "plugintemplate", + name: "PluginProviderExample", data: { "key_1": "plugin component test", "key_2": 34234 @@ -358,10 +230,98 @@ export default { } ``` +#### Stage Model +```js +//plugin_component.js +import pluginComponentManager from '@ohos.pluginComponent' + +function onPushListener(source, template, data, extraData) { + console.log("onPushListener template.source=" + template.source) + var jsonObject = JSON.parse(data.componentTemplate.source) + console.log("request_callback1:source json object" + jsonObject) + var jsonArry = jsonObject.ExternalComponent + for (var i in jsonArry) { + console.log(jsonArry[i]) + } + console.log("onPushListener:source json object" + jsonObject) + console.log("onPushListener:source json string" + JSON.stringify(jsonObject)) + console.log("onPushListener template.ability=" + template.ability) + console.log("onPushListener data=" + JSON.stringify(data)) + console.log("onPushListener extraData=" + JSON.stringify(extraData)) +} -### external.json -```json +function onRequestListener(source, name, data) { - "plugintemplate": "ets/pages/plugintemplate.js", - "plugintemplate2": "ets/pages/plugintemplate2.js" + console.log("onRequestListener name=" + name); + console.log("onRequestListener data=" + JSON.stringify(data)); + return {template:"plugintemplate", data:data}; } + +export default { + //register listener + onListener() { + pluginComponentManager.on("push", onPushListener) + pluginComponentManager.on("request", onRequestListener) + }, + Push() { + // The component provider proactively sends data. + pluginComponentManager.push( + { + owner: { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility", + }, + target: { + bundleName: "com.example.plugin", + abilityName: "com.example.myapplication.PluginProviderExample", + }, + name: "PluginProviderExample", + 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() { + // The component user proactively sends data. + pluginComponentManager.request({ + owner: { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility", + }, + target: { + bundleName: "com.example.plugin", + abilityName: "com.example.myapplication.PluginProviderExample", + }, + name: "PluginProviderExample", + data: { + "key_1": "plugin component test", + "key_2": 34234 + }, + jsonPath: "", + }, + (err, data) => { + console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability) + console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source) + var jsonObject = JSON.parse(data.componentTemplate.source) + console.log("request_callback:source json object" + jsonObject) + var jsonArry = jsonObject.ExternalComponent + for (var i in jsonArry) { + console.log(jsonArry[i]) + } + console.log("request_callback:source json string" + JSON.stringify(jsonObject)) + console.log("request_callback: data=" + JSON.stringify(data.data)) + console.log("request_callback: extraData=" + JSON.stringify(data.extraData)) + } + ) + } +} +```