openharmony 鸿蒙 js-apis-matrix4

2025-06-12 浏览 (1)

@ohos.matrix4 (Matrix Transformation)

The matrix4 module provides APIs for matrix transformation. You can use these APIs to translate, rotate, and scale images.

NOTE

The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { matrix4 } from '@kit.ArkUI';

matrix4.init

init(options: [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number]): Matrix4Transit

Matrix constructor, which is used to create a 4 x 4 matrix with the input parameters. Column-major order is used.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
options[number,number,number,number,
number,number,number,number,
number,number,number,number,
number,number,number,number]		YesA number array whose length is 16 (4 x 4). For details, see 4 x 4 matrix description.
Value range of each number: (-∞, +∞)
Default value:
[1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1]

Return value

TypeDescription
Matrix4Transit4 x 4 matrix object created based on the input parameters.

4 x 4 matrix description

NameTypeMandatoryDescription
m00numberYesScaling value of the x-axis. The default value is 1 for the identity matrix.
m01numberYesThe second value, which is affected by the rotation or tilt of the x, y, and z axes.
m02numberYesThe third value, which is affected by the rotation of the x, y, and z axes.
m03numberYesThe fourth value, which is affected by perspective projection.
m10numberYesThe fifth value, which is affected by the rotation or tilt of the x, y, and z axes.
m11numberYesScaling value of the y-axis. The default value is 1 for the identity matrix.
m12numberYesThe seventh value, which is affected by the rotation of the x, y, and z axes.
m13numberYesThe eighth value, which is affected by perspective projection.
m20numberYesThe ninth value, which is affected by the rotation of the x, y, and z axes.
m21numberYesThe tenth value, which is affected by the rotation of the x, y, and z axes.
m22numberYesScaling value of the z-axis. The default value is 1 for the identity matrix.
m23numberYesThe 12th value, which is affected by perspective projection.
m30numberYesTranslation value of the x-axis, in px. The default value is 0 for the identity matrix.
m31numberYesTranslation value of the y-axis, in px. The default value is 0 for the identity matrix.
m32numberYesTranslation value of the z-axis, in px. The default value is 0 for the identity matrix.
m33numberYesValid in homogeneous coordinates, presenting the perspective projection effect.

Example

import { matrix4 } from '@kit.ArkUI';

// Create a 4 x 4 matrix.
let matrix = matrix4.init(
  [1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0])

@Entry
@Component
struct Tests {
  build() {
    Column() {
      Image($r("app.media.zh"))
        .width("40%")
        .height(100)
        .transform(matrix)
    }
  }
}

matrix4.identity

identity(): Matrix4Transit

Constructs an identity matrix.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

TypeDescription
Matrix4TransitIdentity matrix object.

Example

// The effect of matrix 1 is the same as that of matrix 2.
import { matrix4 } from '@kit.ArkUI';

let matrix1 = matrix4.init(
  [1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0])
let matrix2 = matrix4.identity()

@Entry
@Component
struct Tests {
  build() {
    Column() {
      Image($r("app.media.zh"))
        .width("40%")
        .height(100)
        .transform(matrix1)
      Image($r("app.media.zh"))
        .width("40%")
        .height(100)
        .margin({ top: 150 })
        .transform(matrix2)
    }
  }
}

Matrix4Transit

Implements a Matrix4Transit object.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

copy

copy(): Matrix4Transit

Copies this matrix object.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

TypeDescription
Matrix4TransitCopy object of the current matrix.

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private matrix1 = matrix4.identity().scale({ x: 1.5 })
  private matrix2 = this.matrix1.copy().translate({ x: 200 })
  imageSize: Length = '300px'

  build() {
    Column({ space: "50px" }) {
      Image($r("app.media.testImage"))
        .width(this.imageSize)
        .height(this.imageSize)
      Image($r("app.media.testImage"))
        .width(this.imageSize)
        .height(this.imageSize)
        .transform(this.matrix1)
      Image($r("app.media.testImage"))
        .width(this.imageSize)
        .height(this.imageSize)
        .transform(this.matrix2)
    }.alignItems(HorizontalAlign.Center)
    .height('100%').width("100%")
    .justifyContent(FlexAlign.Center)
  }
}

en-us_image_0000001219744181

combine

combine(options: Matrix4Transit): Matrix4Transit

Combines the effects of two matrices to generate a new matrix object. The original matrix that calls this API will be changed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsMatrix4TransitYesMatrix object to be combined.

Return value

TypeDescription
Matrix4TransitObject after matrix combination.

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private matrix1 = matrix4.identity().translate({ x: 200 })
  private matrix2 = matrix4.identity().scale({ x: 2 })

  build() {
    Column() {
      // Before matrix transformation
      Image($r("app.media.icon"))
        .width("40%")
        .height(100)
        .margin({ top: 50 })
      // Translate the x-axis by 200px, and then scale it twice to obtain the resultant matrix.
      Image($r("app.media.icon"))
        .transform(this.matrix1.copy().combine(this.matrix2))
        .width("40%")
        .height(100)
        .margin({ top: 50 })
    }
  }
}

en-us_image_0000001118642902

invert

invert(): Matrix4Transit

Inverts this matrix object. The original matrix that calls this API will be changed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

TypeDescription
Matrix4TransitInverse matrix object of the current matrix.

Example

import { matrix4 } from '@kit.ArkUI';

// The effect of matrix 1 (width scaled up by 2x) is opposite to that of matrix 2 (width scaled down by 2x).
let matrix1 = matrix4.identity().scale({ x: 2 })
let matrix2 = matrix1.copy().invert()

@Entry
@Component
struct Tests {
  build() {
    Column() {
      Image($r("app.media.zh"))
        .width(200)
        .height(100)
        .transform(matrix1)
        .margin({ top: 100 })
      Image($r("app.media.zh"))
        .width(200)
        .height(100)
        .margin({ top: 150 })
        .transform(matrix2)
    }
  }
}

translate

translate(options: TranslateOption): Matrix4Transit

Translates this matrix object along the x, y, and z axes. The original matrix that calls this API will be changed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsTranslateOptionYesTranslation configuration.

Return value

TypeDescription
Matrix4TransitMatrix object after the translation.

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 })

  build() {
    Column() {
      Image($r("app.media.bg1")).transform(this.matrix1)
        .width("40%")
        .height(100)
    }
  }
}

en-us_image_0000001219662645

scale

scale(options: ScaleOption): Matrix4Transit

Scales this matrix object along the x, y, and z axes. The matrix that calls this API will be changed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsScaleOptionYesScaling configuration.

Return value

TypeDescription
Matrix4TransitMatrix object after the scaling.

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private matrix1 = matrix4.identity()
    .scale({
      x: 2,
      y: 3,
      z: 4,
      centerX: 50,
      centerY: 50
    })

  build() {
    Column() {
      Image($r("app.media.testImage")).transform(this.matrix1)
        .width("300px")
        .height("300px")
    }.width("100%").height("100%").justifyContent(FlexAlign.Center)
  }
}

en-us_image_0000001219864131

skew12+

skew(x: number, y: number): Matrix4Transit

Skews this matrix object along the x and y axes. The matrix that calls this API will be changed.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
xnumberYesAmount of skewing on the x-axis.
ynumberYesAmount of skewing on the y-axis.

Return value

TypeDescription
Matrix4TransitMatrix object after the skewing.

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private matrix1 = matrix4.identity().skew(2, 3)

  build() {
    Column() {
      Image($r("app.media.bg1")).transform(this.matrix1)
        .height(100)
        .margin({
          top: 300
        })
    }
    .width("100%")
    .height("100%")
  }
}

en-us_image_0000001219864132

rotate

rotate(options: RotateOption): Matrix4Transit

Rotates this matrix object along the x, y, and z axes. The matrix that calls this API will be changed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsRotateOptionYesRotation configuration.

Return value

TypeDescription
Matrix4TransitMatrix object after the rotation.

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private matrix1 = matrix4.identity()
    .rotate({
      x: 1,
      y: 1,
      z: 2,
      angle: 30
    })

  build() {
    Column() {
      Image($r("app.media.bg1")).transform(this.matrix1)
        .width("40%")
        .height(100)
    }.width("100%").margin({ top: 50 })
  }
}

en-us_image_0000001174422898

transformPoint

transformPoint(options: [number, number]): [number, number]

Applies the current transformation effect to a coordinate point.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
options[number, number]YesPoint to be transformed.

Return value

TypeDescription
[number, number]Point object after matrix transformation

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private originPoint: number[] = [50, 50]
  private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 })
  private transformPoint = this.matrix_1.transformPoint([this.originPoint[0], this.originPoint[1]])
  private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] })

  build() {
    Column() {
      Text(`Coordinates before matrix transformation: [${this.originPoint}]`)
        .fontSize(16)
      Image($r("app.media.image"))
        .width('600px')
        .height('300px')
        .margin({ top: 50 })
      Text(`Coordinates after matrix transformation: [${this.transformPoint}]`)
        .fontSize(16)
        .margin({ top: 100 })
      Image($r("app.media.image"))
        .width('600px')
        .height('300px')
        .margin({ top: 50 })
        .transform(this.matrix_2)
    }.width("100%").padding(50)
  }
}

en-us_image_0000001219864133

setPolyToPoly12+

setPolyToPoly(options: PolyToPolyOptions): Matrix4Transit

Maps the vertex coordinates of a polygon to those of another polygon.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsPolyToPolyOptionsYesParameters for mapping.

Return value

TypeDescription
Matrix4TransitMatrix object after the mapping.

NOTE

This API must be used with scale({centerX:0,centerY:0,x:1}) to ensure that the transformation is centered at the upper left corner of the component.

Example

import { matrix4 } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  private matrix1 = matrix4.identity().setPolyToPoly({
    src: [{ x: 0, y: 0 }, { x: 500, y: 0 }, { x: 0, y: 500 }, { x: 500, y: 500 }],
    dst: [{ x: 0, y: 0 }, { x: 500, y: 0 }, { x: 0, y: 500 }, { x: 750, y: 1000 }], pointCount: 4
  })

  build() {
    Stack() {
      Column().backgroundColor(Color.Blue)
        .width('500px')
        .height('500px')
      Image($r('app.media.transition_image1'))
        .scale({ centerX: 0, centerY: 0, x: 1 })
        .transform(this.matrix1)
        .width('500px')
        .height('500px')
    }.width("100%").height("100%").opacity(0.5)
  }
}

en-us_image_0000001174422898

TranslateOption

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
xnumberNoTranslation distance along the x-axis.
Unit: px
Default value: 0
Value range: (-∞, +∞)
ynumberNoTranslation distance along the y-axis.
Unit: px
Default value: 0
Value range: (-∞, +∞)
znumberNoTranslation distance along the z-axis.
Unit: px
Default value: 0
Value range: (-∞, +∞)

ScaleOption

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
xnumberNoScaling multiple along the x-axis. x > 1: The image is scaled up along the x-axis.
0 < x < 1: The image is scaled down along the x-axis.
x < 0: The image is scaled in the reverse direction of the x-axis.
Default value: 1
Value range: (-∞, +∞)
ynumberNoScaling multiple along the y-axis. y > 1: The image is scaled up along the y-axis.
0 < y < 1: The image is scaled down along the y-axis.
y < 0: The image is scaled in the reverse direction of the y-axis.
Default value: 1
Value range: (-∞, +∞)
znumberNoScaling multiple along the z-axis. z > 1: The image is scaled up along the z-axis.
0 < z < 1: The image is scaled down along the z-axis.
z < 0: The image is scaled in the reverse direction of the z-axis.
Default value: 1
Value range: (-∞, +∞)
centerXnumberNoX coordinate of the center point.
Unit: px
Default value: X-coordinate of the component center
Value range: (-∞, +∞)
centerYnumberNoY coordinate of the center point.
Unit: px
Default value: Y-coordinate of the component center
Value range: (-∞, +∞)

RotateOption

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
xnumberNoX coordinate of the rotation axis vector.
Default value: 0
Value range: (-∞, +∞)
ynumberNoY coordinate of the rotation axis vector.
Default value: 0
Value range: (-∞, +∞)
znumberNoZ coordinate of the rotation axis vector.
Default value: 0
Value range: (-∞, +∞)
NOTE
The rotation axis vector is valid only when at least one of x, y, and z is not 0.
anglenumberNoRotation angle.
Default value: 0
centerXnumberNoAdditional x-axis offset of the transformation center relative to the component's anchor.
Unit: px
Default value: 0
NOTE
The value 0 indicates that the transformation center coincides with the component's x-axis anchor. For details about the implementation, see Example 3: Implementing Rotation Around a Center Point.
centerYnumberNoAdditional y-axis offset of the transformation center relative to the component's anchor.
Unit: px
Default value: 0
NOTE
The value 0 indicates that the transformation center coincides with the component's y-axis anchor. For details about the implementation, see Example 3: Implementing Rotation Around a Center Point.

PolyToPolyOptions12+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
srcArray<Point>YesCoordinates of the source point.
srcIndexnumberNoStart index of the source point coordinates.
Default value: 0.
Value range: [0, +∞).
dstArray<Point>YesCoordinates of the destination point.
dstIndexnumberNoStart index of the destination point coordinates.
Default value: 0.
Value range: [0, +∞).
pointCountnumberNoNumber of used points.
Default value: src.length/2.
Value range: [0, +∞).

Point12+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
xnumberYesX-coordinate.
Value range: (-∞, +∞)
ynumberYesY-coordinate.
Value range: (-∞, +∞)

matrix4.copy(deprecated)

copy(): Matrix4Transit

Copies this matrix object.

NOTE

This API is deprecated since API version 10. You are advised to use Matrix4Transit.copy instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

TypeDescription
Matrix4TransitCopy object of the current matrix.

Example

// xxx.ets
import { matrix4 } from '@kit.ArkUI';

@Entry
@Component
struct Test {
  private matrix1 = matrix4.identity().translate({ x: 100 })
  // Perform the scale operation on the copy matrix of matrix1, which does not affect matrix1.
  private matrix2 = this.matrix1.copy().scale({ x: 2 })

  build() {
    Column() {
      Image($r("app.media.bg1"))
        .width("40%")
        .height(100)
        .transform(this.matrix1)
      Image($r("app.media.bg2"))
        .width("40%")
        .height(100)
        .margin({ top: 50 })
        .transform(this.matrix2)
    }
  }
}

en-us_image_0000001219744181

matrix4.invert(deprecated)

invert(): Matrix4Transit

Inverts this matrix object.

NOTE

This API is deprecated since API version 10. You are advised to use Matrix4Transit.invert instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

TypeDescription
Matrix4TransitInverse matrix object of the current matrix.

matrix4.combine(deprecated)

combine(options: Matrix4Transit): Matrix4Transit

Combines the effects of two matrices to generate a new matrix object.

NOTE

This API is deprecated since API version 10. You are advised to use Matrix4Transit.combine instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsMatrix4TransitYesMatrix object to be combined.

Return value

TypeDescription
Matrix4TransitMatrix object after combination.

matrix4.translate(deprecated)

translate(options: TranslateOption): Matrix4Transit

Translates this matrix object along the x, y, and z axes.

NOTE

This API is deprecated since API version 10. You are advised to use Matrix4Transit.translate instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsTranslateOptionYesTranslation configuration.

Return value

TypeDescription
Matrix4TransitMatrix object after translation.

matrix4.scale(deprecated)

scale(options: ScaleOption): Matrix4Transit

Scales this matrix object along the x, y, and z axes.

NOTE

This API is deprecated since API version 10. You are advised to use Matrix4Transit.scale instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsScaleOptionYesScaling configuration.

Return value

TypeDescription
Matrix4TransitMatrix object after scaling.

matrix4.rotate(deprecated)

rotate(options: RotateOption): Matrix4Transit

Rotates this matrix object along the x, y, and z axes.

NOTE

This API is deprecated since API version 10. You are advised to use Matrix4Transit.rotate instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
optionsRotateOptionYesRotation configuration.

Return value

TypeDescription
Matrix4TransitMatrix object after rotation.

matrix4.transformPoint(deprecated)

transformPoint(options: [number, number]): [number, number]

Applies the current transformation effect to a coordinate point.

NOTE

This API is deprecated since API version 10. You are advised to use Matrix4Transit.transformPoint instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
options[number, number]YesPoint to be transformed.

Return value

TypeDescription
[number, number]Point object after matrix transformation

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkUI

harmony 鸿蒙ARKUI_TextPickerCascadeRangeContent

harmony 鸿蒙ARKUI_TextPickerRangeContent

harmony 鸿蒙ArkUI_AnimateCompleteCallback

harmony 鸿蒙ArkUI_AttributeItem

harmony 鸿蒙ArkUI_ColorStop

harmony 鸿蒙ArkUI_ContextCallback

harmony 鸿蒙ArkUI_EventModule

harmony 鸿蒙ArkUI_ExpectedFrameRateRange

harmony 鸿蒙ArkUI_IntOffset

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/yByeQ8