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