鸿蒙5.0版开发：ArkTS基础组件（XComponent）

最新推荐文章于 2024-10-02 09:54:20 发布
最新推荐文章于 2024-10-02 09:54:20 发布
阅读量776 收藏 10
点赞数 29
分类专栏： 鸿蒙5.0 ArkUI ArkTS 文章标签： harmonyos 华为 android 鸿蒙 前端
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_69424697/article/details/142444886
版权
鸿蒙5.0 同时被 3 个专栏收录
94 篇文章 0 订阅
订阅专栏
ArkUI
94 篇文章 0 订阅
订阅专栏
ArkTS
90 篇文章 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的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侧事件接口。

仅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替代。

参数:

参数名参数类型必填描述
surfaceWidthnumber是XComponent持有Surface的宽度。
surfaceHeightnumber是XComponent持有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开始，该接口支持在原子化服务中使用。

参数:

参数名参数类型必填描述
rectSurfaceRect是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开始，该接口支持在原子化服务中使用。

返回值:

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

名称类型必填说明
offsetXnumber否Surface显示区域相对于XComponent组件左上角的x轴坐标，单位：px。
offsetYnumber否Surface显示区域相对于XComponent组件左上角的y轴坐标，单位：px。
surfaceWidthnumber是Surface显示区域的宽度，单位：px。
surfaceHeightnumber是Surface显示区域的高度，单位：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分析是否成功执行。

错误码：

以下错误码介绍

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

名称类型必填说明
lockboolean否Surface在屏幕旋转时是否锁定方向，未设置时默认取值为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 })
  }
}

示例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%")
  }
}

示例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%")
  }
}

看完三件事❤️

  • 如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：
  • 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。
  • 关注作者，不定期分享原创知识。
  • 同时可以期待后续文章ing🚀。 
星星不闪包退1
关注
专栏目录
鸿蒙5.0版开发：ArkTS基础组件（TextArea）
m0_69424697的博客
09-21 998
多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。
鸿蒙5.0版开发：ArkTS基础组件（TextInput）
m0_69424697的博客
09-21 1020
单行文本输入框组件。
鸿蒙5.0版开发：ArkTS组件通用属性（布局约束）
m0_73088370的博客
08-27 864
通过组件的宽高比和显示优先级约束组件显示效果。
鸿蒙5.0版开发：ArkTS基础组件（Search）
m0_69424697的博客
09-19 1191
搜索框组件，适用于浏览器的搜索内容输入框等应用场景。
鸿蒙5.0版开发：ArkTS组件-基础组件（Gauge）
m0_69424697的博客
09-13 837
数据量规图表组件，用于将数据展示为环形图表。
鸿蒙5.0版开发：ArkTS组件（触摸事件）
m0_73088370的博客
08-23 1029
当手指在组件上按下、滑动、抬起时触发。
鸿蒙5.0版开发：ArkTS组件基础手势（PanGesture）
m0_69424697的博客
09-10 855
拖动手势事件，当滑动的最小距离超过设定的最小值时触发拖动手势事件。
鸿蒙5.0版开发：ArkTS组件（点击事件）
m0_73088370的博客
08-23 559
组件被点击时触发的事件。
鸿蒙5.0版开发：ArkTS组件-基础组件（Image）
m0_69424697的博客
09-13 897
Image为图片组件，常用于在应用中显示图片。
鸿蒙ArkTS实战开发-Native XComponent组件的使用
2401_82546228的博客
03-22 1756
本篇Codelab主要介绍如何使用XComponent组件调用NAPI来创建EGL/GLES环境，实现在主页面绘制一个正方形，并可以改变正方形的颜色。本篇CodeLab使用Native C++模板创建。
HarmonyOS鸿蒙开发指南:基于ArkTS开发 视频播放开发指导
sybh的博客
01-10 1081
视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。图1视频播放状态机图2视频播放零层图*注意：视频播放需要显示、音频、编解码等硬件能力。三方应用从Xcomponent组件获取surfaceID。三方应用把surfaceID传递给VideoPlayer JS。媒体服务把帧数据flush给surface buffer。
鸿蒙开发实战项目(六十四):Native XComponent组件的使用（ArkTS）
sybh的博客
01-29 748
本篇Codelab主要介绍如何使用XComponent组件调用NAPI来创建EGL/GLES环境，实现在主页面绘制一个正方形，并可以改变正方形的颜色。本篇Codelab使用Native C++模板创建。如图所示，点击绘制矩形按钮，XComponent组件绘制区域中渲染出一个正方形，点击绘制区域，正方形显示另一种颜色，点击绘制矩形按钮正方形还原至初始绘制的颜色。
【鸿蒙】基于ArkTS基础组件封装的标题栏(TitleBar)组件
2401_82772199的博客
02-28 1195
TitleBar 是基于 ArkTS 封装的通用、功能全面的自定义标题栏框架。
HarmonyOS鸿蒙开发指南:基于ArkTS的声明式开发范式 声明式UI开发实例 绘图与动画
sybh的博客
01-07 987
除绘制基础几何图形，开发者还可以使用Path组件来绘制自定义的路线，下面进行绘制应用的Logo图案。在pages文件夹下创建新的页面Logo.ets。Logo.ets中删掉模板代码，创建Logo Component。@Entry@Componentbuild() {创建Flex组件为根节点，宽高设置为100%，设置其在主轴方向和交叉轴方向的对齐方式都为Center，创建Shape组件为Flex子组件。Shape组件是所有绘制组件的父组件。
鸿蒙ArkUI实战开发-主打自研语言及框架
最新发布
zzlyx99的专栏
10-02 673
ArkUI 是 HarmonyOS 的声明式 UI 开发框架，而 ArkUI-X 是基于 ArkUI 框架扩展而来的跨平台开发框架。ArkUI-X 支持 HarmonyOS、OpenHarmony、Android 和 iOS 平台，允许开发者使用一套代码构建支持多平台的应用程序。
【鸿蒙】HarmonyOS NEXT应用开发快速入门教程之布局篇（上）
pixle的博客
09-27 1249
HarmonyOS NEXT（鸿蒙应用）开发快速入门教程之布局篇，基于HarmonyOS NEXT Beta1版本（api 12）讲解。本文将从前端开发者角度来学习鸿蒙的布局语法，通过类比鸿蒙布局和web css布局相似之处，帮助大家快速掌握鸿蒙布局开发。
鸿蒙NEXT开发-自定义构建函数（基于最新api12稳定版）
qq_56760790的博客
09-28 1018
鸿蒙自定义构建函数的学习包含了：构建函数的基本介绍、传参传递、尾随闭包等
HarmonyOS Next应用开发——响应式布局之媒体查询
高心星的专栏
09-27 1065
媒体查询可根据不同设备类型或同设备不同状态修改应用的样式，常用于多屏幕的应用适配。语法规则包括媒体类型（media-type）、媒体逻辑操作（media-logic-operations）（经常省略）和媒体特征（media-feature）。媒体查询条件由媒体类型、逻辑操作符、媒体特征组成，其中媒体类型可省略，逻辑操作符用于连接不同媒体类型与媒体特征，其中，媒体特征要使用“()”包裹且可以有多个。
鸿蒙开发入门： ArkTS语言详解与HelloWorld实践
"移动开发领域的鸿蒙操作系统(HarmonyOS)入门教程，专注于 HelloWorld 示例和 ArkTS 语言的介绍。" 在移动开发领域，HarmonyOS 是华为推出的一款面向全场景的分布式操作系统，旨在打破设备间的界限，实现跨平台、跨...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值