XComponent

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.

NOTE

This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.

Child Components

Not supported

APIs

XComponent¹²⁺

XComponent(options: XComponentOptions)

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

XComponent¹⁰⁺

XComponent(value: {id: string, type: XComponentType, libraryname?: string, controller?: XComponentController})

This API is deprecated since API version 12. You are advised to use XComponent(options: XComponentOptions) instead.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

XComponent^(deprecated)

XComponent(value: {id: string, type: string, libraryname?: string, controller?: XComponentController})

NOTE

This API is deprecated since API version 12. You are advised to use XComponent(options: XComponentOptions) instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

XComponentOptions¹²⁺

Defines the options of the XComponent.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Attributes

In addition to universal attributes, the following attributes are supported. > > NOTE > > 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. > > For the XComponent component of the TEXTURE or SURFACE type, if the renderFit attribute is not set, it defaults to RenderFit.RESIZE_FILL. > > For the XComponent component of the SURFACE type with an opaque black background, the renderFit attribute can only be set to RenderFit.RESIZE_FILL. Other RenderFit enum values are not recommended. > > For the XComponent component created using the ArkUI NDK API, the getAttribute function is not supported for obtaining the renderFit attribute value.

enableAnalyzer¹²⁺

enableAnalyzer(enable: boolean)

Sets whether to enable the AI image analyzer, which supports subject recognition, text recognition, and object lookup. For the settings to take effect, this attribute must be used together with StartImageAnalyzer and StopImageAnalyzer of XComponentController. This feature cannot be used together with the overlay attribute. If both are set, the CustomBuilder attribute in overlay has no effect. This feature also depends on device capabilities.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

This API has effect only when type is set to SURFACE or TEXTURE.

enableSecure¹³⁺

enableSecure(isSecure: boolean)

Sets whether to enable the secure surface to protect the content rendered within the component from being captured or recorded.

Atomic service API: This API can be used in atomic services since API version 13.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

This attribute is effective only when type is set to SURFACE.

The XComponent created using theArkUI NDK APIs is not supported.

Events

Since API version 12, the universal events are supported when type is set to SURFACE or TEXTURE.

NOTE

When the libraryname parameter is set, click events, touch events, show/hide events, key events, focus events, and mouse events only respond to event APIs on the C-API side.

Atomic service API: This API can be used in atomic services since API version 12.

The following events are effective only when type is set to SURFACE or TEXTURE.

onLoad

onLoad(callback: OnNativeLoadCallback )

Triggered when the plug-in is loaded.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

onDestroy

onDestroy(event: VoidCallback )

Triggered when the plug-in is destroyed.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

OnNativeLoadCallback¹⁴⁺

type OnNativeLoadCallback = (event?: object) => void

Triggered after the surface held by the XComponent is created.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

XComponentController

Defines the controller of the XComponent. You can bind the controller to the XComponent to call the component APIs through the controller.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Creating an Object

xcomponentController: XComponentController = new XComponentController()

Atomic service API: This API can be used in atomic services since API version 12.

constructor

constructor()

A constructor used to create a XComponentController instance.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

getXComponentSurfaceId⁹⁺

getXComponentSurfaceId(): string

Obtains the ID of the surface held by the XComponent, which can then be used for @ohos APIs. For details, see Camera Management. This API works only when type of the XComponent is set to SURFACE(“surface”) or TEXTURE.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

setXComponentSurfaceSize^(deprecated)

setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): void

Sets 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.

This API is deprecated since API version 12. You are advised to use setXComponentSurfaceRect instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

getXComponentContext

getXComponentContext(): Object

Obtains the context of an XComponent object. This API works only when type of the XComponent is set to SURFACE(“surface”) or TEXTURE.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

setXComponentSurfaceRect¹²⁺

setXComponentSurfaceRect(rect: SurfaceRect): void

Sets 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.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

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.

If surfaceWidth and surfaceHeight in the rect parameter are set to 0 or a negative value, this API has no effect.

This API has a higher priority than attributes that can change the content offset and size, such as border and padding.

getXComponentSurfaceRect¹²⁺

getXComponentSurfaceRect(): SurfaceRect

Obtains 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.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

onSurfaceCreated¹²⁺

onSurfaceCreated(surfaceId: string): void

Triggered 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.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

The callback is triggered only when the libraryname parameter is not set for the XComponent.

onSurfaceChanged¹²⁺

onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void

Triggered 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.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

The callback is triggered only when the libraryname parameter is not set for the XComponent.

onSurfaceDestroyed¹²⁺

onSurfaceDestroyed(surfaceId: string): void

Triggered 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.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

The callback is triggered only when the libraryname parameter is not set for the XComponent.

startImageAnalyzer¹²⁺

startImageAnalyzer(config: ImageAnalyzerConfig): Promise<void>

Starts AI image analysis in the given settings. Before calling this API, make sure the AI image analyzer is enabled.
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.
If this API is repeatedly called before the execution is complete, an error callback is triggered.

NOTE

The image analysis type cannot be dynamically modified.

This API depends on device capabilities. If it is called on an incompatible device, an error code is returned.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Return value

Error codes

For details about the error codes, see AI Image Analyzer Error Codes.

stopImageAnalyzer¹²⁺

stopImageAnalyzer(): void

Stops AI image analysis. The content displayed by the AI image analyzer will be destroyed.

NOTE

If this API is called when the startImageAnalyzer API has not yet returned any result, an error callback is triggered.

This feature depends on device capabilities.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

setXComponentSurfaceRotation¹²⁺

setXComponentSurfaceRotation(rotationOptions: SurfaceRotationOptions): void

Sets 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”).

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

If rotationOptions is not set, the surface held by this XComponent rotates with the screen by default.

The orientation lock is only applied during the rotation process and is released once the rotation is complete.

The setting takes effect only when the screen is rotated by 90°, that is, when it switches between landscape and portrait modes.

Make sure the Buffer’s width and height remain constant after locking the orientation to prevent distortion.

getXComponentSurfaceRotation¹²⁺

getXComponentSurfaceRotation(): Required<SurfaceRotationOptions>

Obtains 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”).

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

SurfaceRotationOptions¹²⁺

Defines whether the orientation of the surface held by the current XComponent is locked when the screen rotates.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

SurfaceRect¹²⁺

Describes the rectangle of the surface held by the XComponent.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

NOTE

The surfaceWidth and surfaceHeight attributes default to the size of the XComponent if the setXComponentSurfaceRect API is not called and neither border nor padding is set.

Make sure the values of surfaceWidth and surfaceHeight do not exceed 8192 px. Exceeding this limit may lead to rendering issues.

Example

You can preview how this component looks on a real device, but not in DevEco Studio Previewer.

Example 1: Enabling AI Image Analyzer

This 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.

// xxx.ets
import { BusinessError } from '@kit.BasicServicesKit';
import nativeRender from 'libnativerender.so';

class CustomXComponentController extends XComponentController {
  onSurfaceCreated(surfaceId: string): void {
    console.log(`onSurfaceCreated surfaceId: ${surfaceId}`);
    nativeRender.SetSurfaceId(BigInt(surfaceId));
  }

  onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
    console.log(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}}`);
    nativeRender.ChangeSurface(BigInt(surfaceId), rect.surfaceWidth, rect.surfaceHeight);
  }

  onSurfaceDestroyed(surfaceId: string): void {
    console.log(`onSurfaceDestroyed surfaceId: ${surfaceId}`);
    nativeRender.DestroySurface(BigInt(surfaceId));
  }
}

@Entry
@Component
struct XComponentExample {
  xComponentController: XComponentController = new CustomXComponentController();
  private config: ImageAnalyzerConfig = {
    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
  };
  private aiController: ImageAnalyzerController = new ImageAnalyzerController();
  private options: ImageAIOptions = {
    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
    aiController: this.aiController
  };
  @State xcWidth: string = "320px";
  @State xcHeight: string = "480px";
  @State currentStatus: string = "index";

  build() {
    Column({ space: 5 }) {
      Button("change size")
        .onClick(() => {
          this.xcWidth = "640px";
          this.xcHeight = "720px";
        })
      Button('start AI analyze')
        .onClick(() => {
          this.xComponentController.startImageAnalyzer(this.config)
            .then(() => {
              console.log("analysis complete");
            })
            .catch((error: BusinessError) => {
              console.log("error code: " + error.code);
            })
        })
      Button('stop AI analyze')
        .onClick(() => {
          this.xComponentController.stopImageAnalyzer();
        })
      Button('get analyzer types')
        .onClick(() => {
          this.aiController.getImageAnalyzerSupportTypes();
        })
      Button('Draw Star')
        .fontSize('16fp')
        .fontWeight(500)
        .margin({ bottom: 24 })
        .onClick(() => {
          let surfaceId = this.xComponentController.getXComponentSurfaceId();
          this.xComponentController.getXComponentSurfaceRect();
          nativeRender.DrawPattern(BigInt(surfaceId));
          let hasDraw: boolean = false;
          if (nativeRender.GetXComponentStatus(BigInt(surfaceId))) {
            hasDraw = nativeRender.GetXComponentStatus(BigInt(surfaceId)).hasDraw;
          }
          if (hasDraw) {
            this.currentStatus = "draw star";
          }
        })
      XComponent({
        type: XComponentType.SURFACE,
        controller: this.xComponentController,
        imageAIOptions: this.options
      })
        .width(this.xcWidth)
        .height(this.xcHeight)
        .enableAnalyzer(true)
      Text(this.currentStatus)
        .fontSize('24fp')
        .fontWeight(500)
    }
    .width("100%")
  }
}

Example 2: Locking the Surface Orientation During Screen Rotation

This example shows how to use setXComponentSurfaceRotation to lock the surface orientation during screen rotation so that the surface does not rotate with the screen.

// xxx.ets
@Entry
@Component
struct Index{
  @State isLock: boolean = true;
  @State xc_width: number = 500;
  @State xc_height: number = 700;
  myXComponentController: XComponentController = new XComponentController();

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Start }) {
      XComponent({
        id: 'xComponentId',
        type: XComponentType.SURFACE,
        libraryname: 'nativerender',
        controller: this.myXComponentController
      })
      .width(this.xc_width)
      .height(this.xc_height)
      .onLoad(() => {
        let surfaceRotation: SurfaceRotationOptions = { lock: this.isLock };
        this.myXComponentController.setXComponentSurfaceRotation(surfaceRotation);
        console.log("Surface getXComponentSurfaceRotation lock = " +
          this.myXComponentController.getXComponentSurfaceRotation().lock);
      })
    }
    .width('100%')
    .height('100%')
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton