1# PluginComponent (系统接口)
2
3提供外部应用组件嵌入式显示功能，即外部应用提供的UI可在本应用内显示。如需通过跨进程通信实现更新，请参考[@ohos.pluginComponent](../js-apis-plugincomponent.md)。
4
5
6>  **说明：**
7>
8>  - 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
9>
10>  - 本模块系统接口。
11
12## 子组件
13
14无
15
16
17## 接口
18
19PluginComponent(value: { template: PluginComponentTemplate, data: KVObject})
20
21创建插件组件，用于显示外部应用提供的UI。
22
23**参数：**
24
25| 参数名 | 参数类型                                                     | 必填 | 参数描述                                                     |
26| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
27| value  | {<br/>template:&nbsp; [PluginComponentTemplate](#plugincomponenttemplate类型说明),<br/>data:&nbsp;[KVObject](../js-apis-plugincomponent.md#kvobject)<br/>} | 是   | template:&nbsp;&nbsp;组件模板，用于跟提供者定义的组件绑定。<br/>data:&nbsp;传给插件组件提供者使用的数据。 |
28
29## PluginComponentTemplate类型说明
30
31| 参数       | 类型   | 描述                        |
32| ---------- | ------ | --------------------------- |
33| source     | string | 组件模板名。                |
34| bundleName | string | 提供者Ability的bundleName。 |
35## 属性
36必须显式设置组件宽高为非0有效值。
37
38**说明：**
39
40  模板支持两种提供方式：
41* 1.使用绝对路径进行资源提供：source字段填写模板绝对路径，bundleName不需要填写。仅适用于不需要加载资源的单独模板页面，不建议使用。
42* 2.通过应用包进行资源提供：bundleName字段需要填写应用包名；source字段填写相对hap包的模板相对路径，对于多hap场景，通过相对路径&模块名称的方式进行hap包的确认。
43
44  例如：{source：'pages/PluginProviderExample.ets&entry', bundleName:'com.example.provider'}
45
46  仅对FA模型支持source字段填写AbilityName进行模板提供。
47
48  例如：{source：'plugin', bundleName:'com.example.provider'}
49
50
51## 事件
52
53仅支持[绑定手势方法](ts-gesture-settings.md)，并分发给提供方页面，在提供方页面内部处理。
54
55除支持[通用事件](ts-universal-events-click.md)，还支持以下事件：
56
57### onComplete
58
59onComplete(callback:&nbsp;()&nbsp;=&gt;&nbsp;void)
60
61组件加载完成回调。
62
63**系统接口：** 此接口为系统接口。
64
65**系统能力：** SystemCapability.ArkUI.ArkUI.Full
66
67### onError
68
69onError(callback:&nbsp;(info:&nbsp;{&nbsp;errcode:&nbsp;number,&nbsp;msg:&nbsp;string&nbsp;})&nbsp;=&gt;&nbsp;void)
70
71组件加载错误回调。
72
73**系统接口：** 此接口为系统接口。
74
75**系统能力：** SystemCapability.ArkUI.ArkUI.Full
76
77**参数：** 
78
79| 参数名 | 类型                                                         | 必填 | 说明                                            |
80| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
81| info   | &nbsp;{&nbsp;errcode:&nbsp;number,&nbsp;msg:&nbsp;string&nbsp;} | 是   | errcode:&nbsp;错误码。<br/>msg:&nbsp;错误信息。 |
82
83## 示例
84
85
86### 组件使用方
87
88```ts
89//PluginUserExample.ets
90import plugin from "./plugin_component"
91interface Info{
92  errcode:number,
93  msg:string
94}
95@Entry
96@Component
97struct PluginUserExample {
98
99  build() {
100    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
101      Text('Hello World')
102        .fontSize(50)
103        .fontWeight(FontWeight.Bold)
104      Button('Register Request Listener')
105        .fontSize(30)
106        .width(400)
107        .height(100)
108        .margin({top:20})
109        .onClick(()=>{
110          plugin.onListener()
111          console.log("Button('Register Request Listener')")
112        })
113      Button('Request')
114        .fontSize(50)
115        .width(400)
116        .height(100)
117        .margin({ top: 20 })
118        .onClick(() => {
119          plugin.Request()
120          console.log("Button('Request')")
121        })
122      PluginComponent({
123        template: { source: 'pages/PluginProviderExample.ets&entry', bundleName: 'com.example.plugin' },
124        data: { 'countDownStartValue': 'new countDownStartValue' }
125      }).size({ width: 500, height: 350 })
126        .onComplete(() => {
127          console.log("onComplete")
128        })
129        .onError((info:Info) => {
130          console.log("onComplete" + info.errcode + ":" + info.msg)
131        })
132    }
133    .width('100%')
134    .height('100%')
135  }
136}
137```
138
139### 组件提供方
140
141```ts
142//PluginProviderExample.ets
143import plugin from "./plugin_component"
144
145@Entry
146@Component
147struct PluginProviderExample {
148  @State message: string = 'no click!'
149
150  build() {
151    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
152      Button('Register Push Listener')
153        .fontSize(30)
154        .width(400)
155        .height(100)
156        .margin({top:20})
157        .onClick(()=>{
158          plugin.onListener()
159          console.log("Button('Register Push Listener')")
160        })
161      Button('Push')
162        .fontSize(30)
163        .width(400)
164        .height(100)
165        .margin({top:20})
166        .onClick(()=>{
167          plugin.Push()
168          this.message = "Button('Push')"
169          console.log("Button('Push')")
170        })
171      Text(this.message)
172        .height(150)
173        .fontSize(30)
174        .padding(5)
175        .margin(5)
176    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
177  }
178}
179```
180
181### Plugin组件工具
182
183#### FA模型
184```js
185//当前示例代码仅适用于js源文件
186//plugin_component.js
187import pluginComponentManager from '@ohos.pluginComponent'
188
189function onPushListener(source, template, data, extraData) {
190  console.log("onPushListener template.source=" + template.source)
191  console.log("onPushListener template.ability=" + template.ability)
192  console.log("onPushListener data=" + JSON.stringify(data))
193  console.log("onPushListener extraData=" + JSON.stringify(extraData))
194}
195
196function onRequestListener(source, name, data)
197{
198    console.log("onRequestListener name=" + name);
199    console.log("onRequestListener data=" + JSON.stringify(data));
200    return {template:"plugintemplate", data:data};
201}
202
203export default {
204  //register listener
205  onListener() {
206    pluginComponentManager.on("push", onPushListener)
207    pluginComponentManager.on("request", onRequestListener)
208  },
209  Push() {
210    // 组件提供方主动发送事件
211    pluginComponentManager.push(
212      {
213        want: {
214          bundleName: "com.example.plugin",
215          abilityName: "com.example.myapplication.PluginProviderExample",
216        },
217        name: "PluginProviderExample",
218        data: {
219          "key_1": "plugin component test",
220          "key_2": 34234
221        },
222        extraData: {
223          "extra_str": "this is push event"
224        },
225        jsonPath: "",
226      },
227      (err, data) => {
228        console.log("push_callback: push ok!");
229      }
230    )
231  },
232  Request() {
233    // 组件使用方主动发送事件
234    pluginComponentManager.request({
235        want: {
236          bundleName: "com.example.plugin",
237          abilityName: "com.example.myapplication.PluginProviderExample",
238        },
239        name: "PluginProviderExample",
240        data: {
241          "key_1": "plugin component test",
242          "key_2": 34234
243        },
244        jsonPath: "",
245      },
246      (err, data) => {
247        console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability)
248        console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source)
249        console.log("request_callback: data=" + JSON.stringify(data.data))
250        console.log("request_callback: extraData=" + JSON.stringify(data.extraData))
251      }
252    )
253  }
254}
255```
256
257#### Stage模型
258```js
259//当前示例代码仅适用于js源文件
260//plugin_component.js
261import pluginComponentManager from '@ohos.pluginComponent'
262
263function onPushListener(source, template, data, extraData) {
264  console.log("onPushListener template.source=" + template.source)
265  console.log("onPushListener template.ability=" + template.ability)
266  console.log("onPushListener data=" + JSON.stringify(data))
267  console.log("onPushListener extraData=" + JSON.stringify(extraData))
268}
269
270function onRequestListener(source, name, data)
271{
272    console.log("onRequestListener name=" + name);
273    console.log("onRequestListener data=" + JSON.stringify(data));
274    return {template:"plugintemplate", data:data};
275}
276
277export default {
278  //register listener
279  onListener() {
280    pluginComponentManager.on("push", onPushListener)
281    pluginComponentManager.on("request", onRequestListener)
282  },
283  Push() {
284    // 组件提供方主动发送事件
285    pluginComponentManager.push(
286      {
287        owner: {
288          bundleName: "com.example.myapplication",
289          abilityName: "com.example.myapplication.MainAbility",
290        },
291        target: {
292          bundleName: "com.example.plugin",
293          abilityName: "com.example.myapplication.PluginProviderExample",
294        },
295        name: "PluginProviderExample",
296        data: {
297          "key_1": "plugin component test",
298          "key_2": 34234
299        },
300        extraData: {
301          "extra_str": "this is push event"
302        },
303        jsonPath: "",
304      },
305      (err, data) => {
306        console.log("push_callback: push ok!");
307      }
308    )
309  },
310  Request() {
311    // 组件使用方主动发送事件
312    pluginComponentManager.request({
313        owner: {
314          bundleName: "com.example.myapplication",
315          abilityName: "com.example.myapplication.MainAbility",
316        },
317        target: {
318          bundleName: "com.example.plugin",
319          abilityName: "com.example.myapplication.PluginProviderExample",
320        },
321        name: "PluginProviderExample",
322        data: {
323          "key_1": "plugin component test",
324          "key_2": 34234
325        },
326        jsonPath: "",
327      },
328      (err, data) => {
329        console.log("request_callback: componentTemplate.ability=" + data.componentTemplate.ability)
330        console.log("request_callback: componentTemplate.source=" + data.componentTemplate.source)
331        console.log("request_callback: data=" + JSON.stringify(data.data))
332        console.log("request_callback: extraData=" + JSON.stringify(data.extraData))
333      }
334    )
335  }
336}
337```
338