1# XComponent 2 3The **\<XComponent>** can accept and display the EGL/OpenGL ES and media data input. 4 5> **NOTE** 6> 7> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11Child components are not supported when **type** is set to **"surface"**. 12 13Since API version 9, child components are supported when **type** is set to **"component"**. 14 15## APIs 16 17### XComponent 18 19XComponent(value: {id: string, type: string, libraryname?: string, controller?: XComponentController}) 20 21**Parameters** 22 23| Name | Type | Mandatory| Description | 24| ----------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 25| id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters. | 26| type | string | Yes | Type of the component. The options are as follows:<br>- **"surface"**: The custom content is displayed individually on the screen. This option is used for displaying EGL/OpenGL ES and media data.<br>- **"component"**<sup>9+</sup>: The component becomes a container where non-UI logic can be executed to dynamically load the display content.<br>Any other value evaluates to **"surface"**.| 27| libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer. This parameter is valid only when **type** is **"surface"**.| 28| controller | [XComponentcontroller](#xcomponentcontroller) | No | Controller bound to the component, which can be used to invoke methods of the component. This parameter is valid only when the component type is **"surface"**.| 29 30### XComponent<sup>10+</sup> 31 32XComponent(value: {id: string, type: XComponentType, libraryname?: string, controller?: XComponentController}) 33 34**Parameters** 35 36| Name | Type | Mandatory| Description | 37| ----------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 38| id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters. | 39| type | [XComponentType](#xcomponenttype10) | Yes | Type of the component. | 40| libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer. This parameter is valid only when **type** is **SURFACE** or **TEXTURE**.| 41| controller | [XComponentcontroller](#xcomponentcontroller) | No | Controller bound to the component, which can be used to invoke methods of the component. This parameter is valid only when **type** is **SURFACE** or **TEXTURE**.| 42 43## XComponentType<sup>10+</sup> 44 45| Name | Description | 46| --------- | ------------------------------------------------------------ | 47| SURFACE | The custom content is displayed individually on the screen. This option is used for displaying EGL/OpenGL ES and media data.| 48| COMPONENT | The component becomes a container where non-UI logic can be executed to dynamically load the display content.| 49| TEXTURE | The custom content of the component is grouped and displayed together with content of the component.| 50 51> **NOTE** 52> 53> When **type** is set to **COMPONENT("component")**, the **\<XComponent>** functions as a container, where child components are laid out vertically. 54> 55> - Vertical alignment: [FlexAlign](ts-appendix-enums.md#flexalign).Start 56> - Horizontal alignment: [FlexAlign](ts-appendix-enums.md#flexalign).Center 57> 58> The component does not respond to any events. 59> 60> Layout changes and event responses can be set by mounting child components. 61> 62> The non-UI logic written internally needs to be encapsulated in one or more functions. 63 64## Attributes 65- You can customize the content displayed in the **\<XComponent>**. Depending on the **type** settings, the support for the universal attributes [background](ts-universal-attributes-background.md), [opacity](ts-universal-attributes-opacity.md), and [image effects](ts-universal-attributes-image-effect.md) varies. 66- When **type** is set to **SURFACE("surface")**, only the **shadow** attribute of [image effects](ts-universal-attributes-image-effect.md). For configuration of other attributes, you are advised to use the APIs provided by EGL/OpenGL ES instead. 67- When **type** is set to **COMPONENT("component")**, only the **shadow** attribute of [image effects](ts-universal-attributes-image-effect.md). For configuration of other attributes, you are advised to mount child components. 68- When **type** is set to **TEXTURE**, only the **backgroundColor** attribute of [background](ts-universal-attributes-background.md), the **shadow** attribute of [image effects](ts-universal-attributes-image-effect.md), and [opacity](ts-universal-attributes-opacity.md) are supported. For configuration of other attributes, you are advised to use the APIs provided by EGL/OpenGL ES instead. 69 70## Events 71 72When **type** is set to **SURFACE("surface")** or **TEXTURE**, the following events are supported. The [universal events](ts-universal-events-click.md) are not supported. 73 74### onLoad 75 76onLoad(callback: (event?: object) => void ) 77 78Triggered when the plug-in is loaded. 79 80**Parameters** 81 82| Name | Type | Mandatory | Description | 83| ----- | ------ | ---- | ---------------------------------------- | 84| event | object | No | Context of the **\<XComponent>** object. The APIs contained in the context are defined at the C++ layer by developers.| 85 86### onDestroy 87 88onDestroy(event: () => void ) 89 90Triggered when the plug-in is destroyed. 91 92## XComponentController 93 94Defines the controller of the **\<XComponent>**. You can bind the controller to the **\<XComponent>** to invoke the methods of the component through the controller. 95 96### Creating an Object 97 98``` 99xcomponentController: XComponentController = new XComponentController() 100``` 101 102### getXComponentSurfaceId 103 104getXComponentSurfaceId(): string 105 106Obtains the ID of the surface held by the **\<XComponent>**, which can then be used for @ohos APIs. For details, see [Camera Management](../apis/js-apis-camera.md). This API works only when **type** of the **\<XComponent>** is set to **SURFACE("surface")** or **TEXTURE**. 107 108 109**Return value** 110 111| Type | Description | 112| ------ | ----------------------- | 113| string | ID of the surface held by the **\<XComponent>**.| 114 115 116### setXComponentSurfaceSize 117 118setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): void 119 120Sets the width and height of the surface held by the **\<XComponent>**. This API works only when **type** of the **\<XComponent>** is set to **SURFACE("surface")** or **TEXTURE**. 121 122 123**Parameters** 124 125| Name | Type | Mandatory | Description | 126| ------------- | ------ | ---- | ----------------------- | 127| surfaceWidth | number | Yes | Width of the surface held by the **\<XComponent>**.| 128| surfaceHeight | number | Yes | Height of the surface held by the **\<XComponent>**.| 129 130 131### getXComponentContext 132 133getXComponentContext(): Object 134 135Obtains the context of an **\<XComponent>** object. This API works only when **type** of the **\<XComponent>** is set to **SURFACE("surface")** or **TEXTURE**. 136 137**Return value** 138 139| Type | Description | 140| ------ | ---------------------------------------- | 141| Object | Context of the **\<XComponent>** object. The APIs contained in the context are defined by developers.| 142 143 144## Example 145 146You can preview how this component looks on a real device, but not in the DevEco Studio Previewer. 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