1# @ohos.arkui.componentUtils (componentUtils)
2
3The **componentUtils** module provides API for obtaining the coordinates and size of the drawing area of a component.
4
5> **NOTE**
6>
7> The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.
8>
9> 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](./js-apis-arkui-UIContext.md#uicontext).
10>
11> Since API version 10, you can use the [getComponentUtils](./js-apis-arkui-UIContext.md#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)](js-apis-arkui-inspector.md).
12
13## Modules to Import
14
15```ts
16import { componentUtils } from '@kit.ArkUI';
17```
18## componentUtils.getRectangleById
19
20getRectangleById(id: string): ComponentInfo
21
22Obtains a **ComponentInfo** object based on the component ID.
23
24**Atomic service API**: This API can be used in atomic services since API version 11.
25
26**System capability**: SystemCapability.ArkUI.ArkUI.Full
27
28**Parameters**
29
30| Name| Type  | Mandatory| Description      |
31| ------ | ------ | ---- | ---------- |
32| id     | string | Yes  | Component ID.|
33
34**Return value**
35
36| Type  | Description      |
37| ------ | ---------- |
38| [ComponentInfo](#componentinfo) | **ComponentInfo** object, which provides the size, position, translation, scaling, rotation, and affine matrix information of the component.|
39
40**Error codes**
41
42For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
43
44| ID | Error Message               |
45| ------ | ------------------- |
46| 100001 | UI execution context not found. |
47
48**Example**
49
50```ts
51import { componentUtils } from '@kit.ArkUI';
52let modePosition:componentUtils.ComponentInfo = componentUtils.getRectangleById("onClick");
53```
54
55## ComponentInfo
56
57**Atomic service API**: This API can be used in atomic services since API version 11.
58
59**System capability**: SystemCapability.ArkUI.ArkUI.Full
60
61| Name          | Type            | Mandatory          | Description                        |
62| ---------------|------------     | -----------------------------| -----------------------------|
63| size           | [Size](#size) | Yes| Component size.                   |
64| localOffset    | [Offset](#offset) | Yes| Offset of the component relative to the parent component.        |
65| windowOffset   | [Offset](#offset) | Yes| Offset of the component relative to the window.          |
66| screenOffset   | [Offset](#offset) | Yes| Offset of the component relative to the screen.          |
67| translate      | [TranslateResult](#translateresult) | Yes| Translation of the component.               |
68| scale          | [ScaleResult](#scaleresult) | Yes| Scaling of the component.               |
69| rotate         | [RotateResult](#rotateresult) | Yes| Rotation of the component.               |
70| transform      | [Matrix4Result](#matrix4result) | Yes| Affine matrix of the component, which is a 4x4 matrix object created based on the input parameter. |
71
72### Size
73
74**Atomic service API**: This API can be used in atomic services since API version 11.
75
76**System capability**: SystemCapability.ArkUI.ArkUI.Full
77
78| Name    | Type| Mandatory| Description                              |
79| -------- | ---- | ----------------------------------| ----------------------------------|
80| width    | number | Yes| Component width.<br>Unit: px                     |
81| height   | number | Yes| Component height.<br>Unit: px                     |
82
83### Offset
84
85**Atomic service API**: This API can be used in atomic services since API version 11.
86
87**System capability**: SystemCapability.ArkUI.ArkUI.Full
88
89| Name    | Type| Mandatory| Description                              |
90| --------| ---- | -----------------------------------| -----------------------------------|
91| x       | number | Yes| X coordinate.<br>Unit: px                          |
92| y       | number | Yes| Y coordinate.<br>Unit: px                          |
93
94### TranslateResult
95
96**Atomic service API**: This API can be used in atomic services since API version 11.
97
98**System capability**: SystemCapability.ArkUI.ArkUI.Full
99
100| Name    | Type| Mandatory| Description                              |
101| --------| ---- | -----------------------------------| -----------------------------------|
102| x       | number | Yes| Translation distance along the x-axis.<br>Unit: px                      |
103| y       | number | Yes| Translation distance along the y-axis.<br>Unit: px                      |
104| z       | number | Yes| Translation distance along the z-axis.<br>Unit: px                      |
105
106### ScaleResult
107
108**Atomic service API**: This API can be used in atomic services since API version 11.
109
110**System capability**: SystemCapability.ArkUI.ArkUI.Full
111
112| Name    | Type| Mandatory| Description                              |
113| --------| ---- | -----------------------------------| -----------------------------------|
114| x       | number | Yes| Scale factor along the x-axis.<br>Unit: px                      |
115| y       | number | Yes| Scale factor along the y-axis.<br>Unit: px                      |
116| z       | number | Yes| Scale factor along the z-axis.<br>Unit: px                      |
117| centerX | number | Yes| X coordinate of the center point.<br>Unit: px                 |
118| centerY | number | Yes| Y coordinate of the center point.<br>Unit: px               |
119
120### RotateResult
121
122**Atomic service API**: This API can be used in atomic services since API version 11.
123
124**System capability**: SystemCapability.ArkUI.ArkUI.Full
125
126| Name    | Type| Mandatory| Description                              |
127| --------| ---- | -----------------------------------| -----------------------------------|
128| x       | number | Yes| X coordinate of the rotation vector.<br>Unit: px                  |
129| y       | number | Yes| Y coordinate of the rotation vector.<br>Unit: px                  |
130| z       | number | Yes| Z coordinate of the rotation vector.<br>Unit: px                  |
131| angle   | number | Yes| Rotation angle.<br>Unit: px                         |
132| centerX | number | Yes| X coordinate of the center point.<br>Unit: px                |
133| centerY | number | Yes| Y coordinate of the center point.<br>Unit: px                |
134
135### Matrix4Result
136
137type Matrix4Result = [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number]
138
139**Atomic service API**: This API can be used in atomic services since API version 11.
140
141**System capability**: SystemCapability.ArkUI.ArkUI.Full
142
143| Type| Description                              |
144| --------| -----------------------------------|
145| [number,number,number,number,<br>number,number,number,number,<br>number,number,number,number,<br>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**. |
146
147**4 x 4 matrix description**
148
149| Name| Type  | Mandatory| Description                                |
150| ------ | ------ | ---- | ------------------------------------ |
151| m00    | number | Yes  | Scale factor along the x-axis. Defaults to **1** for the identity matrix.        |
152| m01    | number | Yes  | The second value, which is affected by the rotation of the x, y, and z axes.    |
153| m02    | number | Yes  | The third value, which is affected by the rotation of the x, y, and z axes.    |
154| m03    | number | Yes  | Meaningless value.                        |
155| m10    | number | Yes  | The fifth value, which is affected by the rotation of the x, y, and z axes.    |
156| m11    | number | Yes  | Scale factor along the y-axis. Defaults to **1** for the identity matrix.        |
157| m12    | number | Yes  | The seventh value, which is affected by the rotation of the x, y, and z axes.    |
158| m13    | number | Yes  | Meaningless value.                        |
159| m20    | number | Yes  | The ninth value, which is affected by the rotation of the x, y, and z axes.    |
160| m21    | number | Yes  | The tenth value, which is affected by the rotation of the x, y, and z axes.   |
161| m22    | number | Yes  | Scale factor along the z-axis. Defaults to **1** for the identity matrix.        |
162| m23    | number | Yes  | Meaningless value.                        |
163| m30    | number | Yes  | Translation value of the x-axis, in px. Defaults to **0** for the unit matrix.|
164| m31    | number | Yes  | Translation value of the y-axis, in px. The default value is **0** for the identity matrix.|
165| m32    | number | Yes  | Translation value of the z-axis, in px. The default value is **0** for the identity matrix.|
166| m33    | number | Yes  | Valid in homogeneous coordinates, presenting the perspective projection effect.  |
167
168**Example**
169
170> **NOTE**
171>
172> You are advised to use the [getComponentUtils](./js-apis-arkui-UIContext.md#getcomponentutils) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the **ComponentUtils** object associated with the current UI context.
173
174  ```ts
175import { matrix4, componentUtils } from '@kit.ArkUI';
176
177@Entry
178@Component
179struct Utils {
180  @State x: number = 120;
181  @State y: number = 10;
182  @State z: number = 100;
183  @State value: string = '';
184  private matrix1 = matrix4.identity().translate({ x: this.x, y: this.y, z: this.z });
185
186  build() {
187    Column() {
188      Image($r("app.media.img"))
189        .transform(this.matrix1)
190        .translate({ x: 20, y: 20, z: 20 })
191        .scale({ x: 0.5, y: 0.5, z: 1 })
192        .rotate({
193          x: 1,
194          y: 1,
195          z: 1,
196          centerX: '50%',
197          centerY: '50%',
198          angle: 300
199        })
200        .width(300)
201        .height(100)
202        .key("image_01")
203      Button('getRectangleById')
204      .onClick(() => {
205        this.value = JSON.stringify(componentUtils.getRectangleById("image_01")) // You are advised to use this.getUIContext().getComponentUtils().
206      }).margin(10).id('onClick')
207      Text(this.value)
208        .margin(20)
209        .width(300)
210        .height(300)
211        .borderWidth(2)
212    }.margin({left: 50})
213  }
214}
215  ```
216
217  ![componentget](figures/getRectangleById.gif)
218