鸿蒙5.0开发进阶：UI框架-ArkTS组件（Matrix2D）

矩阵对象，可以对矩阵进行缩放、旋转、平移等变换。

懂你的大海

1060人浏览 · 2025-01-23 15:37:56

懂你的大海 · 2025-01-23 15:37:56 发布

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

Matrix2D

矩阵对象，可以对矩阵进行缩放、旋转、平移等变换。

说明

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

接口

Matrix2D(unit?: LengthMetricsUnit)

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

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

参数：

参数名	类型	必填	说明
unit12+	LengthMetricsUnit	否	用来配置Matrix2D对象的单位模式，配置后无法动态更改，配置方法同CanvasRenderingContext2D。默认值：DEFAULT。

参数名

类型

必填

说明

unit12+

LengthMetricsUnit

否

用来配置Matrix2D对象的单位模式，配置后无法动态更改，配置方法同CanvasRenderingContext2D。

默认值：DEFAULT。

属性

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

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

名称	类型	只读	可选	说明
scaleX	number	否	是	水平缩放系数。
scaleY	number	否	是	垂直缩放系数。
rotateX	number	否	是	水平倾斜系数。
rotateY	number	否	是	垂直倾斜系数。
translateX	number	否	是	水平平移距离。默认单位：vp。
translateY	number	否	是	垂直平移距离。默认单位：vp。

说明

可使用px2vp接口进行单位转换。

示例：

// xxx.ets
@Entry
@Component
struct Parameter {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private matrix : Matrix2D = new Matrix2D()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.context)
        .width('240vp')
        .height('180vp')
        .backgroundColor('#ffff00')
        .onReady(() =>{
          this.context.fillRect(100,20,50,50)
          this.matrix.scaleX = 1
          this.matrix.scaleY = 1
          this.matrix.rotateX = -0.5
          this.matrix.rotateY = 0.5
          this.matrix.translateX = 10
          this.matrix.translateY = 10
          this.context.setTransform(this.matrix)
          this.context.fillRect(100,20,50,50)
        })
    }
    .width('100%')
    .height('100%')
  }
}

方法

identity

identity(): Matrix2D

创建一个单位矩阵。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

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

返回值：

类型	说明
Matrix2D	单位矩阵。

示例：

// xxx.ets
@Entry
@Component
struct Identity {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private matrix : Matrix2D = new Matrix2D()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.context)
        .width('240vp')
        .height('180vp')
        .backgroundColor('#ffff00')
        .onReady(() =>{
          this.context.fillRect(100,20,50,50)
          this.matrix = this.matrix.identity()
          this.context.setTransform(this.matrix)
          this.context.fillRect(100,100,50,50)
        })
    }
    .width('100%')
    .height('100%')
  }
}

invert

invert(): Matrix2D

得到当前矩阵的逆矩阵。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

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

返回值：

类型	说明
Matrix2D	逆矩阵结果。

示例：

// xxx.ets
@Entry
@Component
struct Invert {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private matrix : Matrix2D = new Matrix2D()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.context)
        .width('240vp')
        .height('180vp')
        .backgroundColor('#ffff00')
        .onReady(() =>{
          this.context.fillRect(100,110,50,50)
          this.matrix.scaleX = 1
          this.matrix.scaleY = 1
          this.matrix.rotateX = -0.5
          this.matrix.rotateY = 0.5
          this.matrix.translateX = 10
          this.matrix.translateY = 10
          this.matrix.invert()
          this.context.setTransform(this.matrix)
          this.context.fillRect(100,110,50,50)
        })
    }
    .width('100%')
    .height('100%')
  }
}

multiply(deprecated)

multiply(other?: Matrix2D): Matrix2D

当前矩阵与目标矩阵相乘。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。该接口为空接口。

该接口从API version 10开始废弃，且无实际绘制效果。

参数：

参数名	类型	必填	说明
other	Matrix2D	否	目标矩阵。默认值：null。

参数名

类型

必填

说明

other

Matrix2D

否

目标矩阵。

默认值：null。

返回值：

类型	说明
Matrix2D	相乘结果矩阵。

示例：

// xxx.ets
@Entry
@Component
struct Multiply {
  @State message: string = 'Matrix2D Multiply'

  printMatrix(title: string, matrix: Matrix2D) {
    console.log(title)
    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
  }
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
        Button("matrix multiply")
          .onClick(() => {
            let matrix : Matrix2D = new Matrix2D()
            matrix.scaleX = 1
            matrix.scaleY = 1
            matrix.rotateX = 0
            matrix.rotateY = 0
            matrix.translateX = 0
            matrix.translateY = 0
            let other: Matrix2D = new Matrix2D()
            other.scaleX = 2
            other.scaleY = 2
            other.rotateX = 0
            other.rotateY = 0
            other.translateX = 10
            other.translateY = 10
            other.multiply(other)
            this.printMatrix(this.message, matrix)
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

rotate(deprecated)

rotate(rx?: number, ry?: number): Matrix2D

对当前矩阵进行旋转运算。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。该接口为空接口。

该接口从API version 10开始废弃，推荐使用rotate。

参数：

参数名	类型	必填	说明
rx	number	否	旋转点的水平方向坐标。默认单位：vp。
ry	number	否	旋转点的垂直方向坐标。默认单位：vp。

参数名

类型

必填

说明

number

否

旋转点的水平方向坐标。

默认单位：vp。

number

否

旋转点的垂直方向坐标。

默认单位：vp。

返回值：

类型	说明
Matrix2D	旋转后结果矩阵对象。

示例：

// xxx.ets
@Entry
@Component
struct Rotate {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private matrix : Matrix2D = new Matrix2D()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.context)
        .width('240vp')
        .height('180vp')
        .backgroundColor('#ffff00')
        .onReady(() =>{
          this.context.fillRect(50,110,50,50)
          this.matrix.scaleX = 1
          this.matrix.scaleY = 1
          this.matrix.rotateX = -0.5
          this.matrix.rotateY = 0.5
          this.matrix.translateX = 10
          this.matrix.translateY = 10
          this.matrix.rotate(5, 5)
          this.context.setTransform(this.matrix)
          this.context.fillRect(50,110,50,50)
        })
    }
    .width('100%')
    .height('100%')
  }
}

rotate10+

rotate(degree: number, rx?: number, ry?: number): Matrix2D

以旋转点为中心、对当前矩阵进行右乘旋转运算。

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

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

参数：

参数名	类型	必填	说明
degree	number	是	旋转角度。顺时针方向为正角度，可以通过 degree * Math.PI / 180 将角度转换为弧度值。默认单位：弧度。
rx	number	否	旋转点的水平方向坐标。默认单位：vp。默认值：0。
ry	number	否	旋转点的垂直方向坐标。默认单位：vp。默认值：0。

参数名

类型

必填

说明

degree

number

是

旋转角度。顺时针方向为正角度，可以通过 degree * Math.PI / 180 将角度转换为弧度值。

默认单位：弧度。

number

否

旋转点的水平方向坐标。

默认单位：vp。

默认值：0。

number

否

旋转点的垂直方向坐标。

默认单位：vp。

默认值：0。

返回值：

类型	说明
Matrix2D	旋转后结果矩阵对象。

示例：

// xxx.ets
@Entry
@Component
struct Rotate {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private matrix : Matrix2D = new Matrix2D()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.context)
        .width('240vp')
        .height('180vp')
        .backgroundColor('#ffff00')
        .onReady(() =>{
          this.context.fillRect(60,80,50,50)
          this.matrix.scaleX = 1
          this.matrix.scaleY = 1
          this.matrix.rotateX = -0.5
          this.matrix.rotateY = 0.5
          this.matrix.translateX = 10
          this.matrix.translateY = 10
          this.matrix.rotate(-60 * Math.PI / 180, 5, 5)
          this.context.setTransform(this.matrix)
          this.context.fillRect(60,80,50,50)
        })
    }
    .width('100%')
    .height('100%')
  }
}

translate

translate(tx?: number, ty?: number): Matrix2D

对当前矩阵进行左乘平移运算。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

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

参数：

参数名	类型	必填	说明
tx	number	否	水平方向平移距离。默认单位：vp。默认值：0。
ty	number	否	垂直方向平移距离。默认单位：vp。默认值：0。

参数名

类型

必填

说明

number

否

水平方向平移距离。

默认单位：vp。

默认值：0。

number

否

垂直方向平移距离。

默认单位：vp。

默认值：0。

返回值：

类型	说明
Matrix2D	平移后结果矩阵对象。

示例：

// xxx.ets
@Entry
@Component
struct Translate {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private matrix : Matrix2D = new Matrix2D()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.context)
        .width('240vp')
        .height('180vp')
        .backgroundColor('#ffff00')
        .onReady(() =>{
          this.context.fillRect(40,20,50,50)
          this.matrix.scaleX = 1
          this.matrix.scaleY = 1
          this.matrix.rotateX = 0
          this.matrix.rotateY = 0
          this.matrix.translateX = 0
          this.matrix.translateY = 0
          this.matrix.translate(100, 100)
          this.context.setTransform(this.matrix)
          this.context.fillRect(40,20,50,50)
        })
    }
    .width('100%')
    .height('100%')
  }
}

scale

scale(sx?: number, sy?: number): Matrix2D

对当前矩阵进行右乘缩放运算。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

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

参数：

参数	类型	必填	描述
sx	number	否	水平缩放比例系数。默认值：1.0。
sy	number	否	垂直缩放比例系数。默认值：1.0。

参数

类型

必填

描述

number

否

水平缩放比例系数。

默认值：1.0。

number

否

垂直缩放比例系数。

默认值：1.0。

返回值：

类型	说明
Matrix2D	缩放结果矩阵对象。

示例：

// xxx.ets
@Entry
@Component
struct Scale {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private matrix : Matrix2D = new Matrix2D()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.context)
        .width('240vp')
        .height('180vp')
        .backgroundColor('#ffff00')
        .onReady(() =>{
          this.context.fillRect(120,70,50,50)
          this.matrix.scaleX = 1
          this.matrix.scaleY = 1
          this.matrix.rotateX = -0.5
          this.matrix.rotateY = 0.5
          this.matrix.translateX = 10
          this.matrix.translateY = 10
          this.matrix.scale(0.5, 0.5)
          this.context.setTransform(this.matrix)
          this.context.fillRect(120,70,50,50)
        })
    }
    .width('100%')
    .height('100%')
  }
}

HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

【新手教程】HarmonyOS组件模板通关攻略（通过DevEco Studio插件快速集成模板&组件）

点击顶部菜单栏中的“File（文件）”> “New...（新建）”> “Create Project from Template Market（从模板市场创建项目）”，进入模板市场界面；找到目标组件后，点击组件详情页卡片中的“Integrate source code”（集成源码）或“Integrate SDK”（集成SDK）按钮，即可将组件添加到您的项目中。启动 IDE，点击顶部菜单栏中的“Fi

HarmonyOS开发者社区

【案例+1】HarmonyOS官方模板优秀案例（第8期：阅读行业 · 电子书）

在commons/lib_common/src/main/ets/httprequest/HttpRequest.ets文件中将云侧开发者自定义的数据结构转换为端侧数据结构。将commons/lib_common/src/main/ets/httprequest/HttpRequestApi.ets文件中的mock接口替换为真实的服务器接口。中国移动一键登录SDK/易盾一键登录SDK/创蓝闪验/极

HarmonyOS开发者社区

【HarmonyOS-媒体技术-Media Kit】HarmonyOS 音视频开发全栈解析

Media Kit 让开发者可以调用系统的音视频能力，涵盖播放、录制、录屏、元数据提取与转码六大核心功能模块，支撑系统应用与第三方应用在视频播放、内容创作、教学录屏、直播互动等典型场景下的音视频处理需求。AVMetadataExtractor 用于从音视频资源中提取元数据，如标题、艺术家、专辑、时长等信息，从视频中提取指定时间点的画面，生成缩略图。AVRecorder 可实现音频、视频、音视频混合