鸿蒙5.0开发进阶：UI框架-ArkTS组件（XComponent）

最新推荐文章于 2025-04-19 19:37:24 发布
最新推荐文章于 2025-04-19 19:37:24 发布
阅读量773 收藏 29
点赞数 29
分类专栏： 鸿蒙开发 ArkTS ArkUI 文章标签： harmonyos 华为 android 前端 ArkUI ArkTS 鸿蒙系统
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/Androidbye/article/details/145493895
版权

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

XComponent

提供用于图形绘制和媒体数据写入的Surface，XComponent负责将其嵌入到视图中，支持应用自定义Surface位置和大小。

说明

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

子组件

无

接口

XComponent12+

XComponent(options: XComponentOptions)

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

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

参数:

参数名类型必填说明
optionsXComponentOptions是定义XComponent的具体配置参数。

XComponent10+

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

该接口从API version 12开始不再演进，推荐使用XComponent(options: XComponentOptions)。

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

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

参数:

参数名类型必填说明
idstring是组件的唯一标识，支持最大的字符串长度128。
typeXComponentType是用于指定XComponent组件类型。
librarynamestring否用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅类型为SURFACE或TEXTURE时有效。
controllerXComponentController否给组件绑定一个控制器，通过控制器调用组件方法，仅类型为SURFACE或TEXTURE时有效。

XComponent(deprecated)

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

说明：

从API version 12开始废弃，建议使用XComponent(options: XComponentOptions)替代。

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

参数:

参数名类型必填说明
idstring是组件的唯一标识，支持最大的字符串长度128。
typestring是

用于指定XComponent组件类型，可选值仅有两个为：

-"surface"：用于EGL/OpenGLES和媒体数据写入，开发者定制的绘制内容单独展示到屏幕上。

-"component"9+ ：XComponent将变成一个容器组件，并可在其中执行非UI逻辑以动态加载显示内容。

其他值均会被视为"surface"类型

librarynamestring否应用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅XComponent类型为"surface"时有效。
controllerXComponentcontroller否给组件绑定一个控制器，通过控制器调用组件方法，仅XComponent类型为"surface"时有效。

XComponentOptions12+

定义XComponent的具体配置参数。

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

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

名称类型必填说明
typeXComponentType是用于指定XComponent组件类型。
controllerXComponentController是给组件绑定一个控制器，通过控制器调用组件方法，仅类型为SURFACE或TEXTURE时有效。
imageAIOptionsImageAIOptions否给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。

属性

除支持通用属性外，还支持以下属性：

说明

不支持foregroundColor、obscured和pixelStretchEffect属性，并且type为SURFACE类型时也不支持动态属性设置、自定义绘制、背景设置(backgroundColor除外)、图像效果(shadow除外)、maskShape和foregroundEffect属性。

对于TEXTURE和SURFACE类型的XComponent，当不设置renderFit属性时，取默认值为RenderFit.RESIZE_FILL。

enableAnalyzer12+

enableAnalyzer(enable: boolean)

设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能。

本功能需要搭配XComponentController的StartImageAnalyzer和StopImageAnalyzer一起使用。

不能和overlay属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。

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

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

参数：

参数名类型必填说明
enableboolean是是否启用图像分析功能

说明

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

事件

从API version 12开始，type为SURFACE或TEXTURE时，支持通用事件。

说明

当配置libraryname参数时，点击事件、触摸事件、挂载卸载事件、按键事件、焦点事件、鼠标事件仅响应C-API侧事件接口。

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

仅type为SURFACE或TEXTURE时以下事件有效：

onLoad

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

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

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

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

参数:

参数名类型必填说明
eventobject否获取XComponent实例对象的context，context上挂载的方法由开发者在c++层定义。

onDestroy

onDestroy(event: () => void )

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

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

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

XComponentController

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

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

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

创建对象

xcomponentController: XComponentController = new XComponentController()

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

constructor

constructor()

XComponentController的构造函数。

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

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

getXComponentSurfaceId9+

getXComponentSurfaceId(): string

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

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

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

返回值:

类型描述
stringXComponent持有Surface的ID。

setXComponentSurfaceSize(deprecated)

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

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

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

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

参数:

参数名类型必填说明
surfaceWidthnumber是XComponent持有Surface的宽度。
surfaceHeightnumber是XComponent持有Surface的高度。

getXComponentContext

getXComponentContext(): Object

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

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

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

返回值:

类型描述
Object获取XComponent实例对象的context，context包含的具体接口方法由开发者自定义，context内容与onLoad回调中的第一个参数一致。

setXComponentSurfaceRect12+

setXComponentSurfaceRect(rect: SurfaceRect): void

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

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

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

参数:

参数名类型必填说明
rectSurfaceRect是XComponent持有Surface的显示区域。

说明

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

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

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

getXComponentSurfaceRect12+

getXComponentSurfaceRect(): SurfaceRect

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

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

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

返回值:

类型描述
SurfaceRect获取XComponent持有Surface的显示区域。

onSurfaceCreated12+

onSurfaceCreated(surfaceId: string): void

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

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

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

参数:

参数名类型必填说明
surfaceIdstring是回调该方法的时候，绑定XComponent持有Surface的ID。

说明

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

onSurfaceChanged12+

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

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

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

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

参数:

参数名类型必填说明
surfaceIdstring是回调该方法的时候，绑定XComponent持有Surface的ID。
rectSurfaceRect是回调该方法的时候，绑定XComponent持有Surface的显示区域。

说明

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

onSurfaceDestroyed12+

onSurfaceDestroyed(surfaceId: string): void

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

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

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

参数:

参数名类型必填说明
surfaceIdstring是回调该方法的时候，绑定XComponent持有Surface的ID。

说明

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

startImageAnalyzer12+

startImageAnalyzer(config: ImageAnalyzerConfig): Promise<void>

配置AI分析并启动AI分析功能，使用前需先使能图像AI分析能力。

该方法调用时，将截取调用时刻的画面帧进行分析，使用时需注意启动分析的时机，避免出现画面和分析内容不一致的情况。

若该方法尚未执行完毕，此时重复调用，则会触发错误回调。

说明

分析类型不支持动态修改。

该特性依赖设备能力，不支持该能力的情况下，将返回错误码。

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

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

参数：

参数名类型必填说明
configImageAnalyzerConfig是执行AI分析所需要的入参，用于配置AI分析功能。

返回值：

类型说明
Promise<void>Promise对象，用于获取AI分析是否成功执行。

错误码：

以下错误码的详细介绍。

错误码ID错误信息
110001Image analysis feature is unsupported.
110002Image analysis is currently being executed.
110003Image analysis is stopped.

stopImageAnalyzer12+

stopImageAnalyzer(): void

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

说明

在startImageAnalyzer方法未返回结果时调用本方法，会触发其错误回调。

该特性依赖设备能力。

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

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

setXComponentSurfaceRotation12+

setXComponentSurfaceRotation(rotationOptions: SurfaceRotationOptions): void

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

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

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

参数:

参数名类型必填说明
rotationOptionsSurfaceRotationOptions是设置XComponent持有Surface在屏幕旋转时是否锁定方向。

说明

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

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

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

锁定旋转后的Buffer宽高需要保持不变，否则会有拉伸问题。

getXComponentSurfaceRotation12+

getXComponentSurfaceRotation(): Required<SurfaceRotationOptions>

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

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

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

返回值:

类型描述
SurfaceRotationOptions获取XComponent持有Surface在屏幕旋转时是否锁定方向的设置。

SurfaceRotationOptions12+对象说明

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

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

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

名称类型必填说明
lockboolean否Surface在屏幕旋转时是否锁定方向，未设置时默认取值为false，即不锁定方向。

SurfaceRect12+对象说明

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

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

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

名称类型必填说明
offsetXnumber否Surface显示区域相对于XComponent组件左上角的x轴坐标，单位：px。
offsetYnumber否Surface显示区域相对于XComponent组件左上角的y轴坐标，单位：px。
surfaceWidthnumber是Surface显示区域的宽度，单位：px。
surfaceHeightnumber是Surface显示区域的高度，单位：px。

说明

surfaceWidth和surfaceHeight属性在未调用setXComponentSurfaceRect也未设置border和padding等属性时，其取值大小为XComponent组件的大小。

surfaceWidth和surfaceHeight属性的取值都不可超过8192px，否则会导致渲染异常。

示例

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

示例1（图像AI分析功能）

使用enableAnalyzer属性开启图像AI分析功能。可通过XComponentController控制开始、停止图形AI分析。

// 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%")
  }
}

示例2（在surface旋转过程中锁定）

通过setXComponentSurfaceRotation设置surface在屏幕旋转过程中锁定方向，不跟随屏幕进行旋转。

// 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%')
  }
}

鸿蒙组件学习之XComponent
坚果的博客
09-02 980
可用于EGL/OpenGLES和媒体数据写入，并显示在XComponent组件。
OpenHarmony/HarmonyOS基础组件之XComponent
热门推荐
坚果的博客
03-30 1万+
可用于EGL/OpenGLES和媒体数据写入，并显示在XComponent组件。
鸿蒙5.0开发进阶：UI开发常用组件-自定义渲染 (XComponent)
Androidbye的博客
09-08 2307
XComponent组件作为一种渲染组件，通常用于满足开发者较为复杂的自定义渲染需求
鸿蒙开发 自定义渲染 (XComponent)
最新发布
ButcherCS的博客
04-19 693
XComponent组件作为一种渲染组件，可用于EGL/OpenGLES和媒体数据写入，通过使用XComponent独有的“ NativeWindow ”来渲染画面，通常用于满足开发者较为复杂的自定义渲染需求，例如相机预览流的显示和游戏画面的渲染。其可通过指定type字段来实现不同的渲染方式，分别为 XComponentType .SURFACE和XComponentType.TEXTURE。对于SURFACE类型，开发者将定制的绘制内容单独展示到屏幕上。
OpenHarmony实战开发-如何实现自定义绘制 (XComponent)
m0_70749039的博客
04-27 2290
XComponent组件作为一种绘制组件，通常用于满足开发者较为复杂的自定义绘制需求，例如相机预览流的显示和游戏画面的绘制。
鸿蒙（HarmonyOS）项目方舟框架（ArkUI）之XComponent组件
zy0412326的专栏
02-10 2877
鸿蒙（HarmonyOS）项目方舟框架（ArkUI）之XComponent组件。
鸿蒙Harmony应用开发—ArkTS声明式开发（基础手势：XComponent）
m0_64420071的博客
03-14 1779
ArkTS声明式开发（基础手势：XComponent）
鸿蒙ArkTS实战开发-Native XComponent组件的使用
2401_82546228的博客
03-22 2102
本篇Codelab主要介绍如何使用XComponent组件调用NAPI来创建EGL/GLES环境，实现在主页面绘制一个正方形，并可以改变正方形的颜色。本篇CodeLab使用Native C++模板创建。
鸿蒙5.0开发进阶：UI框架-ArkTS组件（Scroll）
Androidbye的博客
01-06 737
可滚动的容器组件，当子组件的布局尺寸超过父组件的尺寸时，内容可以滚动。
鸿蒙5.0开发进阶：UI框架-ArkTS组件（Grid）
Androidbye的博客
01-06 993
网格容器，由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。
鸿蒙5.0开发进阶：UI框架-ArkTS组件（Video）
Androidbye的博客
01-16 992
用于播放视频文件并控制其播放状态的组件。
鸿蒙5.0开发进阶：UI框架-ArkTS组件（Line）
Androidbye的博客
02-06 883
直线绘制组件。
鸿蒙5.0开发进阶：UI框架-ArkTS组件（Swiper）
Androidbye的博客
01-07 679
滑块视图容器，提供子组件滑动轮播显示的能力。
【鸿蒙实战开发】C-API版本XComponent接入
HarmonyOSMN的博客
07-08 1382
C-API 版本使用XComponent总共分成了两个步骤：createSurface的时候创建XComponentSurface;startSurface的时候将CPP的XComponentSurface连接到ArkUI的Xcomponent上。
HarmonyOS核心知识点：自定义绘制 (XComponent)
wuliusan5的博客
03-20 1026
开发者在ArkTS侧使用如下代码，即可用XComponent组件进行利用EGL/OpenGLES渲染的开发。id : 与XComponent组件为一一对应关系，不建议重复。通常开发者可以在native侧通过OH_NativeXComponent_GetXComponentId接口来获取对应的id从而绑定对应的XComponent。说明如果id重复，在native侧将无法对多个XComponent进行区分。
C-API版本XComponent接入
hongxiaomeng的博客
06-21 166
【鸿蒙开发】—— 添加组件（Native XComponent)
2401_88547687的博客
11-06 685
Native XComponent是XComponent组件提供在Native层的实例，可作为JS层和Native层XComponent绑定的桥梁。XComponent所提供的NDK接口都依赖于该实例。接口能力包括获取Native Window实例、获取XComponent的布局/事件信息、注册XComponent的生命周期回调、注册XComponent的触摸、鼠标、按键等事件回调。利用Native XComponent提供的接口注册XComponent的生命周期和事件回调。
鸿蒙OpenHarmony【XComponent】渲染绘制
asfn123123的博客
11-18 1352
提供用于图形绘制和媒体数据写入的Surface，XComponent负责将其嵌入到视图中，支持应用自定义Surface位置和大小。
鸿蒙NEXT版实战开发：使用XComponent实现画中画功能开发
qq_39652397的博客
09-30 751
本文以视频播放为例，介绍通过XComponent实现画中画功能的基本开发步骤。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值