1# XComponent 2 3可用于EGL/OpenGLES和媒体数据写入，并显示在XComponent组件。 4 5> **说明：** 6> 7> 该组件从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 子组件 10 11 构造参数type为"surface"时不支持。 12 13 从API version 9开始，构造参数type为"component"时可以包含子组件。 14 15## 接口 16 17 XComponent(value: {id: string, type: string, libraryname?: string, controller?: XComponentController}) 18 19**参数:** 20 21| 参数名 | 参数类型 | 必填 | 描述 | 22| ----------- | ---------------------------------------- | ---- | ---------------------------------------- | 23| id | string | 是 | 组件的唯一标识，支持最大的字符串长度128。 | 24| type | string | 是 | 用于指定XComponent组件类型，可选值为：<br/>-"surface"：用于EGL/OpenGLES和媒体数据写入，组件内容单独送显，直接合成到屏幕。<br/>-"component"<sup>9+</sup> ：XComponent将变成一个容器组件，并可在其中执行非UI逻辑以动态加载显示内容。 | 25| libraryname | string | 否 | 应用Native层编译输出动态库名称，仅XComponent类型为"surface"时有效。 | 26| controller | [XComponentcontroller](#xcomponentcontroller) | 否 | 给组件绑定一个控制器，通过控制器调用组件方法，仅XComponent类型为"surface"时有效。 | 27 28> **说明：** 29> 30> type为"component"时，XComponent作为容器，子组件沿垂直方向布局： 31> 32> - 垂直方向上对齐格式：[FlexAlign](ts-appendix-enums.md#flexalign).Start 33> - 水平方向上对齐格式：[FlexAlign](ts-appendix-enums.md#flexalign).Center 34> 35> 所有的事件响应均不支持。 36> 37> 布局方式更改和事件响应均可通过挂载子组件来设置。 38> 39> 内部所写的非UI逻辑需要封装在一个或多个函数内。 40 41## 属性 42- XComponent显示的内容，可由开发者自定义绘制，通用属性不支持[背景设置](./ts-universal-attributes-background.md)、[透明度设置](./ts-universal-attributes-opacity.md)和[图像效果](./ts-universal-attributes-image-effect.md)。 43- type为"surface"时建议使用EGL/OpenGLES提供的接口设置相关内容。 44- type为"component"时建议使用挂载子组件的方式进行设置相关内容。 45 46## 事件 47 48仅type为"surface"时以下事件有效。不支持[通用事件](ts-universal-events-click.md)和[手势](ts-gesture-settings.md)。 49 50### onLoad 51 52onLoad(callback: (event?: object) => void ) 53 54插件加载完成时回调事件。 55 56**参数:** 57 58| 参数名 | 参数类型 | 必填 | 描述 | 59| ----- | ------ | ---- | ---------------------------------------- | 60| event | object | 否 | 获取XComponent实例对象的context，context上挂载的方法由开发者在c++层定义。 | 61 62### onDestroy 63 64onDestroy(event: () => void ) 65 66插件卸载完成时回调事件。 67 68## XComponentController 69 70xcomponent 组件的控制器，可以将此对象绑定至XComponent组件，然后通过控制器来调用组件方法。 71 72### 创建对象 73 74``` 75xcomponentController: XComponentController = new XComponentController() 76``` 77 78### getXComponentSurfaceId 79 80getXComponentSurfaceId(): string 81 82获取XComponent对应Surface的ID，供@ohos接口使用，使用方式可参考[相机管理](../apis/js-apis-camera.md)，仅XComponent类型为"surface"时有效。 83 84 85**返回值:** 86 87| 类型 | 描述 | 88| ------ | ----------------------- | 89| string | XComponent持有Surface的ID。 | 90 91 92### setXComponentSurfaceSize 93 94setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): void 95 96设置XComponent持有Surface的宽度和高度，仅XComponent类型为"surface"时有效。 97 98 99**参数:** 100 101| 参数名 | 参数类型 | 必填 | 描述 | 102| ------------- | ------ | ---- | ----------------------- | 103| surfaceWidth | number | 是 | XComponent持有Surface的宽度。 | 104| surfaceHeight | number | 是 | XComponent持有Surface的高度。 | 105 106 107### getXComponentContext 108 109getXComponentContext(): Object 110 111获取XComponent实例对象的context，仅XComponent类型为"surface"时有效。 112 113**返回值:** 114 115| 类型 | 描述 | 116| ------ | ---------------------------------------- | 117| Object | 获取XComponent实例对象的context，context包含的具体接口方法由开发者自定义。 | 118 119 120## 示例 121 122示例效果请以真机运行为准，当前IDE预览器不支持。 123 124```ts 125// xxx.ets 126@Entry 127@Component 128struct PreviewArea { 129 private surfaceId : string ='' 130 xcomponentController: XComponentController = new XComponentController() 131 build() { 132 Row() { 133 XComponent({ 134 id: 'xcomponent', 135 type: 'surface', 136 controller: this.xcomponentController 137 }) 138 .onLoad(() => { 139 this.xcomponentController.setXComponentSurfaceSize({surfaceWidth:1920,surfaceHeight:1080}); 140 this.surfaceId = this.xcomponentController.getXComponentSurfaceId() 141 }) 142 .width('640px') 143 .height('480px') 144 } 145 .backgroundColor(Color.Black) 146 .position({x: 0, y: 48}) 147 } 148} 149``` 150