XComponent

可用于EGL/OpenGLES和媒体数据写入，并显示在XComponent组件。

说明：

该组件从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

构造参数type为"surface"时不支持。

从API version 9开始，构造参数type为"component"时可以包含子组件。

接口

XComponent

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

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

XComponent¹⁰⁺

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

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

XComponent¹²⁺

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

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数:

XComponentType¹⁰⁺枚举说明

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

说明：

type为COMPONENT("component")时，XComponent作为容器，子组件沿垂直方向布局：

• 垂直方向上对齐格式：FlexAlign.Start
• 水平方向上对齐格式：FlexAlign.Center

所有的事件响应均不支持。

布局方式更改和事件响应均可通过挂载子组件来设置。

内部所写的非UI逻辑需要封装在一个或多个函数内。

属性

• XComponent显示的内容，可由开发者自定义绘制，通用属性中的背景设置、透明度设置和图像效果按照type类型有限支持。

• type为SURFACE("surface")时仅支持图像效果中的shadow和BlendMode属性，建议使用EGL/OpenGLES提供的接口设置相关内容。

  说明：

  从API version 11开始，type为SURFACE("surface")时支持背景颜色设置。

• type为COMPONENT("component")时仅支持图像效果中的shadow属性，建议使用挂载子组件的方式进行设置相关内容。

• type为TEXTURE时通用属性可以支持背景颜色设置、透明度设置和图像效果中的shadow和BlendMode属性，除颜色外的背景设置和其他图像效果暂不支持，建议使用EGL/OpenGLES提供的接口设置相关内容。

enableAnalyzer¹²⁺

enableAnalyzer(enable: boolean)

设置组件支持AI分析，需要搭配XComponentController的StartImageAnalyzer和StopImageAnalyzer一起使用。 不能和overlay属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

说明：

仅type为SURFACE和TEXTURE时该功能有效。

事件

从API version 12开始，type为SURFACE("surface")或TEXTURE时，满足以下条件时支持通用事件：

• 点击事件、触摸事件、挂载卸载事件、按键事件、焦点事件、鼠标事件与NDK对应接口互斥，未配置libraryname时生效。

• 其他通用事件无对应NDK接口，无论是否配置libraryname都能生效。

仅type为SURFACE("surface")或TEXTURE时以下事件有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

onLoad

onLoad(callback: (event?: object) => void )

插件加载完成时回调事件。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

onDestroy

onDestroy(event: () => void )

插件卸载完成时回调事件。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

XComponentController

xcomponent 组件的控制器，可以将此对象绑定至XComponent组件，然后通过控制器来调用组件方法。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

创建对象

xcomponentController: XComponentController = new XComponentController()

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

getXComponentSurfaceId

getXComponentSurfaceId(): string

获取XComponent对应Surface的ID，供@ohos接口使用，使用方式可参考相机管理，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

返回值:

setXComponentSurfaceSize^(deprecated)

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

设置XComponent持有Surface的宽度和高度，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

该接口从API Version 12开始废弃，建议使用setXComponentSurfaceRect替代。

参数:

getXComponentContext

getXComponentContext(): Object

获取XComponent实例对象的context，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

返回值:

setXComponentSurfaceRect¹²⁺

setXComponentSurfaceRect(rect: SurfaceRect): void

设置XComponent持有Surface的显示区域，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

说明：

rect参数中的offsetX/offsetY不设置时，Surface显示区域相对于XComponent左上角x/y轴的偏移效果默认按照居中显示。

rect参数中的surfaceWidth和surfaceHeight存在0或负数时，调用该接口设置显示区域不生效。

该方法优先级高于border、padding等可以改变内容偏移和大小的属性。

getXComponentSurfaceRect¹²⁺

getXComponentSurfaceRect(): SurfaceRect

获取XComponent持有Surface的显示区域，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

返回值:

onSurfaceCreated¹²⁺

onSurfaceCreated(surfaceId: string): void

当XComponent持有的Surface创建后进行该回调，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

说明：

仅当XComponent组件未设置libraryname参数时，会进行该回调。

onSurfaceChanged¹²⁺

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

当XComponent持有的Surface大小改变后（包括首次创建时的大小改变）进行该回调，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

说明：

仅当XComponent组件未设置libraryname参数时，会进行该回调。

onSurfaceDestroyed¹²⁺

onSurfaceDestroyed(surfaceId: string): void

当XComponent持有的Surface销毁后进行该回调，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

说明：

仅当XComponent组件未设置libraryname参数时，会进行该回调。

SurfaceRect¹²⁺类型说明

用于描述XComponent持有Surface的显示区域。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

startImageAnalyzer¹²⁺

startImageAnalyzer(config: ImageAnalyzerConfig): Promise<void>

配置AI分析并启动AI分析功能，使用前需先使能图像AI分析能力。
该方法调用时，将截取调用时刻的画面帧进行分析，使用时需注意启动分析的时机，避免出现画面和分析内容不一致的情况。
若该方法尚未执行完毕，此时重复调用，则会触发错误回调。

说明：

分析类型不支持动态修改。 该特性依赖设备能力，不支持该能力的情况下，将返回错误码。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

返回值：

错误码：

以下错误码的详细介绍请参见AI分析类库错误码。

stopImageAnalyzer¹²⁺

stopImageAnalyzer(): void

停止AI分析功能，AI分析展示的内容将被销毁。

说明：

在startImageAnalyzer方法未返回结果时调用本方法，会触发其错误回调。 该特性依赖设备能力。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

setXComponentSurfaceRotation¹²⁺

setXComponentSurfaceRotation(rotationOptions: SurfaceRotationOptions): void

设置XComponent持有Surface在屏幕旋转时是否锁定方向，仅XComponent类型为SURFACE("surface")时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数:

说明：

rotationOptions未配置时，默认XComponent持有Surface在屏幕旋转时不锁定方向，跟随屏幕进行旋转。

仅在屏幕旋转过程中生效，旋转完成后不再锁定Surface。

仅在屏幕旋转90°，即发生横竖屏切换时生效。

getXComponentSurfaceRotation¹²⁺

getXComponentSurfaceRotation(): Required<SurfaceRotationOptions>

获取XComponent持有Surface在屏幕旋转时是否锁定方向的设置，仅XComponent类型为SURFACE("surface")时有效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

返回值:

SurfaceRotationOptions¹²⁺类型说明

用于描述XComponent持有Surface在屏幕旋转时是否锁定方向的设置。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

示例

示例效果请以真机运行为准，当前IDE预览器不支持。

示例1

// xxx.ets
@Entry
@Component
struct PreviewArea {
  private surfaceId: string = ''
  private xComponentContext: Record<string, () => void> = {}
  xComponentController: XComponentController = new XComponentController()
  @State rect: SurfaceRect | null = null

  build() {
    Column() {
      Text(JSON.stringify(this.rect))
        .fontSize(12)
      XComponent({
        id: 'xcomponent',
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
        .onLoad(() => {
          this.surfaceId = this.xComponentController.getXComponentSurfaceId()
          this.xComponentContext = this.xComponentController.getXComponentContext() as Record<string, () => void>
          let surfaceRect: SurfaceRect = { offsetX: 20, offsetY: 20, surfaceWidth: 500, surfaceHeight: 500 }
          this.xComponentController.setXComponentSurfaceRect(surfaceRect)
          this.rect = this.xComponentController.getXComponentSurfaceRect()
        })
        .width('640px')
        .height('480px')
    }
    .position({ x: 0, y: 48 })
  }
}

示例2

// xxx.ets
class CustomXComponentController extends XComponentController {
  onSurfaceCreated(surfaceId: string): void {
    console.log(`onSurfaceCreated surfaceId: ${surfaceId}`)
  }

  onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
    console.log(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}}`)
  }

  onSurfaceDestroyed(surfaceId: string): void {
    console.log(`onSurfaceDestroyed surfaceId: ${surfaceId}`)
  }
}

@Entry
@Component
struct SurfaceCallbackDemo {
  xComponentController: XComponentController = new CustomXComponentController()
  @State xcWidth: string = "320px"
  @State xcHeight: string = "480px"

  build() {
    Column() {
      Button("change size")
        .onClick(() => {
          this.xcWidth = "640px"
          this.xcHeight = "960px"
        })
      XComponent({
        id: 'xcomponent',
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
        .width(this.xcWidth)
        .height(this.xcHeight)
    }
    .width("100%")
  }
}

示例3

图像分析功能使用示例。

// xxx.ets
import { BusinessError } from '@ohos.base';

@Entry
@Component
struct ImageAnalyzerExample {
  xComponentController: XComponentController = new XComponentController()
  private config: ImageAnalyzerConfig = {
    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
  }
  private aiController: ImageAnalyzerController = new ImageAnalyzerController()
  private options: ImageAIOptions = {
    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
    aiController: this.aiController
  }

  build() {
    Column() {
      Button('start')
        .width(80)
        .height(80)
        .onClick(() => {
          this.xComponentController.startImageAnalyzer(this.config)
            .then(() => {
              console.log("analysis complete")
            })
            .catch((error: BusinessError) => {
              console.log("error code: " + error.code)
            })
        })
      Button('stop')
        .width(80)
        .height(80)
        .onClick(() => {
          this.xComponentController.stopImageAnalyzer()
        })
      Button('getTypes')
        .width(80)
        .height(80)
        .onClick(() => {
          this.aiController.getImageAnalyzerSupportTypes()
        })
      XComponent({
        id: 'xcomponent',
        type: XComponentType.SURFACE,
        imageAIOptions: this.options,
        controller: this.xComponentController
      })
        .enableAnalyzer(true)
        .width('640px')
        .height('480px')
    }
    .width("100%")
  }
}