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