1# XComponent 2 3提供用于图形绘制和媒体数据写入的Surface，XComponent负责将其嵌入到视图中，支持应用自定义Surface位置和大小。具体指南请参考[自定义渲染 (XComponent)文档](../../../ui/napi-xcomponent-guidelines.md)。 4 5> **说明：** 6> 7> 该组件从API version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11无 12 13## 接口 14 15### XComponent<sup>12+</sup> 16 17XComponent(options: XComponentOptions) 18 19创建XComponent组件，支持在ArkTS侧获取SurfaceId、注册XComponent持有的Surface的生命周期回调和触摸、鼠标、按键等组件事件回调，支持AI分析。 20 21**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数:** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | --------------------------------------- | ---- | ------------------------------ | 29| options | [XComponentOptions](#xcomponentoptions12) | 是 | 定义XComponent的具体配置参数。 | 30 31### XComponent<sup>10+</sup> 32 33XComponent(value: {id: string, type: XComponentType, libraryname?: string, controller?: XComponentController}) 34 35创建XComponent组件，支持Native侧触发XComponent生命周期回调。 36 37该接口从API version 12开始不再演进，推荐使用[XComponent(options: XComponentOptions)](#xcomponent12)。 38 39**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.ArkUI.ArkUI.Full 42 43**参数:** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| ----------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 47| id | string | 是 | 组件的唯一标识，支持最大的字符串长度128。 | 48| type | [XComponentType](ts-appendix-enums.md#xcomponenttype10) | 是 | 用于指定XComponent组件类型。 | 49| libraryname | string | 否 | 用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅类型为SURFACE或TEXTURE时有效。 | 50| controller | [XComponentController](#xcomponentcontroller) | 否 | 给组件绑定一个控制器，通过控制器调用组件方法，仅类型为SURFACE或TEXTURE时有效。 | 51 52### XComponent<sup>(deprecated)</sup> 53 54XComponent(value: {id: string, type: string, libraryname?: string, controller?: XComponentController}) 55 56**说明：** 57 58从API version 12开始废弃，建议使用[XComponent(options: XComponentOptions)](#xcomponent12)替代。 59 60**系统能力：** SystemCapability.ArkUI.ArkUI.Full 61 62**参数:** 63 64| 参数名 | 类型 | 必填 | 说明 | 65| ----------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 66| id | string | 是 | 组件的唯一标识，支持最大的字符串长度128。 | 67| type | string | 是 | 用于指定XComponent组件类型，可选值仅有两个为：<br/>-"surface"：用于EGL/OpenGLES和媒体数据写入，开发者定制的绘制内容单独展示到屏幕上。<br/>-"component"<sup>9+</sup> ：XComponent将变成一个容器组件，并可在其中执行非UI逻辑以动态加载显示内容。<br/>其他值均会被视为"surface"类型 | 68| libraryname | string | 否 | 应用Native层编译输出动态库名称（对应的动态库不支持跨模块加载），仅XComponent类型为"surface"时有效。 | 69| controller | [XComponentcontroller](#xcomponentcontroller) | 否 | 给组件绑定一个控制器，通过控制器调用组件方法，仅XComponent类型为"surface"时有效。 | 70 71## XComponentOptions<sup>12+</sup> 72 73定义XComponent的具体配置参数。 74 75**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79| 名称 | 类型 | 必填 | 说明 | 80| -------- | -------- | -------- | -------- | 81| type | [XComponentType](ts-appendix-enums.md#xcomponenttype10) | 是 | 用于指定XComponent组件类型。 | 82| controller | [XComponentController](#xcomponentcontroller) | 是 | 给组件绑定一个控制器，通过控制器调用组件方法，仅类型为SURFACE或TEXTURE时有效。 | 83| imageAIOptions | [ImageAIOptions](ts-image-common.md#imageaioptions) | 否 | 给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。 | 84 85 86## 属性 87除支持通用属性外，还支持以下属性： 88 > 89 > **说明：** 90 > 91 > 不支持foregroundColor、obscured和pixelStretchEffect属性，并且type为SURFACE类型时也不支持动态属性设置、自定义绘制、背景设置(backgroundColor除外)、图像效果(shadow除外)、maskShape和foregroundEffect属性。 92 > 93 > 对于TEXTURE和SURFACE类型的XComponent组件，当不设置[renderFit](./ts-universal-attributes-renderfit.md)属性时，取默认值为RenderFit.RESIZE_FILL。 94 > 95 > 对于SURFACE类型的XComponent组件，当组件背景色为不透明的纯黑色时，其[renderFit](./ts-universal-attributes-renderfit.md)通用属性仅支持设置为RenderFit.RESIZE_FILL，不推荐设置为其他的RenderFit枚举值。 96 > 97 > 对于使用[ArkUI NDK接口](../../../ui/ndk-access-the-arkts-page.md)创建的XComponent组件，不支持使用属性获取函数[getAttribute](../_ark_u_i___native_node_a_p_i__1.md#getattribute)获取其renderFit属性值。 98 99### enableAnalyzer<sup>12+</sup> 100 101enableAnalyzer(enable: boolean) 102 103设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能。 104本功能需要搭配XComponentController的[StartImageAnalyzer](#startimageanalyzer12)和[StopImageAnalyzer](#stopimageanalyzer12)一起使用。 105不能和[overlay](ts-universal-attributes-overlay.md)属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。 106 107**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 108 109**系统能力：** SystemCapability.ArkUI.ArkUI.Full 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| -------- | -------- | -------- | -------- | 115| enable | boolean | 是 | 是否启用图像分析功能。<br/>true：开启图像分析；false：关闭图像分析。<br/>默认值：false | 116 117 > **说明：** 118 > 119 > 仅type为SURFACE和TEXTURE时该功能有效。 120 121### enableSecure<sup>13+</sup> 122 123enableSecure(isSecure: boolean) 124 125防止组件内自绘制内容被截屏、录屏。 126 127**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| -------- | ------- | ---- | ---------------------- | 135| isSecure | boolean | 是 | 是否开启隐私图层模式。<br/>true：开启隐私图层模式；false：关闭隐私图层模式。<br/>默认值：false | 136 137 > **说明：** 138 > 139 > 仅type为SURFACE时有效。 140 > 141 > 不支持[ArkUI NDK接口](../../../ui/ndk-build-ui-overview.md)创建的XComponent组件。 142 143## 事件 144 145从API version 12开始，type为SURFACE或TEXTURE时，支持[通用事件](ts-component-general-events.md)。 146 147> **说明：** 148> 149> 当配置libraryname参数时，[点击事件](ts-universal-events-click.md)、[触摸事件](ts-universal-events-touch.md)、[挂载卸载事件](ts-universal-events-show-hide.md)、[按键事件](ts-universal-events-key.md)、[焦点事件](ts-universal-focus-event.md)、[鼠标事件](ts-universal-mouse-key.md)仅响应C-API侧事件接口。 150 151仅type为SURFACE或TEXTURE时以下事件有效： 152 153### onLoad 154 155onLoad(callback: OnNativeLoadCallback ) 156 157插件加载完成时回调事件。 158 159**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 160 161**系统能力：** SystemCapability.ArkUI.ArkUI.Full 162 163**参数:** 164 165| 参数名 | 类型 | 必填 | 说明 | 166| ----- | ------ | ---- | ---------------------------------------- | 167| callback | [OnNativeLoadCallback](#onnativeloadcallback18) | 是 | XComponent持有的Surface创建后回调事件。 | 168 169> **说明：** 170> 171> 使用自定义组件节点创建XComponent组件时，因为onLoad回调触发时机早于[onSurfaceCreated](#onsurfacecreated12),所以在onLoad回调中调用[getXComponentSurfaceId](#getxcomponentsurfaceid9)获取surfaceId会失败，建议在[onSurfaceCreated](#onsurfacecreated12)回调中获取。 172 173### onDestroy 174 175onDestroy(event: VoidCallback ) 176 177插件卸载完成时回调事件。 178 179**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 180 181**系统能力：** SystemCapability.ArkUI.ArkUI.Full 182 183**参数:** 184 185| 参数名 | 类型 | 必填 | 说明 | 186| ----- | ------ | ---- | ---------------------------------------- | 187| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | XComponent销毁后回调事件。 | 188 189## OnNativeLoadCallback<sup>18+</sup> 190 191type OnNativeLoadCallback = (event?: object) =\> void 192 193XComponent持有的Surface创建后回调事件。 194 195**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 196 197**系统能力：** SystemCapability.ArkUI.ArkUI.Full 198 199**参数:** 200 201| 参数名 | 类型 | 必填 | 说明 | 202| ----- | ------ | ---- | ---------------------------------------- | 203| event | object | 否 | 获取XComponent实例对象的context，context上挂载的方法由开发者在Native层定义。 | 204 205## XComponentController 206 207XComponent组件的控制器，可以将此对象绑定至XComponent组件，然后通过控制器来调用组件方法。 208 209**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 210 211**系统能力：** SystemCapability.ArkUI.ArkUI.Full 212 213**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 214 215### constructor 216 217constructor() 218 219XComponentController的构造函数。 220 221```ts 222xcomponentController: XComponentController = new XComponentController() 223``` 224 225**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 226 227**系统能力：** SystemCapability.ArkUI.ArkUI.Full 228 229### getXComponentSurfaceId<sup>9+</sup> 230 231getXComponentSurfaceId(): string 232 233获取XComponent对应Surface的ID，供@ohos接口使用，使用方式可参考[相机管理](../../apis-camera-kit/js-apis-camera.md)，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 234 235**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239**返回值:** 240 241| 类型 | 描述 | 242| ------ | ----------------------- | 243| string | XComponent持有Surface的ID。 | 244 245 246### setXComponentSurfaceSize<sup>(deprecated)</sup> 247 248setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): void 249 250设置XComponent持有Surface的宽度和高度，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 251 252该接口从API version 12开始废弃，建议使用[setXComponentSurfaceRect](#setxcomponentsurfacerect12)替代。 253 254**系统能力：** SystemCapability.ArkUI.ArkUI.Full 255 256**参数:** 257 258| 参数名 | 类型 | 必填 | 说明 | 259| ------------- | ------ | ---- | ----------------------- | 260| surfaceWidth | number | 是 | XComponent持有Surface的宽度。 | 261| surfaceHeight | number | 是 | XComponent持有Surface的高度。 | 262 263 264### getXComponentContext 265 266getXComponentContext(): Object 267 268获取XComponent实例对象的context，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 269 270**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 271 272**系统能力：** SystemCapability.ArkUI.ArkUI.Full 273 274**返回值:** 275 276| 类型 | 描述 | 277| ------ | ------------------------------------------------------------ | 278| Object | 获取XComponent实例对象的context，context包含的具体接口方法由开发者自定义，context内容与onLoad回调中的第一个参数一致。 | 279 280### setXComponentSurfaceRect<sup>12+</sup> 281 282setXComponentSurfaceRect(rect: SurfaceRect): void 283 284设置XComponent持有Surface的显示区域，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 285 286**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 287 288**系统能力：** SystemCapability.ArkUI.ArkUI.Full 289 290**参数:** 291 292| 参数名 | 类型 | 必填 | 说明 | 293| ------ | ------------------------------------ | ---- | --------------------------------- | 294| rect | [SurfaceRect](#surfacerect12对象说明) | 是 | XComponent持有Surface的显示区域。 | 295 296> **说明：** 297> 298> rect参数中的offsetX/offsetY不设置时，Surface显示区域相对于XComponent左上角x/y轴的偏移效果默认按照居中显示。 299> 300> rect参数中的surfaceWidth和surfaceHeight存在0或负数时，调用该接口设置显示区域不生效。 301> 302> 该方法优先级高于[border](ts-universal-attributes-border.md#border)、[padding](ts-universal-attributes-size.md#padding)等可以改变内容偏移和大小的属性。 303 304### getXComponentSurfaceRect<sup>12+</sup> 305 306getXComponentSurfaceRect(): SurfaceRect 307 308获取XComponent持有Surface的显示区域，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 309 310**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 311 312**系统能力：** SystemCapability.ArkUI.ArkUI.Full 313 314**返回值:** 315 316| 类型 | 描述 | 317| ------------------------------------ | ------------------------------------- | 318| [SurfaceRect](#surfacerect12对象说明) | 获取XComponent持有Surface的显示区域。 | 319 320### onSurfaceCreated<sup>12+</sup> 321 322onSurfaceCreated(surfaceId: string): void 323 324当XComponent持有的Surface创建后进行该回调，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 325 326**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 327 328**系统能力：** SystemCapability.ArkUI.ArkUI.Full 329 330**参数:** 331 332| 参数名 | 类型 | 必填 | 说明 | 333| --------- | -------- | ---- | ------------------------------------------------- | 334| surfaceId | string | 是 | 回调该方法的时候，绑定XComponent持有Surface的ID。 | 335 336> **说明：** 337> 338> 仅当XComponent组件未设置libraryname参数时，会进行该回调。 339 340### onSurfaceChanged<sup>12+</sup> 341 342onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void 343 344当XComponent持有的Surface大小改变后（包括首次创建时的大小改变）进行该回调，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 345 346**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 347 348**系统能力：** SystemCapability.ArkUI.ArkUI.Full 349 350**参数:** 351 352| 参数名 | 类型 | 必填 | 说明 | 353| --------- | ------------------------------------- | ---- | ------------------------------------------------------- | 354| surfaceId | string | 是 | 回调该方法的时候，绑定XComponent持有Surface的ID。 | 355| rect | [SurfaceRect](#surfacerect12对象说明) | 是 | 回调该方法的时候，绑定XComponent持有Surface的显示区域。 | 356 357> **说明：** 358> 359> 仅当XComponent组件未设置libraryname参数时，会进行该回调。 360 361### onSurfaceDestroyed<sup>12+</sup> 362 363onSurfaceDestroyed(surfaceId: string): void 364 365当XComponent持有的Surface销毁后进行该回调，仅XComponent类型为SURFACE("surface")或TEXTURE时有效。 366 367**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 368 369**系统能力：** SystemCapability.ArkUI.ArkUI.Full 370 371**参数:** 372 373| 参数名 | 类型 | 必填 | 说明 | 374| --------- | -------- | ---- | ------------------------------------------------- | 375| surfaceId | string | 是 | 回调该方法的时候，绑定XComponent持有Surface的ID。 | 376 377> **说明：** 378> 379> 仅当XComponent组件未设置libraryname参数时，会进行该回调。 380 381### startImageAnalyzer<sup>12+</sup> 382 383startImageAnalyzer(config: ImageAnalyzerConfig): Promise\<void> 384 385配置AI分析并启动AI分析功能，使用前需先[启用图像AI分析能力](#enableanalyzer12)。<br>该方法调用时，将截取调用时刻的画面帧进行分析，使用时需注意启动分析的时机，避免出现画面和分析内容不一致的情况。<br>若该方法尚未执行完毕，此时重复调用，则会触发错误回调。 386 387> **说明：** 388> 389> 分析类型不支持动态修改。 390> 该特性依赖设备能力，不支持该能力的情况下，将返回错误码。 391 392**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 393 394**系统能力：** SystemCapability.ArkUI.ArkUI.Full 395 396**参数：** 397 398| 参数名 | 类型 | 必填 | 说明 | 399| ------ | --------- | ---- | ---------------------------------------------------------------------- | 400| config | [ImageAnalyzerConfig](ts-image-common.md#imageanalyzerconfig) | 是 | 执行AI分析所需要的入参，用于配置AI分析功能。 | 401 402**返回值：** 403 404| 类型 | 说明 | 405| ----------------- | ------------------------------------ | 406| Promise\<void> | Promise对象，用于获取AI分析是否成功执行。 | 407 408**错误码：** 409 410以下错误码的详细介绍请参见[AI分析类库错误码](../errorcode-image-analyzer.md)。 411 412| 错误码ID | 错误信息 | 413| -------- | -------------------------------------------- | 414| 110001 | Image analysis feature is unsupported. | 415| 110002 | Image analysis is currently being executed. | 416| 110003 | Image analysis is stopped. | 417 418### stopImageAnalyzer<sup>12+</sup> 419 420stopImageAnalyzer(): void 421 422停止AI分析功能，AI分析展示的内容将被销毁。 423 424> **说明：** 425> 426> 在startImageAnalyzer方法未返回结果时调用本方法，会触发其错误回调。 427> 该特性依赖设备能力。 428 429**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 430 431**系统能力：** SystemCapability.ArkUI.ArkUI.Full 432 433### setXComponentSurfaceRotation<sup>12+</sup> 434 435setXComponentSurfaceRotation(rotationOptions: SurfaceRotationOptions): void 436 437设置XComponent持有Surface在屏幕旋转时是否锁定方向，仅XComponent类型为SURFACE("surface")时有效。 438 439**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 440 441**系统能力：** SystemCapability.ArkUI.ArkUI.Full 442 443**参数:** 444 445| 参数名 | 类型 | 必填 | 说明 | 446| ------ | ------------------------------------ | ---- | --------------------------------- | 447| rotationOptions | [SurfaceRotationOptions](#surfacerotationoptions12对象说明) | 是 | 设置XComponent持有Surface在屏幕旋转时是否锁定方向。 | 448 449> **说明：** 450> 451> rotationOptions未配置时，默认XComponent持有Surface在屏幕旋转时不锁定方向，跟随屏幕进行旋转。 452> 453> 仅在屏幕旋转过程中生效，旋转完成后不再锁定Surface。 454> 455> 仅在屏幕旋转90°，即发生横竖屏切换时生效。 456> 457> 锁定旋转后的Buffer宽高需要保持不变，否则会有拉伸问题。 458 459### getXComponentSurfaceRotation<sup>12+</sup> 460 461getXComponentSurfaceRotation(): Required\<SurfaceRotationOptions> 462 463获取XComponent持有Surface在屏幕旋转时是否锁定方向的设置，仅XComponent类型为SURFACE("surface")时有效。 464 465**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 466 467**系统能力：** SystemCapability.ArkUI.ArkUI.Full 468 469**返回值:** 470 471| 类型 | 描述 | 472| ------------------------------------ | ------------------------------------- | 473| [SurfaceRotationOptions](#surfacerotationoptions12对象说明) | 获取XComponent持有Surface在屏幕旋转时是否锁定方向的设置。 | 474 475## SurfaceRotationOptions<sup>12+</sup>对象说明 476 477用于描述XComponent持有Surface在屏幕旋转时是否锁定方向的设置。 478 479**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 480 481**系统能力：** SystemCapability.ArkUI.ArkUI.Full 482 483| 名称 | 类型 | 必填 | 说明 | 484| ------------- | ------ | ---- | ------------------------------------------------------------ | 485| lock | boolean | 否 | Surface在屏幕旋转时是否锁定方向，未设置时默认取值为false，即不锁定方向。<br/>true：锁定方向；false：不锁定方向。 | 486 487## SurfaceRect<sup>12+</sup>对象说明 488 489用于描述XComponent持有Surface的显示区域。 490 491**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 492 493**系统能力：** SystemCapability.ArkUI.ArkUI.Full 494 495| 名称 | 类型 | 必填 | 说明 | 496| ------------- | ------ | ---- | ------------------------------------------------------------ | 497| offsetX | number | 否 | Surface显示区域相对于XComponent组件左上角的x轴坐标，单位：px。 | 498| offsetY | number | 否 | Surface显示区域相对于XComponent组件左上角的y轴坐标，单位：px。 | 499| surfaceWidth | number | 是 | Surface显示区域的宽度，单位：px。 | 500| surfaceHeight | number | 是 | Surface显示区域的高度，单位：px。 | 501 502> **说明：** 503> 504> surfaceWidth和surfaceHeight属性在未调用[setXComponentSurfaceRect](ts-basic-components-xcomponent.md#setxcomponentsurfacerect12)也未设置[border](ts-universal-attributes-border.md#border)和[padding](ts-universal-attributes-size.md#padding)等属性时，其取值大小为XComponent组件的大小。 505> 506> surfaceWidth和surfaceHeight属性的取值都不可超过8192px，否则会导致渲染异常。 507 508## 示例 509 510示例效果请以真机运行为准，当前DevEco Studio预览器不支持。 511 512 513### 示例1（图像AI分析功能） 514 515使用enableAnalyzer属性开启图像AI分析功能。可通过XComponentController控制开始、停止图形AI分析。 516 517<!--Del--> 518> **说明：** 519> 520> 本示例画图逻辑具体实现（和nativeRender相关的函数实现）可以参考[ArkTSXComponent示例](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Native/ArkTSXComponent) 521<!--DelEnd--> 522 523```ts 524// xxx.ets 525import { BusinessError } from '@kit.BasicServicesKit'; 526import nativeRender from 'libnativerender.so'; 527 528class CustomXComponentController extends XComponentController { 529 onSurfaceCreated(surfaceId: string): void { 530 console.log(`onSurfaceCreated surfaceId: ${surfaceId}`); 531 nativeRender.SetSurfaceId(BigInt(surfaceId)); 532 } 533 534 onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void { 535 console.log(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}}`); 536 nativeRender.ChangeSurface(BigInt(surfaceId), rect.surfaceWidth, rect.surfaceHeight); 537 } 538 539 onSurfaceDestroyed(surfaceId: string): void { 540 console.log(`onSurfaceDestroyed surfaceId: ${surfaceId}`); 541 nativeRender.DestroySurface(BigInt(surfaceId)); 542 } 543} 544 545@Entry 546@Component 547struct XComponentExample { 548 xComponentController: XComponentController = new CustomXComponentController(); 549 private config: ImageAnalyzerConfig = { 550 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] 551 }; 552 private aiController: ImageAnalyzerController = new ImageAnalyzerController(); 553 private options: ImageAIOptions = { 554 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], 555 aiController: this.aiController 556 }; 557 @State xcWidth: string = "320px"; 558 @State xcHeight: string = "480px"; 559 @State currentStatus: string = "index"; 560 561 build() { 562 Column({ space: 5 }) { 563 Button("change size") 564 .onClick(() => { 565 this.xcWidth = "640px"; 566 this.xcHeight = "720px"; 567 }) 568 Button('start AI analyze') 569 .onClick(() => { 570 this.xComponentController.startImageAnalyzer(this.config) 571 .then(() => { 572 console.log("analysis complete"); 573 }) 574 .catch((error: BusinessError) => { 575 console.log("error code: " + error.code); 576 }) 577 }) 578 Button('stop AI analyze') 579 .onClick(() => { 580 this.xComponentController.stopImageAnalyzer(); 581 }) 582 Button('get analyzer types') 583 .onClick(() => { 584 this.aiController.getImageAnalyzerSupportTypes(); 585 }) 586 Button('Draw Star') 587 .fontSize('16fp') 588 .fontWeight(500) 589 .margin({ bottom: 24 }) 590 .onClick(() => { 591 let surfaceId = this.xComponentController.getXComponentSurfaceId(); 592 this.xComponentController.getXComponentSurfaceRect(); 593 nativeRender.DrawPattern(BigInt(surfaceId)); 594 let hasDraw: boolean = false; 595 if (nativeRender.GetXComponentStatus(BigInt(surfaceId))) { 596 hasDraw = nativeRender.GetXComponentStatus(BigInt(surfaceId)).hasDraw; 597 } 598 if (hasDraw) { 599 this.currentStatus = "draw star"; 600 } 601 }) 602 XComponent({ 603 type: XComponentType.SURFACE, 604 controller: this.xComponentController, 605 imageAIOptions: this.options 606 }) 607 .width(this.xcWidth) 608 .height(this.xcHeight) 609 .enableAnalyzer(true) 610 Text(this.currentStatus) 611 .fontSize('24fp') 612 .fontWeight(500) 613 } 614 .width("100%") 615 } 616} 617``` 618<!--RP1--><!--RP1End--> 619 620### 示例2（在surface旋转过程中锁定） 621 622通过setXComponentSurfaceRotation设置surface在屏幕旋转过程中锁定方向，不跟随屏幕进行旋转。 623 624```ts 625// xxx.ets 626@Entry 627@Component 628struct Index { 629 @State isLock: boolean = true; 630 @State xc_width: number = 500; 631 @State xc_height: number = 700; 632 myXComponentController: XComponentController = new XComponentController(); 633 634 build() { 635 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Start }) { 636 XComponent({ 637 id: 'xComponentId', 638 type: XComponentType.SURFACE, 639 libraryname: 'nativerender', 640 controller: this.myXComponentController 641 }) 642 .width(this.xc_width) 643 .height(this.xc_height) 644 .onLoad(() => { 645 let surfaceRotation: SurfaceRotationOptions = { lock: this.isLock }; 646 this.myXComponentController.setXComponentSurfaceRotation(surfaceRotation); 647 console.log("Surface getXComponentSurfaceRotation lock = " + 648 this.myXComponentController.getXComponentSurfaceRotation().lock); 649 }) 650 } 651 .width('100%') 652 .height('100%') 653 } 654} 655``` 656 657