1# XComponent
2
3**XComponent** provides a surface for graphics rendering and media data input into your view. You can customize the position and size of the surface as needed. For details, see [Native XComponent](../../../ui/napi-xcomponent-guidelines.md).
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
11Not supported
12
13## APIs
14
15### XComponent<sup>12+</sup>
16
17XComponent(options: XComponentOptions)
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name | Type                               | Mandatory| Description                          |
26| ------- | --------------------------------------- | ---- | ------------------------------ |
27| options | [XComponentOptions](#xcomponentoptions12) | Yes  | Options of the **XComponent**.|
28
29### XComponent<sup>10+</sup>
30
31XComponent(value: {id: string, type: XComponentType, libraryname?: string, controller?: XComponentController})
32
33This API is deprecated since API version 12. You are advised to use [XComponent(options: XComponentOptions)](#xcomponent12) instead.
34
35**Atomic service API**: This API can be used in atomic services since API version 12.
36
37**System capability**: SystemCapability.ArkUI.ArkUI.Full
38
39**Parameters**
40
41| Name     | Type                                     | Mandatory| Description                                                        |
42| ----------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
43| id          | string                                        | Yes  | Unique ID of the component. The value can contain a maximum of 128 characters.                   |
44| type        | [XComponentType](ts-appendix-enums.md#xcomponenttype10)   | Yes  | Type of the component.                                |
45| libraryname | string                                        | No  | Name of the dynamic library compiled and output by the native layer (the corresponding dynamic library does not support cross-module loading). This parameter is effective only when **type** is **SURFACE** or **TEXTURE**.|
46| controller  | [XComponentController](#xcomponentcontroller) | No  | Controller bound to the component, which can be used to invoke methods of the component. This parameter is effective only when **type** is **SURFACE** or **TEXTURE**.|
47
48### XComponent<sup>(deprecated)</sup>
49
50XComponent(value: {id: string, type: string, libraryname?: string, controller?: XComponentController})
51
52> **NOTE**
53>
54> This API is deprecated since API version 12. You are advised to use [XComponent(options: XComponentOptions)](#xcomponent12) instead.
55
56**System capability**: SystemCapability.ArkUI.ArkUI.Full
57
58**Parameters**
59
60| Name     | Type                                     | Mandatory| Description                                                        |
61| ----------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
62| id          | string                                        | Yes  | Unique ID of the component. The value can contain a maximum of 128 characters.                   |
63| 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 acts a container where non-UI logic can be executed to dynamically load and display content.<br>Any other value is handled as **"surface"**.|
64| libraryname | string                                        | No  | Name of the dynamic library compiled and output by the native layer (the corresponding dynamic library does not support cross-module loading). This parameter is effective only when **type** is **"surface"**.|
65| 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"**.|
66
67## XComponentOptions<sup>12+</sup>
68
69Defines the options of the **XComponent**.
70
71**Atomic service API**: This API can be used in atomic services since API version 12.
72
73**System capability**: SystemCapability.ArkUI.ArkUI.Full
74
75| Name| Type| Mandatory| Description|
76| -------- | -------- | -------- | -------- |
77| type | [XComponentType](ts-appendix-enums.md#xcomponenttype10)         | Yes  | Type of the component.|
78| controller | [XComponentController](#xcomponentcontroller) | Yes| 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**.|
79| imageAIOptions | [ImageAIOptions](ts-image-common.md#imageaioptions) | No| AI image analysis options. You can configure the analysis type or bind an analyzer controller through this parameter.|
80
81
82## Attributes
83In addition to universal attributes, the following attributes are supported.
84  >
85  > **NOTE**
86  >
87  > The **foregroundColor**, **obscured**, and **pixelStretchEffect** attributes are not supported. When **type** is set to **SURFACE**, the following are not supported either: attribute modifier, custom drawing, background options (except **backgroundColor**), image effects (except **shadow**), **maskShape**, and **foregroundEffect** attributes.
88  >
89  > For the **XComponent** component of the TEXTURE or SURFACE type, if the [renderFit](./ts-universal-attributes-renderfit.md) attribute is not set, it defaults to **RenderFit.RESIZE_FILL**.
90  >
91  > For the **XComponent** component of the SURFACE type with an opaque black background, the [renderFit](./ts-universal-attributes-renderfit.md) attribute can only be set to **RenderFit.RESIZE_FILL**. Other **RenderFit** enum values are not recommended.
92  >
93  > For the **XComponent** component created using the [ArkUI NDK API](../../../ui/ndk-access-the-arkts-page.md), the [getAttribute](../_ark_u_i___native_node_a_p_i__1.md#getattribute) function is not supported for obtaining the **renderFit** attribute value.
94
95### enableAnalyzer<sup>12+</sup>
96
97enableAnalyzer(enable: boolean)
98
99Sets whether to enable the AI image analyzer, which supports subject recognition, text recognition, and object lookup.
100For the settings to take effect, this attribute must be used together with [StartImageAnalyzer](#startimageanalyzer12) and [StopImageAnalyzer](#stopimageanalyzer12) of **XComponentController**.
101This feature cannot be used together with the [overlay](ts-universal-attributes-overlay.md) attribute. If both are set, the **CustomBuilder** attribute in **overlay** has no effect. This feature also depends on device capabilities.
102
103**Atomic service API**: This API can be used in atomic services since API version 12.
104
105**System capability**: SystemCapability.ArkUI.ArkUI.Full
106
107**Parameters**
108
109| Name| Type| Mandatory| Description|
110| -------- | -------- | -------- | -------- |
111| enable | boolean | Yes| Whether to enable the AI image analyzer.|
112
113  > **NOTE**
114  >
115  > This API has effect only when **type** is set to **SURFACE** or **TEXTURE**.
116
117### enableSecure<sup>13+</sup>
118
119enableSecure(isSecure: boolean)
120
121Sets whether to enable the secure surface to protect the content rendered within the component from being captured or recorded.
122
123**Atomic service API**: This API can be used in atomic services since API version 13.
124
125**System capability**: SystemCapability.ArkUI.ArkUI.Full
126
127**Parameters**
128
129| Name  | Type   | Mandatory| Description                  |
130| -------- | ------- | ---- | ---------------------- |
131| isSecure | boolean | Yes  | Whether to enable the secure surface.|
132
133  > **NOTE**
134  >
135  > This attribute is effective only when **type** is set to **SURFACE**.
136  >
137  > The **XComponent** created using the[ArkUI NDK APIs](../../../ui/ndk-build-ui-overview.md) is not supported.
138
139## Events
140
141Since API version 12, the [universal events](ts-universal-events-click.md) are supported when **type** is set to **SURFACE** or **TEXTURE**.
142
143> **NOTE**
144>
145> When the **libraryname** parameter is set, [click events](ts-universal-events-click.md), [touch events](ts-universal-events-touch.md), [show/hide events](ts-universal-events-show-hide.md), [key events](ts-universal-events-key.md), [focus events](ts-universal-focus-event.md), and [mouse events](ts-universal-mouse-key.md) only respond to event APIs on the C-API side.
146
147**Atomic service API**: This API can be used in atomic services since API version 12.
148
149The following events are effective only when **type** is set to **SURFACE** or **TEXTURE**.
150
151### onLoad
152
153onLoad(callback: (event?: object) => void )
154
155Triggered when the plug-in is loaded.
156
157**Atomic service API**: This API can be used in atomic services since API version 14.
158
159**System capability**: SystemCapability.ArkUI.ArkUI.Full
160
161**Parameters**
162
163| Name  | Type  | Mandatory  | Description                                      |
164| ----- | ------ | ---- | ---------------------------------------- |
165| event | object | No   | Context of the **XComponent** object. The APIs contained in the context are defined at the native layer by developers.|
166
167### onDestroy
168
169onDestroy(event: VoidCallback )
170
171Triggered when the plug-in is destroyed.
172
173**Atomic service API**: This API can be used in atomic services since API version 14.
174
175**System capability**: SystemCapability.ArkUI.ArkUI.Full
176
177**Parameters**
178
179| Name  | Type  | Mandatory  | Description                                      |
180| ----- | ------ | ---- | ---------------------------------------- |
181| event | [VoidCallback](ts-types.md#voidcallback12) | Yes   | Callback after the **XComponent** is destroyed.|
182
183## XComponentController
184
185Defines the controller of the **XComponent**. You can bind the controller to the **XComponent** to call the component APIs through the controller.
186
187**Atomic service API**: This API can be used in atomic services since API version 12.
188
189**System capability**: SystemCapability.ArkUI.ArkUI.Full
190
191### Creating an Object
192
193```
194xcomponentController: XComponentController = new XComponentController()
195```
196
197**Atomic service API**: This API can be used in atomic services since API version 12.
198
199### constructor
200
201constructor()
202
203A constructor used to create a **XComponentController** instance.
204
205**Atomic service API**: This API can be used in atomic services since API version 12.
206
207**System capability**: SystemCapability.ArkUI.ArkUI.Full
208
209### getXComponentSurfaceId<sup>9+</sup>
210
211getXComponentSurfaceId(): string
212
213Obtains the ID of the surface held by the **XComponent**, which can then be used for @ohos APIs. For details, see [Camera Management](../../apis-camera-kit/js-apis-camera.md). This API works only when **type** of the **XComponent** is set to **SURFACE("surface")** or **TEXTURE**.
214
215**Atomic service API**: This API can be used in atomic services since API version 12.
216
217**System capability**: SystemCapability.ArkUI.ArkUI.Full
218
219**Return value**
220
221| Type    | Description                     |
222| ------ | ----------------------- |
223| string | ID of the surface held by the **XComponent**.|
224
225
226### setXComponentSurfaceSize<sup>(deprecated)</sup>
227
228setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): void
229
230Sets 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**.
231
232This API is deprecated since API version 12. You are advised to use [setXComponentSurfaceRect](#setxcomponentsurfacerect12) instead.
233
234**System capability**: SystemCapability.ArkUI.ArkUI.Full
235
236**Parameters**
237
238| Name          | Type  | Mandatory  | Description                     |
239| ------------- | ------ | ---- | ----------------------- |
240| surfaceWidth  | number | Yes   | Width of the surface held by the **XComponent**.|
241| surfaceHeight | number | Yes   | Height of the surface held by the **XComponent**.|
242
243
244### getXComponentContext
245
246getXComponentContext(): Object
247
248Obtains the context of an **XComponent** object. This API works only when **type** of the **XComponent** is set to **SURFACE("surface")** or **TEXTURE**.
249
250**Atomic service API**: This API can be used in atomic services since API version 12.
251
252**System capability**: SystemCapability.ArkUI.ArkUI.Full
253
254**Return value**
255
256| Type  | Description                                                        |
257| ------ | ------------------------------------------------------------ |
258| Object | Context of the **XComponent** object. The APIs contained in the context are defined by developers. The context is passed in as the first parameter of the **onLoad** callback.|
259
260### setXComponentSurfaceRect<sup>12+</sup>
261
262setXComponentSurfaceRect(rect: SurfaceRect): void
263
264Sets the rectangle for the surface held by the **XComponent**. This API works only when type of the **XComponent** is set to **SURFACE("surface")** or **TEXTURE**.
265
266**Atomic service API**: This API can be used in atomic services since API version 12.
267
268**System capability**: SystemCapability.ArkUI.ArkUI.Full
269
270**Parameters**
271
272| Name| Type                            | Mandatory| Description                             |
273| ------ | ------------------------------------ | ---- | --------------------------------- |
274| rect   | [SurfaceRect](#surfacerect12) | Yes  | Rectangle of the surface held by the **XComponent**.|
275
276> **NOTE**
277>
278> If **offsetX** or **offsetY** in the **rect** parameter is not set, the surface rectangle is centered along the x-axis or y-axis relative to the upper left corner of the **XComponent**.
279>
280> If **surfaceWidth** and **surfaceHeight** in the **rect** parameter are set to **0** or a negative value, this API has no effect.
281>
282> This API has a higher priority than attributes that can change the content offset and size, such as [border](ts-universal-attributes-border.md#border) and [padding](ts-universal-attributes-size.md#padding).
283
284### getXComponentSurfaceRect<sup>12+</sup>
285
286getXComponentSurfaceRect(): SurfaceRect
287
288Obtains the rectangle of the surface held by the **XComponent**. This API works only when type of the **XComponent** is set to **SURFACE("surface")** or **TEXTURE**.
289
290**Atomic service API**: This API can be used in atomic services since API version 12.
291
292**System capability**: SystemCapability.ArkUI.ArkUI.Full
293
294**Return value**
295
296| Type                                | Description                                 |
297| ------------------------------------ | ------------------------------------- |
298| [SurfaceRect](#surfacerect12) | Rectangle of the surface held by the **XComponent**.|
299
300### onSurfaceCreated<sup>12+</sup>
301
302onSurfaceCreated(surfaceId: string): void
303
304Triggered when the surface held by the **XComponent** is created. This API works only when **type** of the **XComponent** is set to **SURFACE("surface")** or **TEXTURE**.
305
306**Atomic service API**: This API can be used in atomic services since API version 12.
307
308**System capability**: SystemCapability.ArkUI.ArkUI.Full
309
310**Parameters**
311
312| Name   | Type| Mandatory| Description                                             |
313| --------- | -------- | ---- | ------------------------------------------------- |
314| surfaceId | string   | Yes  | ID of the surface held by the **XComponent**.|
315
316> **NOTE**
317>
318> The callback is triggered only when the **libraryname** parameter is not set for the **XComponent**.
319
320### onSurfaceChanged<sup>12+</sup>
321
322onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void
323
324Triggered when the surface held by the **XComponent** has its size changed (including the time when the **XComponent** is created with the specified size). This API works only when **type** of the **XComponent** is set to **SURFACE** (**"surface"**) or **TEXTURE**.
325
326**Atomic service API**: This API can be used in atomic services since API version 12.
327
328**System capability**: SystemCapability.ArkUI.ArkUI.Full
329
330**Parameters**
331
332| Name   | Type                             | Mandatory| Description                                                   |
333| --------- | ------------------------------------- | ---- | ------------------------------------------------------- |
334| surfaceId | string                                | Yes  | ID of the surface held by the **XComponent**.      |
335| rect      | [SurfaceRect](#surfacerect12) | Yes  | Rectangle for displaying the surface held by the **XComponent**.|
336
337> **NOTE**
338>
339> The callback is triggered only when the **libraryname** parameter is not set for the **XComponent**.
340
341### onSurfaceDestroyed<sup>12+</sup>
342
343onSurfaceDestroyed(surfaceId: string): void
344
345Triggered when the surface held by the **XComponent** is destroyed. This API works only when **type** of the **XComponent** is set to **SURFACE** (**"surface"**) or **TEXTURE**.
346
347**Atomic service API**: This API can be used in atomic services since API version 12.
348
349**System capability**: SystemCapability.ArkUI.ArkUI.Full
350
351**Parameters**
352
353| Name   | Type| Mandatory| Description                                             |
354| --------- | -------- | ---- | ------------------------------------------------- |
355| surfaceId | string   | Yes  | ID of the surface held by the **XComponent**.|
356
357> **NOTE**
358>
359> The callback is triggered only when the **libraryname** parameter is not set for the **XComponent**.
360
361### startImageAnalyzer<sup>12+</sup>
362
363startImageAnalyzer(config: ImageAnalyzerConfig): Promise\<void>
364
365Starts AI image analysis in the given settings. Before calling this API, make sure the AI image analyzer is [enabled](#enableanalyzer12).<br>Because the image frame used for analysis is the one captured when this API is called, pay attention to the invoking time of this API.<br>If this API is repeatedly called before the execution is complete, an error callback is triggered.
366
367> **NOTE**
368>
369> The image analysis type cannot be dynamically modified.
370>
371> This API depends on device capabilities. If it is called on an incompatible device, an error code is returned.
372
373**Atomic service API**: This API can be used in atomic services since API version 12.
374
375**System capability**: SystemCapability.ArkUI.ArkUI.Full
376
377**Parameters**
378
379| Name| Type     | Mandatory| Description                                                                  |
380| ------ | --------- | ---- | ---------------------------------------------------------------------- |
381| config   | [ImageAnalyzerConfig](ts-image-common.md#imageanalyzerconfig) | Yes  | Settings of the AI image analyzer.|
382
383**Return value**
384
385| Type             | Description                                |
386| ----------------- | ------------------------------------ |
387| Promise\<void>  | Promise used to return the result.|
388
389**Error codes**
390
391For details about the error codes, see [AI Image Analyzer Error Codes](../errorcode-image-analyzer.md).
392
393| ID| Error Message                                     |
394| -------- | -------------------------------------------- |
395| 110001 | Image analysis feature is unsupported.               |
396| 110002 | Image analysis is currently being executed.  |
397| 110003 | Image analysis is stopped.  |
398
399### stopImageAnalyzer<sup>12+</sup>
400
401stopImageAnalyzer(): void
402
403Stops AI image analysis. The content displayed by the AI image analyzer will be destroyed.
404
405> **NOTE**
406>
407> If this API is called when the **startImageAnalyzer** API has not yet returned any result, an error callback is triggered.
408>
409> This feature depends on device capabilities.
410
411**Atomic service API**: This API can be used in atomic services since API version 12.
412
413**System capability**: SystemCapability.ArkUI.ArkUI.Full
414
415### setXComponentSurfaceRotation<sup>12+</sup>
416
417setXComponentSurfaceRotation(rotationOptions: SurfaceRotationOptions): void
418
419Sets whether to lock the orientation of the surface held by this **XComponent** when the screen rotates. This API is effective only when the **XComponent** type is **SURFACE** (**"surface"**).
420
421**Atomic service API**: This API can be used in atomic services since API version 12.
422
423**System capability**: SystemCapability.ArkUI.ArkUI.Full
424
425**Parameters**
426
427| Name| Type                            | Mandatory| Description                             |
428| ------ | ------------------------------------ | ---- | --------------------------------- |
429| rotationOptions   | [SurfaceRotationOptions](#surfacerotationoptions12) | Yes| Whether to lock the orientation of the surface held by the current **XComponent** when the screen rotates.|
430
431> **NOTE**
432>
433> If **rotationOptions** is not set, the surface held by this **XComponent** rotates with the screen by default.
434>
435> The orientation lock is only applied during the rotation process and is released once the rotation is complete.
436>
437> The setting takes effect only when the screen is rotated by 90°, that is, when it switches between landscape and portrait modes.
438>
439> Make sure the Buffer's width and height remain constant after locking the orientation to prevent distortion.
440
441### getXComponentSurfaceRotation<sup>12+</sup>
442
443getXComponentSurfaceRotation(): Required\<SurfaceRotationOptions>
444
445Obtains whether the orientation of the surface held by this **XComponent** is locked when the screen rotates. This API is effective only when the **XComponent** type is **SURFACE** (**"surface"**).
446
447**Atomic service API**: This API can be used in atomic services since API version 12.
448
449**System capability**: SystemCapability.ArkUI.ArkUI.Full
450
451**Return value**
452
453| Type                                | Description                                 |
454| ------------------------------------ | ------------------------------------- |
455| [SurfaceRotationOptions](#surfacerotationoptions12) | Whether the orientation of the surface held by the current **XComponent** is locked when the screen rotates.|
456
457## SurfaceRotationOptions<sup>12+</sup>
458
459Defines whether the orientation of the surface held by the current **XComponent** is locked when the screen rotates.
460
461**Atomic service API**: This API can be used in atomic services since API version 12.
462
463**System capability**: SystemCapability.ArkUI.ArkUI.Full
464
465| Name         | Type  | Mandatory| Description                                                        |
466| ------------- | ------ | ---- | ------------------------------------------------------------ |
467| lock       | boolean | No  | Whether the orientation of the surface is locked when the screen rotates. If this parameter is not set, the default value **false** is used, indicating that the orientation is not locked.|
468
469## SurfaceRect<sup>12+</sup>
470
471Describes the rectangle of the surface held by the **XComponent**.
472
473**Atomic service API**: This API can be used in atomic services since API version 12.
474
475**System capability**: SystemCapability.ArkUI.ArkUI.Full
476
477| Name         | Type  | Mandatory| Description                                                        |
478| ------------- | ------ | ---- | ------------------------------------------------------------ |
479| offsetX       | number | No  | X coordinate of the surface rectangle relative to the upper left corner of the **XComponent**.<br>Unit: px|
480| offsetY       | number | No  | Y coordinate of the surface rectangle relative to the upper left corner of the **XComponent**.<br>Unit: px|
481| surfaceWidth  | number | Yes  | Width of the surface rectangle.<br>Unit: px                           |
482| surfaceHeight | number | Yes  | Height of the surface rectangle.<br>Unit: px                           |
483
484> **NOTE**
485>
486> The **surfaceWidth** and **surfaceHeight** attributes default to the size of the **XComponent** if the [setXComponentSurfaceRect](ts-basic-components-xcomponent.md#setxcomponentsurfacerect12) API is not called and neither [border](ts-universal-attributes-border.md#border) nor [padding](ts-universal-attributes-size.md#padding) is set.
487>
488> Make sure the values of **surfaceWidth** and **surfaceHeight** do not exceed 8192 px. Exceeding this limit may lead to rendering issues.
489
490## Example
491
492You can preview how this component looks on a real device, but not in DevEco Studio Previewer.
493
494
495### Example 1: Enabling AI Image Analyzer
496
497This example shows how to use the **enableAnalyzer** attribute to enable AI image analyzer. You can use **XComponentController** to start or stop AI analysis on images.
498
499```ts
500// xxx.ets
501import { BusinessError } from '@kit.BasicServicesKit';
502import nativeRender from 'libnativerender.so';
503
504class CustomXComponentController extends XComponentController {
505  onSurfaceCreated(surfaceId: string): void {
506    console.log(`onSurfaceCreated surfaceId: ${surfaceId}`);
507    nativeRender.SetSurfaceId(BigInt(surfaceId));
508  }
509
510  onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
511    console.log(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}}`);
512    nativeRender.ChangeSurface(BigInt(surfaceId), rect.surfaceWidth, rect.surfaceHeight);
513  }
514
515  onSurfaceDestroyed(surfaceId: string): void {
516    console.log(`onSurfaceDestroyed surfaceId: ${surfaceId}`);
517    nativeRender.DestroySurface(BigInt(surfaceId));
518  }
519}
520
521@Entry
522@Component
523struct XComponentExample {
524  xComponentController: XComponentController = new CustomXComponentController();
525  private config: ImageAnalyzerConfig = {
526    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
527  };
528  private aiController: ImageAnalyzerController = new ImageAnalyzerController();
529  private options: ImageAIOptions = {
530    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
531    aiController: this.aiController
532  };
533  @State xcWidth: string = "320px";
534  @State xcHeight: string = "480px";
535  @State currentStatus: string = "index";
536
537  build() {
538    Column({ space: 5 }) {
539      Button("change size")
540        .onClick(() => {
541          this.xcWidth = "640px";
542          this.xcHeight = "720px";
543        })
544      Button('start AI analyze')
545        .onClick(() => {
546          this.xComponentController.startImageAnalyzer(this.config)
547            .then(() => {
548              console.log("analysis complete");
549            })
550            .catch((error: BusinessError) => {
551              console.log("error code: " + error.code);
552            })
553        })
554      Button('stop AI analyze')
555        .onClick(() => {
556          this.xComponentController.stopImageAnalyzer();
557        })
558      Button('get analyzer types')
559        .onClick(() => {
560          this.aiController.getImageAnalyzerSupportTypes();
561        })
562      Button('Draw Star')
563        .fontSize('16fp')
564        .fontWeight(500)
565        .margin({ bottom: 24 })
566        .onClick(() => {
567          let surfaceId = this.xComponentController.getXComponentSurfaceId();
568          this.xComponentController.getXComponentSurfaceRect();
569          nativeRender.DrawPattern(BigInt(surfaceId));
570          let hasDraw: boolean = false;
571          if (nativeRender.GetXComponentStatus(BigInt(surfaceId))) {
572            hasDraw = nativeRender.GetXComponentStatus(BigInt(surfaceId)).hasDraw;
573          }
574          if (hasDraw) {
575            this.currentStatus = "draw star";
576          }
577        })
578      XComponent({
579        type: XComponentType.SURFACE,
580        controller: this.xComponentController,
581        imageAIOptions: this.options
582      })
583        .width(this.xcWidth)
584        .height(this.xcHeight)
585        .enableAnalyzer(true)
586      Text(this.currentStatus)
587        .fontSize('24fp')
588        .fontWeight(500)
589    }
590    .width("100%")
591  }
592}
593```
594<!--RP1--><!--RP1End-->
595
596### Example 2: Locking the Surface Orientation During Screen Rotation
597
598This example shows how to use **setXComponentSurfaceRotation** to lock the surface orientation during screen rotation so that the surface does not rotate with the screen.
599
600```ts
601// xxx.ets
602@Entry
603@Component
604struct Index{
605  @State isLock: boolean = true;
606  @State xc_width: number = 500;
607  @State xc_height: number = 700;
608  myXComponentController: XComponentController = new XComponentController();
609
610  build() {
611    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Start }) {
612      XComponent({
613        id: 'xComponentId',
614        type: XComponentType.SURFACE,
615        libraryname: 'nativerender',
616        controller: this.myXComponentController
617      })
618      .width(this.xc_width)
619      .height(this.xc_height)
620      .onLoad(() => {
621        let surfaceRotation: SurfaceRotationOptions = { lock: this.isLock };
622        this.myXComponentController.setXComponentSurfaceRotation(surfaceRotation);
623        console.log("Surface getXComponentSurfaceRotation lock = " +
624          this.myXComponentController.getXComponentSurfaceRotation().lock);
625      })
626    }
627    .width('100%')
628    .height('100%')
629  }
630}
631```
632