1# @ohos.arkui.componentUtils (componentUtils) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9提供获取组件绘制区域坐标和大小的能力。 10 11> **说明：** 12> 13> 从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 本模块功能依赖UI的执行上下文，不可在[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的地方使用，参见[UIContext](./arkts-apis-uicontext-uicontext.md)说明。 16 17## 导入模块 18 19```ts 20import { componentUtils } from '@kit.ArkUI'; 21``` 22## componentUtils.getRectangleById<sup>(deprecated)</sup> 23 24getRectangleById(id: string): ComponentInfo 25 26根据组件ID获取组件实例对象，通过组件实例对象将获取的坐标位置和大小同步返回给开发者。 27 28> **说明：** 29> 30> 从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getComponentUtils](arkts-apis-uicontext-uicontext.md#getcomponentutils)获取[ComponentUtils](arkts-apis-uicontext-componentutils.md)实例，再通过此实例调用替代方法[getRectangleById](arkts-apis-uicontext-componentutils.md#getrectanglebyid)。 31> 32> 从API version 10开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getComponentUtils](arkts-apis-uicontext-uicontext.md#getcomponentutils)方法获取当前UI上下文关联的[ComponentUtils](arkts-apis-uicontext-componentutils.md)对象。该接口需要在目标组件布局、完成以后获取目标组件区域大小信息，建议在[onAppear](./arkui-ts/ts-universal-events-show-hide.md#onappear)中使用该接口。 33 34**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 35 36**系统能力：** SystemCapability.ArkUI.ArkUI.Full 37 38**参数：** 39 40| 参数名 | 类型 | 必填 | 说明 | 41| ------ | ------ | ---- | ---------- | 42| id | string | 是 | 指定组件id。 | 43 44**返回值：** 45 46| 类型 | 说明 | 47| ------ | ---------- | 48| [ComponentInfo](#componentinfo) | 组件大小、位置、平移缩放旋转及仿射矩阵属性信息。 | 49 50**错误码：** 51 52以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 53 54| 错误码ID | 错误信息 | 55| ------ | ------------------- | 56| 100001 | UI execution context not found. | 57 58**示例：** 59 60```ts 61import { componentUtils } from '@kit.ArkUI'; 62let modePosition:componentUtils.ComponentInfo = componentUtils.getRectangleById("onClick"); 63``` 64 65## ComponentInfo 66 67组件大小、位置、平移缩放旋转及仿射矩阵属性信息。 68 69**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 70 71**系统能力：** SystemCapability.ArkUI.ArkUI.Full 72 73| 名称 | 类型 | 只读 | 可选 | 说明 | 74| ---------------|------------| --------------- | -----------------------------| -----------------------------| 75| size | [Size](#size) | 否 | 否 | 组件大小。 | 76| localOffset | [Offset](#offset) | 否 | 否 | 组件相对于父组件信息。 | 77| windowOffset | [Offset](#offset) | 否 | 否 | 组件相对于窗口信息。 | 78| screenOffset | [Offset](#offset) | 否 | 否 | 组件相对于屏幕信息。 | 79| translate | [TranslateResult](#translateresult)| 否 | 否 | 组件平移信息。 | 80| scale | [ScaleResult](#scaleresult) | 否 | 否 | 组件缩放信息。 | 81| rotate | [RotateResult](#rotateresult) | 否 | 否 | 组件旋转信息。 | 82| transform | [Matrix4Result](#matrix4result) | 否 | 否 | 仿射矩阵信息，根据入参创建的四阶矩阵对象。 | 83 84### Size 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90| 名称 | 类型 | 只读 | 可选 | 说明 | 91| -------- | ---- | -------------------------| ------------------------| ----------------------------------| 92| width | number | 否 | 否 | 组件宽度。<br />单位: px | 93| height | number | 否 | 否 | 组件高度。<br />单位: px | 94 95### Offset 96 97**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 98 99**系统能力：** SystemCapability.ArkUI.ArkUI.Full 100 101| 名称 | 类型 | 只读 | 可选 | 说明 | 102| --------| ---- | --------------| ------------------------------------| -----------------------------------| 103| x | number| 否 | 否 | x点坐标。<br />单位: px | 104| y | number| 否 | 否 | y点坐标。<br />单位: px | 105 106### TranslateResult 107 108**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112| 名称 | 类型 | 只读 | 可选 | 说明 | 113| --------| ---- | -------------------| -------------------------------| -----------------------------------| 114| x | number | 否 | 否 | x轴平移距离。<br />单位: px | 115| y | number | 否 | 否 | y轴平移距离。<br />单位: px | 116| z | number | 否 | 否 | z轴平移距离。<br />单位: px | 117 118### ScaleResult 119 120**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 121 122**系统能力：** SystemCapability.ArkUI.ArkUI.Full 123 124| 名称 | 类型 | 只读 | 可选 | 说明 | 125| --------| ---- | ---- |-----------------------------------| -----------------------------------| 126| x | number | 否 | 否 | x轴缩放倍数。<br />单位: px | 127| y | number | 否 | 否 | y轴缩放倍数。<br />单位: px | 128| z | number | 否 | 否 | z轴缩放倍数。<br />单位: px | 129| centerX | number | 否 | 否 | 变换中心点x轴坐标。<br />单位: px | 130| centerY | number | 否 | 否 | 变换中心点y轴坐标。<br />单位: px | 131 132### RotateResult 133 134**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 135 136**系统能力：** SystemCapability.ArkUI.ArkUI.Full 137 138| 名称 | 类型 | 只读 | 可选 | 说明 | 139| --------| ---- | -----------------| ---------------------------------| -----------------------------------| 140| x | number | 否 | 否 | 旋转轴向量x坐标。<br />单位: px | 141| y | number | 否 | 否 | 旋转轴向量y坐标。<br />单位: px | 142| z | number | 否 | 否 | 旋转轴向量z坐标。<br />单位: px | 143| angle | number | 否 | 否 | 旋转角度。<br />单位: px | 144| centerX | number | 否 | 否 | 变换中心点x轴坐标。<br />单位: px | 145| centerY | number | 否 | 否 | 变换中心点y轴坐标。<br />单位: px | 146 147### Matrix4Result 148 149type Matrix4Result = [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number] 150 151**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 152 153**系统能力：** SystemCapability.ArkUI.ArkUI.Full 154 155| 类型 | 说明 | 156| --------| -----------------------------------| 157| [number,number,number,number,<br />number,number,number,number,<br />number,number,number,number,<br />number,number,number,number] | 取值范围为长度为16（4\*4）的number数组， 详情见四阶矩阵说明。<br/>单位: px | 158 159**四阶矩阵说明：** 160 161| 参数名 | 类型 | 必填 | 说明 | 162| ------ | ------ | ---- | ------------------------------------ | 163| m00 | number | 是 | x轴缩放值，单位矩阵默认为1。 | 164| m01 | number | 是 | 第2个值，xyz轴旋转会影响这个值。 | 165| m02 | number | 是 | 第3个值，xyz轴旋转会影响这个值。 | 166| m03 | number | 是 | 无实际意义。 | 167| m10 | number | 是 | 第5个值，xyz轴旋转会影响这个值。 | 168| m11 | number | 是 | y轴缩放值，单位矩阵默认为1。 | 169| m12 | number | 是 | 第7个值，xyz轴旋转会影响这个值。 | 170| m13 | number | 是 | 无实际意义。 | 171| m20 | number | 是 | 第9个值，xyz轴旋转会影响这个值。 | 172| m21 | number | 是 | 第10个值，xyz轴旋转会影响这个值。 | 173| m22 | number | 是 | z轴缩放值，单位矩阵默认为1。 | 174| m23 | number | 是 | 无实际意义。 | 175| m30 | number | 是 | x轴平移值，单位px，单位矩阵默认为0。 | 176| m31 | number | 是 | y轴平移值，单位px，单位矩阵默认为0。 | 177| m32 | number | 是 | z轴平移值，单位px，单位矩阵默认为0。 | 178| m33 | number | 是 | 齐次坐标下生效，产生透视投影效果。 | 179 180**示例：** 181 182> **说明：** 183> 184> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getComponentUtils](./arkts-apis-uicontext-uicontext.md#getcomponentutils)方法获取当前UI上下文关联的ComponentUtils对象。 185 186 ```ts 187import { matrix4, componentUtils } from '@kit.ArkUI'; 188 189@Entry 190@Component 191struct Utils { 192 @State x: number = 120; 193 @State y: number = 10; 194 @State z: number = 100; 195 @State value: string = ''; 196 private matrix1 = matrix4.identity().translate({ x: this.x, y: this.y, z: this.z }); 197 198 build() { 199 Column() { 200 // $r("app.media.img")需要替换为开发者所需的图像资源文件 201 Image($r("app.media.img")) 202 .transform(this.matrix1) 203 .translate({ x: 20, y: 20, z: 20 }) 204 .scale({ x: 0.5, y: 0.5, z: 1 }) 205 .rotate({ 206 x: 1, 207 y: 1, 208 z: 1, 209 centerX: '50%', 210 centerY: '50%', 211 angle: 300 212 }) 213 .width(300) 214 .height(100) 215 .key("image_01") 216 Button('getRectangleById') 217 .onClick(() => { 218 this.value = JSON.stringify(this.getUIContext().getComponentUtils().getRectangleById("image_01")) // 建议使用this.getUIContext().getComponentUtils()接口 219 }).margin(10).id('onClick') 220 Text(this.value) 221 .margin(20) 222 .width(300) 223 .height(300) 224 .borderWidth(2) 225 }.margin({left: 50}) 226 } 227} 228 ``` 229 230  231
