1# PluginComponent (System API)
2
3The **PluginComponent** allows an application to display external UI from another application. To implement update through inter-process communication (IPC), see [@ohos.pluginComponent](../js-apis-plugincomponent.md).
4
5
6>  **NOTE**
7>
8>  - This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
9>
10>  - The APIs provided by this module are system APIs.
11
12## Child Components
13
14Not supported
15
16
17## APIs
18
19PluginComponent(value: { template: PluginComponentTemplate, data: KVObject})
20
21Creates a **PluginComponent** to display the UI provided by an external application.
22
23**Parameters**
24
25| Name| Type                                                    | Mandatory| Description                                                    |
26| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
27| value  | {<br>template:  [PluginComponentTemplate](#plugincomponenttemplate),<br>data: [KVObject](../js-apis-plugincomponent.md#kvobject)<br>} | Yes  | **template**: template of the **PluginComponent**, which is bound to the component defined by the provider.<br>**data**: data passed to the **PluginComponent** provider.|
28
29## PluginComponentTemplate
30
31| Name      | Type  | Description                       |
32| ---------- | ------ | --------------------------- |
33| source     | string | Component template name.               |
34| bundleName | string | Bundle name of the provider ability.|
35## Attributes
36The width and height of the component must be explicitly set to non-zero valid values.
37
38**NOTE**
39
40  The template can be provided in either of the following modes:
41* Use an absolute path. In this case, set **source** to the absolute path of the template and leave **bundleName** blank. This mode is not recommended as it is applicable only to standalone templates that do not need to load resources.
42
43* Use an application package. In this case, set **bundleName** to the application bundle name and **source** to the relative path of the HAP file template. In the multi-HAP scenario, a HAP file is identified based on its relative path and name.
44
45  Example: **{source: 'pages/PluginProviderExample.ets&entry', bundleName:'com.example.provider'}**
46
47  The template is provided only when **source** can be set to an ability name in the FA model.
48
49  Example: **{source:'plugin', bundleName:'com.example.provider'}**
50
51
52## Events
53
54Only the [gesture event](ts-gesture-settings.md) can be distributed to and processed inside the provider page.
55
56In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
57
58### onComplete
59
60onComplete(callback: () =&gt; void)
61
62Triggered when the component loading is complete.
63
64**System API**: This is a system API.
65
66**System capability**: SystemCapability.ArkUI.ArkUI.Full
67
68### onError
69
70onError(callback: (info: { errcode: number, msg: string }) =&gt; void)
71
72Triggered when an error occurs during component loading.
73
74**System API**: This is a system API.
75
76**System capability**: SystemCapability.ArkUI.ArkUI.Full
77
78**Parameters**
79
80| Name| Type                                                        | Mandatory| Description                                           |
81| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
82| info   |  { errcode: number, msg: string } | Yes  | **errcode**: error code.<br>**msg**: error information.|
83
84## Example
85
86
87### PluginComponent User
88
89```ts
90//PluginUserExample.ets
91import plugin from "./plugin_component"
92interface Info{
93  errcode:number,
94  msg:string
95}
96@Entry
97@Component
98struct PluginUserExample {
99
100  build() {
101    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
102      Text('Hello World')
103        .fontSize(50)
104        .fontWeight(FontWeight.Bold)
105      Button('Register Request Listener')
106        .fontSize(30)
107        .width(400)
108        .height(100)
109        .margin({top:20})
110        .onClick(()=>{
111          plugin.onListener()
112          console.log("Button('Register Request Listener')")
113        })
114      Button('Request')
115        .fontSize(50)
116        .width(400)
117        .height(100)
118        .margin({ top: 20 })
119        .onClick(() => {
120          plugin.Request()
121          console.log("Button('Request')")
122        })
123      PluginComponent({
124        template: { source: 'pages/PluginProviderExample.ets&entry', bundleName: 'com.example.plugin' },
125        data: { 'countDownStartValue': 'new countDownStartValue' }
126      }).size({ width: 500, height: 350 })
127        .onComplete(() => {
128          console.log("onComplete")
129        })
130        .onError((info:Info) => {
131          console.log("onComplete" + info.errcode + ":" + info.msg)
132        })
133    }
134    .width('100%')
135    .height('100%')
136  }
137}
138```
139
140### PluginComponent Provider
141
142```ts
143//PluginProviderExample.ets
144import plugin from "./plugin_component"
145
146@Entry
147@Component
148struct PluginProviderExample {
149  @State message: string = 'no click!'
150
151  build() {
152    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
153      Button('Register Push Listener')
154        .fontSize(30)
155        .width(400)
156        .height(100)
157        .margin({top:20})
158        .onClick(()=>{
159          plugin.onListener()
160          console.log("Button('Register Push Listener')")
161        })
162      Button('Push')
163        .fontSize(30)
164        .width(400)
165        .height(100)
166        .margin({top:20})
167        .onClick(()=>{
168          plugin.Push()
169          this.message = "Button('Push')"
170          console.log("Button('Push')")
171        })
172      Text(this.message)
173        .height(150)
174        .fontSize(30)
175        .padding(5)
176        .margin(5)
177    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
178  }
179}
180```
181
182### PluginComponent Tools
183
184#### FA Model
185```js
186// The sample code applies only to JS source files.
187//plugin_component.js
188import pluginComponentManager from '@ohos.pluginComponent'
189
190function onPushListener(source, template, data, extraData) {
191  console.log("onPushListener template.source=" + template.source)
192  console.log("onPushListener template.ability=" + template.ability)
193  console.log("onPushListener data=" + JSON.stringify(data))
194  console.log("onPushListener extraData=" + JSON.stringify(extraData))
195}
196
197function onRequestListener(source, name, data)
198{
199    console.log("onRequestListener name=" + name);
200    console.log("onRequestListener data=" + JSON.stringify(data));
201    return {template:"plugintemplate", data:data};
202}
203
204export default {
205  //register listener
206  onListener() {
207    pluginComponentManager.on("push", onPushListener)
208    pluginComponentManager.on("request", onRequestListener)
209  },
210  Push() {
211    // The component provider proactively sends data.
212    pluginComponentManager.push(
213      {
214        want: {
215          bundleName: "com.example.plugin",
216          abilityName: "com.example.myapplication.PluginProviderExample",
217        },
218        name: "PluginProviderExample",
219        data: {
220          "key_1": "plugin component test",
221          "key_2": 34234
222        },
223        extraData: {
224          "extra_str": "this is push event"
225        },
226        jsonPath: "",
227      },
228      (err, data) => {
229        console.log("push_callback: push ok!");
230      }
231    )
232  },
233  Request() {
234    // The component user proactively sends data.
235    pluginComponentManager.request({
236        want: {
237          bundleName: "com.example.plugin",
238          abilityName: "com.example.myapplication.PluginProviderExample",
239        },
240        name: "PluginProviderExample",
241        data: {
242          "key_1": "plugin component test",
243          "key_2": 34234
244        },
245        jsonPath: "",
246      },
247      (err, data) => {
248        console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability)
249        console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source)
250        console.log("request_callback: data=" + JSON.stringify(data.data))
251        console.log("request_callback: extraData=" + JSON.stringify(data.extraData))
252      }
253    )
254  }
255}
256```
257
258#### Stage Model
259```js
260// The sample code applies only to JS source files.
261//plugin_component.js
262import pluginComponentManager from '@ohos.pluginComponent'
263
264function onPushListener(source, template, data, extraData) {
265  console.log("onPushListener template.source=" + template.source)
266  console.log("onPushListener template.ability=" + template.ability)
267  console.log("onPushListener data=" + JSON.stringify(data))
268  console.log("onPushListener extraData=" + JSON.stringify(extraData))
269}
270
271function onRequestListener(source, name, data)
272{
273    console.log("onRequestListener name=" + name);
274    console.log("onRequestListener data=" + JSON.stringify(data));
275    return {template:"plugintemplate", data:data};
276}
277
278export default {
279  //register listener
280  onListener() {
281    pluginComponentManager.on("push", onPushListener)
282    pluginComponentManager.on("request", onRequestListener)
283  },
284  Push() {
285    // The component provider proactively sends data.
286    pluginComponentManager.push(
287      {
288        owner: {
289          bundleName: "com.example.myapplication",
290          abilityName: "com.example.myapplication.MainAbility",
291        },
292        target: {
293          bundleName: "com.example.plugin",
294          abilityName: "com.example.myapplication.PluginProviderExample",
295        },
296        name: "PluginProviderExample",
297        data: {
298          "key_1": "plugin component test",
299          "key_2": 34234
300        },
301        extraData: {
302          "extra_str": "this is push event"
303        },
304        jsonPath: "",
305      },
306      (err, data) => {
307        console.log("push_callback: push ok!");
308      }
309    )
310  },
311  Request() {
312    // The component user proactively sends data.
313    pluginComponentManager.request({
314        owner: {
315          bundleName: "com.example.myapplication",
316          abilityName: "com.example.myapplication.MainAbility",
317        },
318        target: {
319          bundleName: "com.example.plugin",
320          abilityName: "com.example.myapplication.PluginProviderExample",
321        },
322        name: "PluginProviderExample",
323        data: {
324          "key_1": "plugin component test",
325          "key_2": 34234
326        },
327        jsonPath: "",
328      },
329      (err, data) => {
330        console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability)
331        console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source)
332        console.log("request_callback: data=" + JSON.stringify(data.data))
333        console.log("request_callback: extraData=" + JSON.stringify(data.extraData))
334      }
335    )
336  }
337}
338```
339