输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
管理中心
我的
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API

您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。

指南与API参考API参考应用框架ArkUI（方舟UI框架）ArkTS组件渲染绘制XComponent

XComponent

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
更新时间: 2026-09-09 06:54
复制页面
本文导读
子组件
接口
XComponent19+
XComponent12+
XComponent10+
XComponent(deprecated)
XComponentOptions12+
NativeXComponentParameters19+
属性
enableAnalyzer12+
enableSecure13+
hdrBrightness20+
hdrBrightness24+
HdrType枚举说明24+
事件
onLoad
onDestroy
OnNativeLoadCallback18+
XComponentController
constructor
getXComponentSurfaceId9+
setXComponentSurfaceSize(deprecated)
getXComponentContext
setXComponentSurfaceRect12+
getXComponentSurfaceRect12+
onSurfaceCreated12+
onSurfaceChanged12+
onSurfaceDestroyed12+
startImageAnalyzer12+
stopImageAnalyzer12+
setXComponentSurfaceRotation12+
getXComponentSurfaceRotation12+
lockCanvas20+
unlockCanvasAndPost20+
setXComponentSurfaceConfig22+
SurfaceRotationOptions对象说明12+
SurfaceRect对象说明12+
SurfaceConfig对象说明22+
示例
示例1（图像AI分析功能）
示例2（在Surface旋转过程中锁定）
示例3（使用画布对象在XComponent上绘制内容）
示例4（XComponent实现沉浸式效果）
示例5（设置XComponent持有Surface在渲染时是否需要被视为不透明）
展开章节

提供用于图形绘制和媒体数据写入的Surface，XComponent负责将其嵌入到视图中，支持应用自定义Surface位置和大小。同时支持AI图像分析、HDR视频亮度调节、防截屏录屏隐私保护、画布自绘制等能力，适用于视频播放、相机预览、游戏渲染、图像AI识别等需要高性能自绘制和媒体内容展示的场景。具体指南请参考自定义渲染（XComponent）文档。

说明

该组件从API version 8 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

子组件

无

接口

XComponent19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

XComponent(params: NativeXComponentParameters)

在Native侧获取XComponent节点实例、注册XComponent持有的Surface的生命周期回调和触摸、鼠标、按键等组件事件回调。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
params NativeXComponentParameters 是 XComponent的配置参数，用于在Native侧获取XComponent节点实例并注册Surface生命周期回调和组件事件回调。

XComponent12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

XComponent(options: XComponentOptions)

创建XComponent组件，支持在ArkTS侧获取SurfaceId、注册XComponent持有的Surface的生命周期回调和触摸、鼠标、按键等组件事件回调，支持AI分析。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
options XComponentOptions 是 XComponent的配置选项，用于在ArkTS侧获取SurfaceId、注册Surface生命周期回调和组件事件回调，以及配置AI分析功能。

XComponent10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

创建XComponent组件，支持Native侧触发XComponent生命周期回调。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
id string 是 组件的唯一标识，字符串长度不超过128个字符，超出时无效。
type XComponentType 是 用于指定XComponent组件类型。
libraryname string 否 应用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅类型为SURFACE或TEXTURE时有效。未设置时不加载动态库。
controller XComponentController 否 给组件绑定一个控制器，通过控制器调用组件方法（如获取SurfaceId、设置Surface显示区域等），仅类型为SURFACE或TEXTURE时有效。当需要在ArkTS侧控制XComponent行为时传入此参数；不传入时，无法通过控制器调用相关组件方法。

XComponent(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

说明

从 API version 8开始支持，从API version 12开始废弃。建议使用XComponent(value: {id: string, type: XComponentType, libraryname?: string, controller?: XComponentController})替代。

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

参数：

展开
参数名 类型 必填 说明
id string 是 组件的唯一标识，字符串长度不超过128个字符，超出时无效。
type string 是

用于指定XComponent组件类型，可选值仅有以下两种：

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

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

其他值均会被视为"surface"类型
libraryname string 否 应用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅XComponent类型为"surface"时有效。未设置时不加载动态库。
controller XComponentController 否 给组件绑定一个控制器，通过控制器调用组件方法，仅XComponent类型为"surface"时有效。未设置时不绑定控制器。

XComponentOptions12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

定义XComponent的具体配置参数。

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
type XComponentType 否 否 用于指定XComponent组件类型。
controller XComponentController 否 否 给组件绑定一个控制器，通过控制器调用组件方法，仅类型为SURFACE或TEXTURE时有效。未设置时不绑定控制器。
imageAIOptions ImageAIOptions 否 是 给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器，仅类型为SURFACE或TEXTURE时有效。未设置时不配置AI分析选项，可通过enableAnalyzer属性单独启用AI分析。

NativeXComponentParameters19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

定义XComponent的具体配置参数。通过这种构造参数创建的XComponent，可以将其对应的FrameNode对象传递至Native侧，使用NDK接口进行Surface生命周期的相关设置和添加事件监听。

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
type XComponentType 否 否 用于指定XComponent组件类型。
imageAIOptions ImageAIOptions 否 是 给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器，仅类型为SURFACE或TEXTURE时有效。未设置时不配置AI分析选项，可通过enableAnalyzer属性单独启用AI分析。

属性

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

说明

不支持foregroundColor、obscured和pixelStretchEffect属性。API version 17及之前，type为SURFACE类型时也不支持动态属性设置、自定义绘制、背景设置（backgroundColor除外）、图像效果（shadow除外）、maskShape和foregroundEffect属性。从API version 18开始，type为SURFACE类型时，不支持的动态属性包含：background、foregroundColor、animation、gesture、priorityGesture、parallelGesture、useEffect、renderGroup、flexGrow、direction、align、useSizeType、clip、geometryTransition、bindPopup、bindMenu、bindContextMenu、bindContentCover、bindSheet、stateStyles、restoreId、onVisibleAreaChange、accessibilityGroup、obscured、reuseId、accessibilityVirtualNode。

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

对于SURFACE类型的XComponent组件，其背景色默认为不透明的纯黑色。在API version 18之前，该组件的renderFit通用属性仅支持设置为RenderFit.RESIZE_FILL；在API version 18及之后，支持所有的RenderFit枚举值。

对于使用ArkUI NDK接口创建的XComponent组件，不支持使用属性获取函数getAttribute获取其renderFit属性值。

enableAnalyzer12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

enableAnalyzer(enable: boolean)

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

本功能需要搭配XComponentController的startImageAnalyzer和stopImageAnalyzer一起使用。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enable boolean 是

是否启用AI分析功能。

true：开启AI分析；false：关闭AI分析。

默认值：false
说明

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

enableSecure13+

Phone13+PC/2in113+Tablet13+TV19+Wearable18+

enableSecure(isSecure: boolean)

防止组件内自绘制内容被截屏、录屏。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
isSecure boolean 是

是否开启隐私图层模式。

true：开启隐私图层模式；false：关闭隐私图层模式。

默认值：false
说明

仅type为SURFACE时有效。

不支持ArkUI NDK接口创建的XComponent组件。

hdrBrightness20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

hdrBrightness(brightness: number)

用于调整组件播放HDR视频的亮度。

说明

  • 仅XComponent构造参数中的type为XComponentType.SURFACE时该接口生效，否则该接口不生效。

  • 不支持ArkUI NDK接口创建的XComponent组件。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
brightness number 是

HDR视频的亮度。

默认值：1.0

取值范围：[0.0, 1.0]。小于0.0的值按0.0处理，大于1.0的值按1.0处理，其他异常值按1.0处理。

0.0表示视频按照SDR亮度显示，1.0表示视频按照当前允许的最高HDR亮度显示。

hdrBrightness24+

Phone24+PC/2in124+Tablet24+TV24+Wearable24+

hdrBrightness(brightness: number, type?: HdrType)

用于调整组件显示HDR内容时的亮度。

当参数type设置为非HdrType.DEFAULT时，调用该接口前需先检查Display的hdrFormats属性是否包含对应的HDRFormat。

仅当hdrFormats包含对应的HDRFormat时，当前设备才支持对应的HDR类型，参数设置才会生效；否则将使用默认值HdrType.DEFAULT。

其映射关系如下：

展开
type取值 hdrFormats需包含的HDRFormat
HdrType.AIHDR HDRFormat.VIDEO_AIHDR
说明

  • 仅XComponent构造参数中的type为XComponentType.SURFACE时该接口生效，否则该接口不生效。

  • 不支持ArkUI NDK接口创建的XComponent组件。

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

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

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
brightness number 是

HDR内容的亮度。

默认值：1.0

取值范围：[0.0, 1.0]。小于0.0的值按0.0处理，大于1.0的值按1.0处理，其他异常值按1.0处理。

0.0表示内容按照SDR亮度显示，1.0表示内容按照当前允许的最高HDR亮度显示。
type HdrType 否

显示HDR内容时的HDR类型。

默认值：HdrType.DEFAULT

HdrType24+枚举说明

Phone24+PC/2in124+Tablet24+TV24+Wearable24+

HDR内容的高动态范围渲染类型。

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

模型约束： 此接口仅可在Stage模型下使用。

展开
名称 值 说明
DEFAULT 0

默认HDR类型，使用标准高动态范围渲染模式。

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

AI HDR类型，使用AI算法对非HDR内容进行智能动态范围扩展，实现HDR的显示效果。

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

事件

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

说明

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

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

onLoad

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onLoad(callback: OnNativeLoadCallback)

Native加载完成时回调事件。

说明

仅当XComponent设置了libraryname参数时，会触发该回调；当未设置libraryname参数时，请使用onSurfaceCreated等相关回调。

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

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

参数：

展开
参数名 类型 必填 说明
callback OnNativeLoadCallback 是 Native加载完成时回调事件，用于获取XComponent实例对象的context。

onDestroy

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onDestroy(event: VoidCallback)

Native卸载完成时回调事件。与onSurfaceDestroyed的区别：onDestroy适用于设置libraryname参数的场景，回调无参数；onSurfaceDestroyed适用于未设置libraryname参数的场景，回调参数为surfaceId。

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

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

参数：

展开
参数名 类型 必填 说明
event VoidCallback 是 Native卸载完成时回调事件。

OnNativeLoadCallback18+

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

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

XComponent的Native加载完成后回调事件，用于向开发者传递XComponent实例对象的context。与onSurfaceCreated的区别：onLoad回调参数为context对象，适用于设置libraryname参数的场景；onSurfaceCreated回调参数为surfaceId，适用于未设置libraryname参数的场景。onLoad触发时机早于onSurfaceCreated。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
event object 否 获取XComponent实例对象的context，context上挂载的方法由开发者在Native层定义。不传该参数时无法获取context。当需要在回调中使用Native层定义的方法时传入此参数；不传入时，回调中无法获取context对象。

XComponentController

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

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

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

constructor

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

constructor()

XComponentController的构造函数。

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

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

示例：

收起
自动换行
深色代码主题
复制
  1. xComponentController: XComponentController = new XComponentController();

getXComponentSurfaceId9+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

getXComponentSurfaceId(): string

获取XComponent对应Surface的ID，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

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

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

返回值：

展开
类型 说明
string XComponent持有Surface的ID。
说明

使用自定义组件节点创建XComponent组件时，因为onLoad回调触发时机早于onSurfaceCreated，所以在onLoad回调中调用getXComponentSurfaceId获取surfaceId会失败，建议在onSurfaceCreated回调中获取。

示例：

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. 

  3. @Entry
  4.   @Component
  5.   struct Index {
  6.     myXComponentController: XComponentController = new XComponentController();
  7. 

  8.     build() {
  9.       Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
  10.         XComponent({
  11.           type: XComponentType.SURFACE,
  12.           controller: this.myXComponentController
  13.         })
  14.           .onLoad(() => {
  15.             let surfaceId: string = this.myXComponentController.getXComponentSurfaceId();
  16.             console.info("XComponent SurfaceId: " + surfaceId);
  17.           })
  18.       }
  19.     }
  20.   }

setXComponentSurfaceSize(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

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

说明

从 API version 9开始支持，从API version 12开始废弃。建议使用setXComponentSurfaceRect替代。

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

参数：

展开
参数名 类型 必填 说明
surfaceWidth number 是 XComponent持有Surface的宽度，取值范围为大于0且不超过8192，单位：px。传入0、负数或其他异常值时接口不生效。
surfaceHeight number 是 XComponent持有Surface的高度，取值范围为大于0且不超过8192，单位：px。传入0、负数或其他异常值时接口不生效。

getXComponentContext

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

getXComponentContext(): Object

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

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

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

返回值：

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

setXComponentSurfaceRect12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

setXComponentSurfaceRect(rect: SurfaceRect): void

设置XComponent持有Surface的显示区域，包括宽高和相对于组件左上角的位置坐标，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

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

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

rect参数中的surfaceWidth和surfaceHeight存在0、负数或其他异常值时，调用该接口设置显示区域不生效。未调用该接口主动设置Surface显示区域时，surfaceWidth默认与组件宽度一致，surfaceHeight默认与组件高度一致。

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

getXComponentSurfaceRect12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

getXComponentSurfaceRect(): SurfaceRect

获取XComponent持有Surface的显示区域，包括宽高和相对于组件左上角的位置坐标，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

返回值：

展开
类型 说明
SurfaceRect 获取XComponent持有Surface的显示区域。

onSurfaceCreated12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onSurfaceCreated(surfaceId: string): void

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

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

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

onSurfaceChanged12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
surfaceId string 是 回调该方法的时候，绑定XComponent持有Surface的ID。
rect SurfaceRect 是 回调该方法的时候，绑定XComponent持有Surface的显示区域。
说明

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

onSurfaceDestroyed12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onSurfaceDestroyed(surfaceId: string): void

当XComponent持有的Surface销毁后进行该回调，仅XComponent类型为SURFACE("surface")或TEXTURE时有效，具体可以参考指南创建XComponent和管理Surface生命周期章节。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

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

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

startImageAnalyzer12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

startImageAnalyzer(config: ImageAnalyzerConfig): Promise<void>

配置AI分析并启动AI分析功能，使用前需先启用图像AI分析能力enableAnalyzer，仅XComponent类型为SURFACE或TEXTURE时有效。使用Promise异步回调。

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

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

说明

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

AI分析功能依赖设备能力，不支持该能力的情况下，将返回错误码。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

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

返回值：

展开
类型 说明
Promise<void> Promise对象，无返回结果。用于获取AI分析是否成功执行。

错误码：

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

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

stopImageAnalyzer12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

stopImageAnalyzer(): void

停止AI分析功能，仅XComponent类型为SURFACE或TEXTURE时有效，须先调用enableAnalyzer和startImageAnalyzer启用AI分析能力。调用后AI分析展示的内容将被销毁。

说明

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

该特性依赖设备能力。

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

模型约束： 此接口仅可在Stage模型下使用。

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

setXComponentSurfaceRotation12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

setXComponentSurfaceRotation(rotationOptions: SurfaceRotationOptions): void

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

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

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

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

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

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

getXComponentSurfaceRotation12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

getXComponentSurfaceRotation(): Required<SurfaceRotationOptions>

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

返回值：

展开
类型 说明
Required<SurfaceRotationOptions> 获取XComponent持有Surface在屏幕旋转时是否锁定方向的设置。

lockCanvas20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

lockCanvas(): DrawingCanvas | null

返回可用于向XComponent上绘制内容的画布对象。具体绘制方法请参考Canvas。

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

模型约束： 此接口仅可在Stage模型下使用。

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

返回值：

展开
类型 说明
DrawingCanvas | null 可用于向XComponent区域绘制的画布对象；当无法获取画布对象时（如Surface未创建完成或画布已被占用未释放）返回null。
说明

如果当前XComponent状态无法获取画布对象则将返回null。原因通常为：

  1. XComponent持有的Surface未创建完成（可通过设置onLoad/onSurfaceCreated回调来确定，此回调触发时，Surface已创建完成）。

  2. 之前已经调用过lockCanvas来获取过画布对象，且该画布对象未调用unlockCanvasAndPost去释放。

只支持TEXTURE和SURFACE模式。

使用此接口后，同时在NDK侧获取NativeWindow并调用NDK绘制接口进行绘制，可能出现缓冲区竞争和上下文冲突而发生绘制画面错误等异常，因此不允许使用。

此接口需要和unlockCanvasAndPost接口配对使用，具体参考示例3使用画布对象在XComponent上绘制内容。

unlockCanvasAndPost20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

unlockCanvasAndPost(canvas: DrawingCanvas): void

将画布对象中的内容绘制在XComponent区域，并释放该画布对象。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
canvas DrawingCanvas 是 之前调用lockCanvas方法返回的画布对象。
说明

  1. 画布对象调用unlockCanvasAndPost释放后，不可再使用该画布对象。

  2. 只支持TEXTURE和SURFACE模式。

  3. 使用此接口后，同时在NDK侧获取NativeWindow并调用相关接口进行绘制，可能出现缓冲区竞争和上下文冲突而发生绘制画面错误等异常，因此不允许使用。

  4. 此接口需要和lockCanvas接口配对使用，具体参考示例3使用画布对象在XComponent上绘制内容。

setXComponentSurfaceConfig22+

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

setXComponentSurfaceConfig(config: SurfaceConfig): void

设置XComponent创建的Surface的选项，用于设置XComponent持有的Surface在渲染时是否需要被视为不透明。当Surface绘制内容完全不透明时，可设置为不透明以提升渲染性能；当绘制内容包含透明区域时，需保持非不透明以保证透明效果正确显示。

说明

仅当XComponent组件类型为TEXTURE或SURFACE时，本接口生效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
config SurfaceConfig 是 Surface配置选项，用于设置XComponent持有的Surface在渲染时是否需要被视为不透明。

SurfaceRotationOptions12+对象说明

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
lock boolean 否 是

Surface在屏幕旋转时是否锁定方向，未设置时默认取值为false，即不锁定方向。

true：锁定方向；false：不锁定方向。

SurfaceRect12+对象说明

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
offsetX number 否 是 Surface显示区域相对于XComponent组件左上角的x轴坐标，单位：px。未设置时默认按照居中显示。
offsetY number 否 是 Surface显示区域相对于XComponent组件左上角的y轴坐标，单位：px。未设置时默认按照居中显示。
surfaceWidth number 否 否 Surface显示区域的宽度，单位：px。
surfaceHeight number 否 否 Surface显示区域的高度，单位：px。
说明

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

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

沉浸式场景下，默认布局的SurfaceRect不包括安全区，需调用setXComponentSurfaceRect接口主动设置Surface显示区域达到沉浸式效果。

SurfaceConfig22+对象说明

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

用于描述XComponent持有的Surface在渲染时是否需要被视为不透明。

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
isOpaque boolean 否 是

XComponent持有的Surface在渲染时是否需要被视为不透明，未设置时默认取值为false，即在渲染时会应用Surface中绘制内容像素的透明度。

true表示需要被视为不透明，false表示不需要被视为不透明。

默认值：false

示例

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

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

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

说明

本示例画图逻辑具体实现（和nativeRender相关的函数实现）可以参考ArkTS XComponent示例

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import nativeRender from 'libnativerender.so'; // 开发者自己实现的so，详见上述说明。
  4. 

  5. class CustomXComponentController extends XComponentController {
  6.   onSurfaceCreated(surfaceId: string): void {
  7.     console.info(`onSurfaceCreated surfaceId: ${surfaceId}`);
  8.     nativeRender.SetSurfaceId(BigInt(surfaceId));
  9.   }
  10. 

  11.   onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
  12.     console.info(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}`);
  13.     nativeRender.ChangeSurface(BigInt(surfaceId), rect.surfaceWidth, rect.surfaceHeight);
  14.   }
  15. 

  16.   onSurfaceDestroyed(surfaceId: string): void {
  17.     console.info(`onSurfaceDestroyed surfaceId: ${surfaceId}`);
  18.     nativeRender.DestroySurface(BigInt(surfaceId));
  19.   }
  20. }
  21. 

  22. @Entry
  23. @Component
  24. struct XComponentExample {
  25.   xComponentController: XComponentController = new CustomXComponentController();
  26.   private config: ImageAnalyzerConfig = {
  27.     types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
  28.   };
  29.   private aiController: ImageAnalyzerController = new ImageAnalyzerController();
  30.   private options: ImageAIOptions = {
  31.     types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
  32.     aiController: this.aiController
  33.   };
  34.   @State xcWidth: string = "720px";
  35.   @State xcHeight: string = "720px";
  36.   @State currentStatus: string = "index";
  37. 

  38.   build() {
  39.     Column({ space: 5 }) {
  40.       Row() {
  41.         Text('Native XComponent Sample')
  42.           .fontSize('24fp')
  43.           .fontWeight(500)
  44.           .margin({
  45.             left: 24,
  46.             top: 12
  47.           })
  48.       }
  49.       .margin({ top: 24 })
  50.       .width('100%')
  51.       .height(56)
  52. 

  53.       XComponent({
  54.         type: XComponentType.SURFACE,
  55.         controller: this.xComponentController,
  56.         imageAIOptions: this.options
  57.       })
  58.         .width(this.xcWidth)
  59.         .height(this.xcHeight)
  60.         .enableAnalyzer(true)
  61.         .onClick(() => {
  62.           let surfaceId = this.xComponentController.getXComponentSurfaceId();
  63.           nativeRender.ChangeColor(BigInt(surfaceId));
  64.           let hasChangeColor: boolean = false;
  65.           let status = nativeRender.GetXComponentStatus(BigInt(surfaceId));
  66.           if (status) {
  67.             hasChangeColor = status.hasChangeColor;
  68.           }
  69.           if (hasChangeColor) {
  70.             this.currentStatus = "change color";
  71.           }
  72.         })
  73.       Text(this.currentStatus)
  74.         .fontSize('24fp')
  75.         .fontWeight(500)
  76.       Column() {
  77.         Button('start AI analyze')
  78.           .onClick(() => {
  79.             this.xComponentController.startImageAnalyzer(this.config)
  80.               .then(() => {
  81.                 console.info("analysis complete");
  82.               })
  83.               .catch((error: BusinessError) => {
  84.                 console.error(`Failed to start image analyzer. Code: ${error.code}, message: ${error.message}`);
  85.               })
  86.           })
  87.           .margin(2)
  88.         Button('stop AI analyze')
  89.           .onClick(() => {
  90.             this.xComponentController.stopImageAnalyzer();
  91.           })
  92.           .margin(2)
  93.         Button('get analyzer types')
  94.           .onClick(() => {
  95.             this.aiController.getImageAnalyzerSupportTypes();
  96.           })
  97.           .margin(2)
  98.         Button('Draw Star')
  99.           .fontSize('16fp')
  100.           .fontWeight(500)
  101.           .onClick(() => {
  102.             let surfaceId = this.xComponentController.getXComponentSurfaceId();
  103.             console.info(`surface rect is ${this.xComponentController.getXComponentSurfaceRect()}`);
  104.             nativeRender.DrawPattern(BigInt(surfaceId));
  105.             let hasDraw: boolean = false;
  106.             let status = nativeRender.GetXComponentStatus(BigInt(surfaceId));
  107.             if (status) {
  108.               hasDraw = status.hasDraw;
  109.             }
  110.             if (hasDraw) {
  111.               this.currentStatus = "draw star";
  112.             }
  113.           })
  114.           .margin(2)
  115.       }.justifyContent(FlexAlign.Center)
  116.     }
  117.     .width('100%')
  118.   }
  119. }

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

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

说明

本示例画图逻辑具体实现（和nativeRender相关的函数实现）可以参考ArkTS XComponent示例。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import nativeRender from 'libnativerender.so';
  3. 

  4. class MyXComponentController extends XComponentController {
  5.   onSurfaceCreated(surfaceId: string): void {
  6.     console.info(`onSurfaceCreated surfaceId: ${surfaceId}`);
  7.     nativeRender.SetSurfaceId(BigInt(surfaceId));
  8.   }
  9. 

  10.   onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
  11.     console.info(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}`);
  12.     nativeRender.ChangeSurface(BigInt(surfaceId), rect.surfaceWidth, rect.surfaceHeight);
  13.   }
  14. 

  15.   onSurfaceDestroyed(surfaceId: string): void {
  16.     console.info(`onSurfaceDestroyed surfaceId: ${surfaceId}`);
  17.     nativeRender.DestroySurface(BigInt(surfaceId));
  18.   }
  19. }
  20. 

  21. @Entry
  22. @Component
  23. struct Index {
  24.   @State isLock: boolean = true;
  25.   @State xcWidth: number = 500;
  26.   @State xcHeight: number = 700;
  27.   myXComponentController: XComponentController = new MyXComponentController();
  28. 

  29.   build() {
  30.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Start }) {
  31.       XComponent({
  32.         id: "XComponent",
  33.         type: XComponentType.SURFACE,
  34.         controller: this.myXComponentController
  35.       })
  36.         .onLoad(() => {
  37.           let surfaceRotation: SurfaceRotationOptions = { lock: this.isLock };
  38.           this.myXComponentController.setXComponentSurfaceRotation(surfaceRotation);
  39.           console.info("Surface getXComponentSurfaceRotation lock = " +
  40.           this.myXComponentController.getXComponentSurfaceRotation().lock);
  41.         })
  42.         .width(this.xcWidth)
  43.         .height(this.xcHeight)
  44.       Button("Draw")
  45.         .onClick(() => {
  46.           let surfaceId = this.myXComponentController.getXComponentSurfaceId();
  47.           nativeRender.DrawPattern(BigInt(surfaceId));
  48.         })
  49.     }
  50.   }
  51. }

示例3（使用画布对象在XComponent上绘制内容）

从API version 20开始，该示例通过调用lockCanvas返回画布对象，通过画布对象调用对应的绘制接口，再调用unlockCanvasAndPost在XComponent上绘制内容。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { drawing } from '@kit.ArkGraphics2D';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.   private xcController: XComponentController = new XComponentController();
  8.   private mCanvas: DrawingCanvas | null = null;
  9. 

  10.   build() {
  11.     Column() {
  12.       XComponent({ type: XComponentType.SURFACE, controller: this.xcController })
  13.         .width("80%")
  14.         .height("80%")
  15.         .onLoad(() => {
  16.           this.mCanvas = this.xcController.lockCanvas();
  17.           if (this.mCanvas) {
  18.             this.mCanvas.drawColor(255, 240, 250, 255); // 每次绘制前必须完全重绘整个XComponent区域，可以调用此方法实现
  19.             const brush = new drawing.Brush(); // 创建画刷对象
  20.             brush.setColor({ // 设置画刷的颜色
  21.               alpha: 255,
  22.               red: 39,
  23.               green: 135,
  24.               blue: 217
  25.             });
  26.             this.mCanvas.attachBrush(brush); // 绑定画刷到画布上
  27.             this.mCanvas.drawRect({ // 绘制一个矩形
  28.               left: 300,
  29.               right: 800,
  30.               top: 100,
  31.               bottom: 800
  32.             });
  33.             this.mCanvas.detachBrush(); // 将画刷与画布解绑
  34.             this.xcController.unlockCanvasAndPost(this.mCanvas);
  35.           }
  36.         })
  37.     }
  38.     .height('100%')
  39.     .width('100%')
  40.   }
  41. }

示例4（XComponent实现沉浸式效果）

从API version 20开始，在示例3的基础上，调用setXComponentSurfaceRect接口主动设置Surface显示区域达到沉浸式效果。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { display } from '@kit.ArkUI';
  3. @Entry
  4. @Component
  5. struct Index {
  6.   private xcController: XComponentController = new XComponentController();
  7.   private mCanvas: DrawingCanvas | null = null;
  8.   @State screenWidth: number = 0;
  9.   @State screenHeight:number = 0;
  10.   aboutToAppear() {
  11.     try {
  12.       const displayClass = display.getDefaultDisplaySync();
  13.       this.screenWidth = displayClass.width;
  14.       this.screenHeight = displayClass.height;
  15.     } catch (error) {
  16.       console.error(`Failed to get default display. Code: ${error.code}, message: ${error.message}`);
  17.     }
  18.   }
  19. 

  20.   build() {
  21.     Column() {
  22.       XComponent({ type: XComponentType.SURFACE, controller: this.xcController })
  23.         .width('100%')
  24.         .height('100%')
  25.         .onLoad(() => {
  26.           // 请在此处设置Surface大小，过大可能会导致绘制时间长
  27.           this.xcController.setXComponentSurfaceRect({surfaceWidth: this.screenWidth, surfaceHeight: this.screenHeight, offsetX: 0, offsetY: 0});
  28.           this.mCanvas = this.xcController.lockCanvas();
  29.           if (this.mCanvas) {
  30.             this.mCanvas.drawColor(255, 39, 135, 217); // 每次绘制前必须完全重绘整个XComponent区域，可以调用此方法实现
  31.             this.xcController.unlockCanvasAndPost(this.mCanvas);
  32.           }
  33.         })
  34.         .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]);
  35.     }
  36.     .height('100%')
  37.     .width('100%')
  38.   }
  39. }

示例5（设置XComponent持有Surface在渲染时是否需要被视为不透明）

从API version 22开始，该示例通过调用setXComponentSurfaceConfig接口设置XComponent持有的Surface在渲染时是否需要被视为不透明。

说明

本示例画图逻辑具体实现（和nativeRender相关的函数实现）可以参考ArkTS XComponent示例。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import nativeRender from 'libnativerender.so'; // 开发者自己实现的so，详见上述说明。
  3. 

  4. // 重写XComponentController，设置生命周期回调
  5. class MyXComponentController extends XComponentController {
  6.   onSurfaceCreated(surfaceId: string): void {
  7.     console.info(`onSurfaceCreated surfaceId: ${surfaceId}`);
  8.     nativeRender.SetSurfaceId(BigInt(surfaceId));
  9.   }
  10.   onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
  11.     console.info(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}`);
  12.     // 在onSurfaceChanged中调用ChangeSurface绘制内容
  13.     nativeRender.ChangeSurface(BigInt(surfaceId), rect.surfaceWidth, rect.surfaceHeight);
  14.   }
  15.   onSurfaceDestroyed(surfaceId: string): void {
  16.     console.info(`onSurfaceDestroyed surfaceId: ${surfaceId}`);
  17.     nativeRender.DestroySurface(BigInt(surfaceId));
  18.   }
  19. }
  20. 

  21. @Entry
  22. @Component
  23. struct Index {
  24.   @State currentStatus: string = "index";
  25.   xComponentController: XComponentController = new MyXComponentController();
  26. 

  27.   aboutToAppear(): void {
  28.     // 设置XComponent持有的Surface在渲染时被视为不透明
  29.     this.xComponentController.setXComponentSurfaceConfig({ isOpaque: true });
  30.   }
  31. 

  32.   build() {
  33.     Column() {
  34.       Column({ space: 10 }) {
  35.         XComponent({
  36.           type: XComponentType.SURFACE,
  37.           controller: this.xComponentController
  38.         })
  39.           .backgroundColor(Color.Transparent)
  40.         Text(this.currentStatus)
  41.           .fontSize('24fp')
  42.           .fontWeight(500)
  43.       }
  44.       .onClick(() => {
  45.         let surfaceId = this.xComponentController.getXComponentSurfaceId();
  46.         nativeRender.ChangeColor(BigInt(surfaceId));
  47.         let hasChangeColor: boolean = false;
  48.         let status = nativeRender.GetXComponentStatus(BigInt(surfaceId));
  49.         if (status) {
  50.           hasChangeColor = status.hasChangeColor;
  51.         }
  52.         if (hasChangeColor) {
  53.           this.currentStatus = "change color";
  54.         }
  55.       })
  56.       .margin({
  57.         top: 27,
  58.         left: 12,
  59.         right: 12
  60.       })
  61.       .height('40%')
  62.       .width('90%')
  63.       Row() {
  64.         Button('Draw Star')
  65.           .fontSize('16fp')
  66.           .fontWeight(500)
  67.           .margin({ bottom: 24 })
  68.           .onClick(() => {
  69.             let surfaceId = this.xComponentController.getXComponentSurfaceId();
  70.             nativeRender.DrawPattern(BigInt(surfaceId));
  71.             let hasDraw: boolean = false;
  72.             let status = nativeRender.GetXComponentStatus(BigInt(surfaceId));
  73.             if (status) {
  74.               hasDraw = status.hasDraw;
  75.             }
  76.             if (hasDraw) {
  77.               this.currentStatus = "draw star";
  78.             }
  79.           })
  80.           .width('53.6%')
  81.           .height(40)
  82.       }
  83.       .width('100%')
  84.       .justifyContent(FlexAlign.Center)
  85.       .alignItems(VerticalAlign.Bottom)
  86.       .layoutWeight(1)
  87.     }
  88.     .width('100%')
  89.     .height('100%')
  90.   }
  91. }

渲染绘制
Component3D
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明