鸿蒙HarmonyOS NEXT开发:XComponent(基础组件)

150 篇文章 0 订阅

XComponent

可用于EGL/OpenGLES和媒体数据写入,并显示在XComponent组件。

说明:

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

子组件

构造参数type为"surface"时不支持。

从API version 9开始,构造参数type为"component"时可以包含子组件。

接口

XComponent

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

参数:

参数名参数类型必填描述
idstring组件的唯一标识,支持最大的字符串长度128。
typestring用于指定XComponent组件类型,可选值仅有两个为:
-“surface”:用于EGL/OpenGLES和媒体数据写入,开发者定制的绘制内容单独展示到屏幕上。
-“component”9+ :XComponent将变成一个容器组件,并可在其中执行非UI逻辑以动态加载显示内容。
其他值均会被视为"surface"类型
librarynamestring应用Native层编译输出动态库名称,仅XComponent类型为"surface"时有效。
controllerXComponentcontroller给组件绑定一个控制器,通过控制器调用组件方法,仅XComponent类型为"surface"时有效。

XComponent10+

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

参数:

参数名参数类型必填描述
idstring组件的唯一标识,支持最大的字符串长度128。
typeXComponentType用于指定XComponent组件类型。
librarynamestring用Native层编译输出动态库名称,仅类型为SURFACE或TEXTURE时有效。
controllerXComponentcontroller给组件绑定一个控制器,通过控制器调用组件方法,仅类型为SURFACE或TEXTURE时有效。

XComponentType10+枚举说明

名称描述
SURFACE用于EGL/OpenGLES和媒体数据写入,开发者定制的绘制内容单独展示到屏幕上。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
COMPONENTXComponent将变成一个容器组件,并可在其中执行非UI逻辑以动态加载显示内容。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
TEXTURE用于EGL/OpenGLES和媒体数据写入,开发者定制的绘制内容会和XComponent组件的内容合成后展示到屏幕上。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
NODE用于Native UI节点的占位容器,开发者通过Native API 开发的页面组件可展示在此容器区域内。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

说明:

type为COMPONENT(“component”)时,XComponent作为容器,子组件沿垂直方向布局:

  • 垂直方向上对齐格式:FlexAlign.Start
  • 水平方向上对齐格式:FlexAlign.Center

所有的事件响应均不支持。

布局方式更改和事件响应均可通过挂载子组件来设置。

内部所写的非UI逻辑需要封装在一个或多个函数内。

属性

enableAnalyzer12+

enableAnalyzer(enable: boolean)

设置组件支持AI分析,需要搭配XComponentController的StartImageAnalyzerStopImageAnalyzer一起使用。 不能和overlay属性同时使用,两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

参数:

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

说明:

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

事件

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

说明:

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

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

onLoad

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

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

参数:

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

onDestroy

onDestroy(event: () => void )

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

XComponentController

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

创建对象

xcomponentController: XComponentController = new XComponentController()

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

getXComponentSurfaceId

getXComponentSurfaceId(): string

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

返回值:

类型描述
stringXComponent持有Surface的ID。

setXComponentSurfaceSize(deprecated)

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

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

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

参数:

参数名参数类型必填描述
surfaceWidthnumberXComponent持有Surface的宽度。
surfaceHeightnumberXComponent持有Surface的高度。

getXComponentContext

getXComponentContext(): Object

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

返回值:

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

setXComponentSurfaceRect12+

setXComponentSurfaceRect(rect: SurfaceRect): void

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

参数:

参数名参数类型必填描述
rectSurfaceRectXComponent持有Surface的显示区域。

说明:

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

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

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

getXComponentSurfaceRect12+

getXComponentSurfaceRect(): SurfaceRect

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

返回值:

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

onSurfaceCreated12+

onSurfaceCreated(surfaceId: string): void

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

参数:

参数名参数类型必填描述
surfaceIdstring回调该方法的时候,绑定XComponent持有Surface的ID。

说明:

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

onSurfaceChanged12+

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

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

参数:

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

说明:

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

onSurfaceDestroyed12+

onSurfaceDestroyed(surfaceId: string): void

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

参数:

参数名参数类型必填描述
surfaceIdstring回调该方法的时候,绑定XComponent持有Surface的ID。

说明:

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

SurfaceRect12+类型说明

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

名称类型必填说明
offsetXnumberSurface显示区域相对于XComponent组件左上角的x轴坐标,单位:px。
offsetYnumberSurface显示区域相对于XComponent组件左上角的y轴坐标,单位:px。
surfaceWidthnumberSurface显示区域的宽度,单位:px。
surfaceHeightnumberSurface显示区域的高度,单位:px。

startImageAnalyzer12+

startImageAnalyzer(config: ImageAnalyzerConfig): Promise<void>

配置AI分析并启动AI分析功能,使用前需先使能图像AI分析能力。
该方法调用时,将截取调用时刻的画面帧进行分析,使用时需注意启动分析的时机,避免出现画面和分析内容不一致的情况。
若该方法尚未执行完毕,此时重复调用,则会触发错误回调。

说明:

分析类型不支持动态修改。 该特性依赖设备能力,不支持该能力的情况下,将返回错误码。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

参数:

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

返回值:

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

错误码:

以下错误码的详细介绍请参见AI分析类库错误码

错误码ID错误信息
110001AI analysis is unsupported.
110002AI analysis is ongoing.

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开始,该接口支持在原子化服务中使用。

参数:

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

说明:

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

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

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

getXComponentSurfaceRotation12+

getXComponentSurfaceRotation(): Required<SurfaceRotationOptions>

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

返回值:

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

SurfaceRotationOptions12+类型说明

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

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

示例

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

示例1

// xxx.ets
@Entry
@Component
struct PreviewArea {
  private surfaceId: string = ''
  private xComponentContext: Record<string, () => void> = {}
  xComponentController: XComponentController = new XComponentController()
  @State rect: SurfaceRect | null = null

  build() {
    Column() {
      Text(JSON.stringify(this.rect))
        .fontSize(12)
      XComponent({
        id: 'xcomponent',
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
        .onLoad(() => {
          this.surfaceId = this.xComponentController.getXComponentSurfaceId()
          this.xComponentContext = this.xComponentController.getXComponentContext() as Record<string, () => void>
          let surfaceRect: SurfaceRect = { offsetX: 20, offsetY: 20, surfaceWidth: 500, surfaceHeight: 500 }
          this.xComponentController.setXComponentSurfaceRect(surfaceRect)
          this.rect = this.xComponentController.getXComponentSurfaceRect()
        })
        .width('640px')
        .height('480px')
    }
    .position({ x: 0, y: 48 })
  }
}
ts

示例2

// xxx.ets
class CustomXComponentController extends XComponentController {
  onSurfaceCreated(surfaceId: string): void {
    console.log(`onSurfaceCreated surfaceId: ${surfaceId}`)
  }

  onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
    console.log(`onSurfaceChanged surfaceId: ${surfaceId}, rect: ${JSON.stringify(rect)}}`)
  }

  onSurfaceDestroyed(surfaceId: string): void {
    console.log(`onSurfaceDestroyed surfaceId: ${surfaceId}`)
  }
}

@Entry
@Component
struct SurfaceCallbackDemo {
  xComponentController: XComponentController = new CustomXComponentController()
  @State xcWidth: string = "320px"
  @State xcHeight: string = "480px"

  build() {
    Column() {
      Button("change size")
        .onClick(() => {
          this.xcWidth = "640px"
          this.xcHeight = "960px"
        })
      XComponent({
        id: 'xcomponent',
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
        .width(this.xcWidth)
        .height(this.xcHeight)
    }
    .width("100%")
  }
}
ts

示例3

图像分析功能使用示例。

// xxx.ets
import { BusinessError } from '@ohos.base';

@Entry
@Component
struct ImageAnalyzerExample {
  xComponentController: XComponentController = new XComponentController()
  private config: ImageAnalyzerConfig = {
    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
  }

  build() {
    Column() {
      Button('start')
        .width(80)
        .height(80)
        .onClick(() => {
          this.xComponentController.startImageAnalyzer(this.config)
            .then(() => {
              console.log("analysis complete")
            })
            .catch((error: BusinessError) => {
              console.log("error code: " + error.code)
            })
        })
      Button('stop')
        .width(80)
        .height(80)
        .onClick(() => {
          this.xComponentController.stopImageAnalyzer()
        })
      XComponent({
        id: 'xcomponent',
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
        .enableAnalyzer(true)
        .width('640px')
        .height('480px')
    }
    .width("100%")
  }
}

最后

有很多小伙伴不知道学习哪些鸿蒙开发技术?不知道需要重点掌握哪些鸿蒙应用开发知识点?而且学习时频繁踩坑,最终浪费大量时间。所以有一份实用的鸿蒙(HarmonyOS NEXT)资料用来跟着学习是非常有必要的。 

这份鸿蒙(HarmonyOS NEXT)资料包含了鸿蒙开发必掌握的核心知识要点,内容包含了ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony南向开发、鸿蒙项目实战等等)鸿蒙(HarmonyOS NEXT)技术知识点。

希望这一份鸿蒙学习资料能够给大家带来帮助,有需要的小伙伴自行领取,限时开源,先到先得~无套路领取!!

获取这份完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料

鸿蒙(HarmonyOS NEXT)最新学习路线

 

  •  HarmonOS基础技能

  • HarmonOS就业必备技能 
  •  HarmonOS多媒体技术

  • 鸿蒙NaPi组件进阶

  • HarmonOS高级技能

  • 初识HarmonOS内核 
  • 实战就业级设备开发

有了路线图,怎么能没有学习资料呢,小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙(OpenHarmony )学习手册(共计1236页)鸿蒙(OpenHarmony )开发入门教学视频,内容包含:ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。

获取以上完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料

《鸿蒙 (OpenHarmony)开发入门教学视频》

《鸿蒙生态应用开发V2.0白皮书》

图片

《鸿蒙 (OpenHarmony)开发基础到实战手册》

OpenHarmony北向、南向开发环境搭建

图片

 《鸿蒙开发基础》

  • ArkTS语言
  • 安装DevEco Studio
  • 运用你的第一个ArkTS应用
  • ArkUI声明式UI开发
  • .……

图片

 《鸿蒙开发进阶》

  • Stage模型入门
  • 网络管理
  • 数据管理
  • 电话服务
  • 分布式应用开发
  • 通知与窗口管理
  • 多媒体技术
  • 安全技能
  • 任务管理
  • WebGL
  • 国际化开发
  • 应用测试
  • DFX面向未来设计
  • 鸿蒙系统移植和裁剪定制
  • ……

图片

《鸿蒙进阶实战》

  • ArkTS实践
  • UIAbility应用
  • 网络案例
  • ……

图片

 获取以上完整鸿蒙HarmonyOS学习资料,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料

总结

总的来说,华为鸿蒙不再兼容安卓,对中年程序员来说是一个挑战,也是一个机会。只有积极应对变化,不断学习和提升自己,他们才能在这个变革的时代中立于不败之地。 

  • 16
    点赞
  • 25
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值