@ohos.arkui.componentUtils (componentUtils)

The componentUtils module provides API for obtaining the coordinates and size of the drawing area of a component.

NOTE

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

The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see UIContext.

Since API version 10, you can use the getComponentUtils API in UIContext to obtain the ComponentUtils object associated with the current UI context. For this API to work correctly, call it after the notification indicating completion of component layout is received through @ohos.arkui.inspector (layout callback).

Modules to Import

import componentUtils from '@ohos.arkui.componentUtils'

componentUtils.getRectangleById

getRectangleById(id: string): ComponentInfo

Obtains a ComponentInfo object based on the component ID.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
id string Yes Component ID.

Return value

Type Description
ComponentInfo ComponentInfo object, which provides the size, position, translation, scaling, rotation, and affine matrix information of the component.

Example

import componentUtils from '@ohos.arkui.componentUtils';
let modePosition:componentUtils.ComponentInfo = componentUtils.getRectangleById("onClick");

ComponentInfo

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
size Size Yes Component size.
localOffset Offset Yes Offset of the component relative to the parent component.
windowOffset Offset Yes Offset of the component relative to the window.
screenOffset Offset Yes Offset of the component relative to the screen.
translate TranslateResult Yes Translation of the component.
scale ScaleResult Yes Scaling of the component.
rotate RotateResult Yes Rotation of the component.
transform Matrix4Result Yes Affine matrix of the component, which is a 4 x 4 matrix object created based on the input parameter.

Size

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
width number Yes Component width.
Unit: px
height number Yes Component height.
Unit: px

Offset

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
x number Yes X coordinate.
Unit: px
y number Yes Y coordinate.
Unit: px

TranslateResult

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
x number Yes Translation distance along the x-axis.
Unit: px
y number Yes Translation distance along the y-axis.
Unit: px
z number Yes Translation distance along the z-axis.
Unit: px

ScaleResult

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
x number Yes Scale factor along the x-axis.
Unit: px
y number Yes Scale factor along the y-axis.
Unit: px
z number Yes Scale factor along the z-axis.
Unit: px
centerX number Yes X coordinate of the center point.
Unit: px
centerY number Yes Y coordinate of the center point.
Unit: px

RotateResult

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
x number Yes X coordinate of the rotation vector.
Unit: px
y number Yes Y coordinate of the rotation vector.
Unit: px
z number Yes Z coordinate of the rotation vector.
Unit: px
angle number Yes Rotation angle.
Unit: px
centerX number Yes X coordinate of the center point.
Unit: px
centerY number Yes Y coordinate of the center point.
Unit: px

Matrix4Result

System capability: SystemCapability.ArkUI.ArkUI.Full

Value Range Description
[number,number,number,number,
number,number,number,number,
number,number,number,number,
number,number,number,number]		 A number array whose length is 16 (4 x 4). The unit is px. For details, see 4 x 4 matrix description.

4 x 4 matrix description

Name Type Mandatory Description
m00 number Yes Scale factor along the x-axis. Defaults to 1 for the identity matrix.
m01 number Yes The second value, which is affected by the rotation of the x, y, and z axes.
m02 number Yes The third value, which is affected by the rotation of the x, y, and z axes.
m03 number Yes Meaningless value.
m10 number Yes The fifth value, which is affected by the rotation of the x, y, and z axes.
m11 number Yes Scale factor along the y-axis. Defaults to 1 for the identity matrix.
m12 number Yes The seventh value, which is affected by the rotation of the x, y, and z axes.
m13 number Yes Meaningless value.
m20 number Yes The ninth value, which is affected by the rotation of the x, y, and z axes.
m21 number Yes The tenth value, which is affected by the rotation of the x, y, and z axes.
m22 number Yes Scale factor along the z-axis. Defaults to 1 for the identity matrix.
m23 number Yes Meaningless value.
m30 number Yes Translation value of the x-axis, in px. Defaults to 0 for the unit matrix.
m31 number Yes Translation value of the y-axis, in px. The default value is 0 for the identity matrix.
m32 number Yes Translation value of the z-axis, in px. The default value is 0 for the identity matrix.
m33 number Yes Valid in homogeneous coordinates, presenting the perspective projection effect.

Example

import matrix4 from '@ohos.matrix4';
import componentUtils from '@ohos.arkui.componentUtils';

@Entry
@Component
struct Utils {
@State x: number = 120;
@State y: number = 10;
@State z: number = 100;
@State value: string = '';
private matrix1 = matrix4.identity().translate({ x: this.x, y: this.y, z: this.z });

build() {
  Column() {
    Image($r("app.media.icon"))
      .transform(this.matrix1)
      .translate({ x: 100, y: 10, z: 50 })
      .scale({ x: 2, y: 0.5, z: 1 })
      .rotate({
        x: 1,
        y: 1,
        z: 1,
        centerX: '50%',
        centerY: '50%',
        angle: 300
      })
      .width("40%")
      .height(100)
      .key("image_01")
    Button() {
      Text('getRectangleById').fontSize(40).fontWeight(FontWeight.Bold);
    }.margin(20)
    .onClick(() => {
      this.value = JSON.stringify(componentUtils.getRectangleById("image_01"))
    }).id('onClick')
    Text(this.value)
      .margin(20)
      .width(300)
      .height(400)
      .borderWidth(2)
  }
}
}