1# @ohos.arkui.componentUtils (componentUtils)
2
3提供获取组件绘制区域坐标和大小的能力。
4
5> **说明：**
6>
7> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9> 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](./js-apis-arkui-UIContext.md#uicontext)说明。
10>
11> 从API version 10开始，可以通过使用UIContext中的[getComponentUtils](./js-apis-arkui-UIContext.md#getcomponentutils)方法获取当前UI上下文关联的ComponentUtils对象。该接口需要在目标组件布局、完成以后获取目标组件区域大小信息，建议在[@ohos.arkui.inspector(布局回调)](js-apis-arkui-inspector.md)接收到布局完成的通知以后使用该接口。
12
13## 导入模块
14
15```ts
16import { componentUtils } from '@kit.ArkUI';
17```
18## componentUtils.getRectangleById
19
20getRectangleById(id: string): ComponentInfo
21
22根据组件ID获取组件实例对象, 通过组件实例对象将获取的坐标位置和大小同步返回给开发者。
23
24**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
25
26**系统能力：** SystemCapability.ArkUI.ArkUI.Full
27
28**参数：**
29
30| 参数名 | 类型   | 必填 | 说明       |
31| ------ | ------ | ---- | ---------- |
32| id     | string | 是   | 指定组件id。 |
33
34**返回值：**
35
36| 类型   | 说明       |
37| ------ | ---------- |
38| [ComponentInfo](#componentinfo) | 组件大小、位置、平移缩放旋转及仿射矩阵属性信息。 |
39
40**错误码：**
41
42以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。
43
44| 错误码ID  | 错误信息                |
45| ------ | ------------------- |
46| 100001 | UI execution context not found. |
47
48**示例：**
49
50```ts
51import { componentUtils } from '@kit.ArkUI';
52let modePosition:componentUtils.ComponentInfo = componentUtils.getRectangleById("onClick");
53```
54
55## ComponentInfo
56
57**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
58
59**系统能力：** SystemCapability.ArkUI.ArkUI.Full
60
61| 名称           | 类型             | 必填           | 说明                         |
62| ---------------|------------     | -----------------------------| -----------------------------|
63| size           | [Size](#size) | 是 | 组件大小。                    |
64| localOffset    | [Offset](#offset) | 是 | 组件相对于父组件信息。         |
65| windowOffset   | [Offset](#offset) | 是 | 组件相对于窗口信息。           |
66| screenOffset   | [Offset](#offset) | 是 | 组件相对于屏幕信息。           |
67| translate      | [TranslateResult](#translateresult) | 是 | 组件平移信息。                |
68| scale          | [ScaleResult](#scaleresult) | 是 | 组件缩放信息。                |
69| rotate         | [RotateResult](#rotateresult) | 是 | 组件旋转信息。                |
70| transform      | [Matrix4Result](#matrix4result) | 是 | 仿射矩阵信息，根据入参创建的四阶矩阵对象。  |
71
72### Size
73
74**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
75
76**系统能力：** SystemCapability.ArkUI.ArkUI.Full
77
78| 名称     | 类型 | 必填 | 说明                               |
79| -------- | ---- | ----------------------------------| ----------------------------------|
80| width    | number | 是 | 组件宽度。<br />单位: px                      |
81| height   | number | 是 | 组件高度。<br />单位: px                      |
82
83### Offset
84
85**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
86
87**系统能力：** SystemCapability.ArkUI.ArkUI.Full
88
89| 名称     | 类型 | 必填 | 说明                               |
90| --------| ---- | -----------------------------------| -----------------------------------|
91| x       | number | 是 | x点坐标。<br />单位: px                           |
92| y       | number | 是 | y点坐标。<br />单位: px                           |
93
94### TranslateResult
95
96**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
97
98**系统能力：** SystemCapability.ArkUI.ArkUI.Full
99
100| 名称     | 类型 | 必填 | 说明                               |
101| --------| ---- | -----------------------------------| -----------------------------------|
102| x       | number | 是 | x轴平移距离。<br />单位: px                       |
103| y       | number | 是 | y轴平移距离。<br />单位: px                       |
104| z       | number | 是 | z轴平移距离。<br />单位: px                       |
105
106### ScaleResult
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| centerX | number | 是 | 变换中心点x轴坐标。<br />单位: px                  |
118| centerY | number | 是 | 变换中心点y轴坐标。<br />单位: px                |
119
120### RotateResult
121
122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
123
124**系统能力：** SystemCapability.ArkUI.ArkUI.Full
125
126| 名称     | 类型 | 必填 | 说明                               |
127| --------| ---- | -----------------------------------| -----------------------------------|
128| x       | number | 是 | 旋转轴向量x坐标。<br />单位: px                   |
129| y       | number | 是 | 旋转轴向量y坐标。<br />单位: px                   |
130| z       | number | 是 | 旋转轴向量z坐标。<br />单位: px                   |
131| angle   | number | 是 | 旋转角度。<br />单位: px                          |
132| centerX | number | 是 | 变换中心点x轴坐标。<br />单位: px                 |
133| centerY | number | 是 | 变换中心点y轴坐标。<br />单位: 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**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
140
141**系统能力：** SystemCapability.ArkUI.ArkUI.Full
142
143| 类型 | 说明                               |
144| --------| -----------------------------------|
145| [number,number,number,number,<br />number,number,number,number,<br />number,number,number,number,<br />number,number,number,number] | 取值范围为长度为16（4\*4）的number数组,&nbsp;详情见四阶矩阵说明,单位: px  |
146
147**四阶矩阵说明：**
148
149| 参数名 | 类型   | 必填 | 说明                                 |
150| ------ | ------ | ---- | ------------------------------------ |
151| m00    | number | 是   | x轴缩放值，单位矩阵默认为1。         |
152| m01    | number | 是   | 第2个值，xyz轴旋转会影响这个值。     |
153| m02    | number | 是   | 第3个值，xyz轴旋转会影响这个值。     |
154| m03    | number | 是   | 无实际意义。                         |
155| m10    | number | 是   | 第5个值，xyz轴旋转会影响这个值。     |
156| m11    | number | 是   | y轴缩放值，单位矩阵默认为1。         |
157| m12    | number | 是   | 第7个值，xyz轴旋转会影响这个值。     |
158| m13    | number | 是   | 无实际意义。                         |
159| m20    | number | 是   | 第9个值，xyz轴旋转会影响这个值。     |
160| m21    | number | 是   | 第10个值，xyz轴旋转会影响这个值。    |
161| m22    | number | 是   | z轴缩放值，单位矩阵默认为1。         |
162| m23    | number | 是   | 无实际意义。                         |
163| m30    | number | 是   | x轴平移值，单位px，单位矩阵默认为0。 |
164| m31    | number | 是   | y轴平移值，单位px，单位矩阵默认为0。 |
165| m32    | number | 是   | z轴平移值，单位px，单位矩阵默认为0。 |
166| m33    | number | 是   | 齐次坐标下生效，产生透视投影效果。   |
167
168**示例：**
169
170> **说明：**
171>
172> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getComponentUtils](./js-apis-arkui-UIContext.md#getcomponentutils)方法获取当前UI上下文关联的ComponentUtils对象。
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")) // 建议使用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)