鸿蒙OpenHarmony【XComponent】渲染绘制
提供用于图形绘制和媒体数据写入的Surface，XComponent负责将其嵌入到视图中，支持应用自定义Surface位置和大小。说明
该组件从API Version 8 开始支持。后续版本如有新增内容，则采取上角标单独标志该内容的起始版本。
子组件
无
接口
XComponent12+
XComponent(options: XComponentOptions)
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数:
参数名范例必填说明options是定义XComponent的具体设置参数。 XComponent10+
XComponent(value: {id: string, type: XComponentType, libraryname?: string, controller?: XComponentController})
该接口从API version 12开始不再演进，推荐使用。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数:
参数名范例必填说明idstring是组件的唯一标识，支持最大的字符串长度128。type是用于指定XComponent组件范例。librarynamestring否用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅范例为SURFACE或TEXTURE时有用。controller否给组件绑定一个控制器，通过控制器调用组件方法，仅范例为SURFACE或TEXTURE时有用。 XComponent(deprecated)
XComponent(value: {id: string, type: string, libraryname?: string, controller?: XComponentController})
说明：
从API version 12开始废弃，建议使用替代。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数:
参数名范例必填说明idstring是组件的唯一标识，支持最大的字符串长度128。typestring是用于指定XComponent组件范例，可选值仅有两个为：-“surface”：用于EGL/OpenGLES和媒体数据写入，开辟者定制的绘制内容单独展示到屏幕上。-"component"9+ ：XComponent将酿成一个容器组件，并可在其中执行非UI逻辑以动态加载显示内容。其他值均会被视为"surface"范例librarynamestring否应用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅XComponent范例为"surface"时有用。controller否给组件绑定一个控制器，通过控制器调用组件方法，仅XComponent范例为"surface"时有用。 XComponentOptions12+
定义XComponent的具体设置参数。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
名称范例必填说明type是用于指定XComponent组件范例。controller是给组件绑定一个控制器，通过控制器调用组件方法，仅范例为SURFACE或TEXTURE时有用。imageAIOptions否给组件设置一个AI分析选项，通过此项可设置分析范例或绑定一个分析控制器。 属性
除支持通用属性外，还支持以下属性：
说明
不支持foregroundColor、obscured和pixelStretchEffect属性，而且type为SURFACE范例时也不支持动态属性设置、自定义绘制、配景设置(backgroundColor除外)、图像结果(shadow除外)、maskShape和foregroundEffect属性。
enableAnalyzer12+
enableAnalyzer(enable: boolean)
设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能。
本功能需要搭配XComponentController的和一起使用。
不能和属性同时使用，两者同时设置时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开始废弃，建议使用替代。
系统能力： 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是XComponent持有Surface的显示区域。 说明
rect参数中的offsetX/offsetY不设置时，Surface显示区域相对于XComponent左上角x/y轴的偏移结果默认按照居中显示。
rect参数中的surfaceWidth和surfaceHeight存在0或负数时，调用该接口设置显示区域不生效。
该方法优先级高于、等可以改变内容偏移和大小的属性。
getXComponentSurfaceRect12+
getXComponentSurfaceRect(): SurfaceRect
获取XComponent持有Surface的显示区域，仅XComponent范例为SURFACE(“surface”)或TEXTURE时有用。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
返回值:
范例描述获取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是回调该方法的时候，绑定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是执行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是设置XComponent持有Surface在屏幕旋转时是否锁定方向。 说明
rotationOptions未设置时，默认XComponent持有Surface在屏幕旋转时不锁定方向，跟随屏幕进行旋转。
仅在屏幕旋转过程中生效，旋转完成后不再锁定Surface。
仅在屏幕旋转90°，即发生横竖屏切换时生效。
锁定旋转后的Buffer宽高需要保持不变，否则会有拉伸题目。
getXComponentSurfaceRotation12+
getXComponentSurfaceRotation(): Required
获取XComponent持有Surface在屏幕旋转时是否锁定方向的设置，仅XComponent范例为SURFACE(“surface”)时有用。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
返回值:
范例描述获取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属性在未调用也未设置和等属性时，其取值大小为XComponent组件的大小。
surfaceWidth和surfaceHeight属性的取值都不可超过8192px，否则会导致渲染非常。
示例
示例结果请以真机运行为准，当前IDE预览器不支持。
示例1
图像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:
};
private aiController: ImageAnalyzerController = new ImageAnalyzerController();
private options: ImageAIOptions = {
types: ,
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%")
}
}
https://i-blog.csdnimg.cn/direct/2d4c47d3dfc44cc6a97824474647240f.png
示例2
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%')
}
}
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]