鸿蒙OpenHarmony【XComponent】渲染绘制

提供用于图形绘制和媒体数据写入的Surface，XComponent负责将其嵌入到视图中，支持应用自定义Surface位置和大小。
说明
该组件从API Version 8 开始支持。后续版本如有新增内容，则采取上角标单独标志该内容的起始版本。
子组件

无
接口

XComponent12+

XComponent(options: XComponentOptions)
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数:
参数名范例必填说明options[XComponentOptions]是定义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。type[XComponentType]是用于指定XComponent组件范例。librarynamestring否用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅范例为SURFACE或TEXTURE时有用。controller[XComponentController]否给组件绑定一个控制器，通过控制器调用组件方法，仅范例为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"时有用。controller[XComponentcontroller]否给组件绑定一个控制器，通过控制器调用组件方法，仅XComponent范例为"surface"时有用。 XComponentOptions12+

定义XComponent的具体设置参数。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
名称范例必填说明type[XComponentType]是用于指定XComponent组件范例。controller[XComponentController]是给组件绑定一个控制器，通过控制器调用组件方法，仅范例为SURFACE或TEXTURE时有用。imageAIOptions[ImageAIOptions]否给组件设置一个AI分析选项，通过此项可设置分析范例或绑定一个分析控制器。 属性

除支持通用属性外，还支持以下属性：
说明
不支持foregroundColor、obscured和pixelStretchEffect属性，而且type为SURFACE范例时也不支持动态属性设置、自定义绘制、配景设置(backgroundColor除外)、图像结果(shadow除外)、maskShape和foregroundEffect属性。
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
创建对象

1. 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
参数:
参数名范例必填说明rect[SurfaceRect]是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。rect[SurfaceRect]是回调该方法的时候，绑定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
设置AI分析并启动AI分析功能，使用前需先[使能]图像AI分析能力。
该方法调用时，将截取调用时候的画面帧进行分析，使用时需注意启动分析的时机，避免出现画面和分析内容不同等的情况。
若该方法尚未执行完毕，此时重复调用，则会触发错误回调。
说明
分析范例不支持动态修改。
该特性依赖设备能力，不支持该能力的情况下，将返回错误码。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名范例必填说明config[ImageAnalyzerConfig]是执行AI分析所需要的入参，用于设置AI分析功能。 返回值：
范例说明PromisePromise对象，用于获取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
参数:
参数名范例必填说明rotationOptions[SurfaceRotationOptions]是设置XComponent持有Surface在屏幕旋转时是否锁定方向。 说明
rotationOptions未设置时，默认XComponent持有Surface在屏幕旋转时不锁定方向，跟随屏幕进行旋转。
仅在屏幕旋转过程中生效，旋转完成后不再锁定Surface。
仅在屏幕旋转90°，即发生横竖屏切换时生效。
锁定旋转后的Buffer宽高需要保持不变，否则会有拉伸题目。
getXComponentSurfaceRotation12+

getXComponentSurfaceRotation(): Required
获取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，否则会导致渲染非常。
示例

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

图像AI分析功能使用示例。

1. // xxx.ets
2. import { BusinessError } from '@kit.BasicServicesKit';
3. import nativeRender from 'libnativerender.so';
5. class CustomXComponentController extends XComponentController {
6.   onSurfaceCreated(surfaceId: string): void {
7.     console.log(`onSurfaceCreated surfaceId: ${surfaceId}`);
8.     nativeRender.SetSurfaceId(BigInt(surfaceId));
9.   }
11.   onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
12.     console.log(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}}`);
13.     nativeRender.ChangeSurface(BigInt(surfaceId), rect.surfaceWidth, rect.surfaceHeight);
14.   }
16.   onSurfaceDestroyed(surfaceId: string): void {
17.     console.log(`onSurfaceDestroyed surfaceId: ${surfaceId}`);
18.     nativeRender.DestroySurface(BigInt(surfaceId));
19.   }
20. }
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 = "320px";
35.   @State xcHeight: string = "480px";
36.   @State currentStatus: string = "index";
38.   build() {
39.     Column({ space: 5 }) {
40.       Button("change size")
41.         .onClick(() => {
42.           this.xcWidth = "640px";
43.           this.xcHeight = "720px";
44.         })
45.       Button('start AI analyze')
46.         .onClick(() => {
47.           this.xComponentController.startImageAnalyzer(this.config)
48.             .then(() => {
49.               console.log("analysis complete");
50.             })
51.             .catch((error: BusinessError) => {
52.               console.log("error code: " + error.code);
53.             })
54.         })
55.       Button('stop AI analyze')
56.         .onClick(() => {
57.           this.xComponentController.stopImageAnalyzer();
58.         })
59.       Button('get analyzer types')
60.         .onClick(() => {
61.           this.aiController.getImageAnalyzerSupportTypes();
62.         })
63.       Button('Draw Star')
64.         .fontSize('16fp')
65.         .fontWeight(500)
66.         .margin({ bottom: 24 })
67.         .onClick(() => {
68.           let surfaceId = this.xComponentController.getXComponentSurfaceId();
69.           this.xComponentController.getXComponentSurfaceRect();
70.           nativeRender.DrawPattern(BigInt(surfaceId));
71.           let hasDraw: boolean = false;
72.           if (nativeRender.GetXComponentStatus(BigInt(surfaceId))) {
73.             hasDraw = nativeRender.GetXComponentStatus(BigInt(surfaceId)).hasDraw;
74.           }
75.           if (hasDraw) {
76.             this.currentStatus = "draw star";
77.           }
78.         })
79.       XComponent({
80.         type: XComponentType.SURFACE,
81.         controller: this.xComponentController,
82.         imageAIOptions: this.options
83.       })
84.         .width(this.xcWidth)
85.         .height(this.xcHeight)
86.         .enableAnalyzer(true)
87.       Text(this.currentStatus)
88.         .fontSize('24fp')
89.         .fontWeight(500)
90.     }
91.     .width("100%")
92.   }
93. }

复制代码

示例2

surface旋转过程中锁定功能使用示例。

1. // xxx.ets
2. @Entry
3. @Component
4. struct Index{
5.   @State isLock: boolean = true;
6.   @State xc_width: number = 500;
7.   @State xc_height: number = 700;
8.   myXComponentController: XComponentController = new XComponentController();
10.   build() {
11.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Start }) {
12.       XComponent({
13.         id: 'xComponentId',
14.         type: XComponentType.SURFACE,
15.         libraryname: 'nativerender',
16.         controller: this.myXComponentController
17.       })
18.       .width(this.xc_width)
19.       .height(this.xc_height)
20.       .onLoad(() => {
21.         let surfaceRotation: SurfaceRotationOptions = { lock: this.isLock };
22.         this.myXComponentController.setXComponentSurfaceRotation(surfaceRotation);
23.         console.log("Surface getXComponentSurfaceRotation lock = " +
24.           this.myXComponentController.getXComponentSurfaceRotation().lock);
25.       })
26.     }
27.     .width('100%')
28.     .height('100%')
29.   }
30. }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。