1# Transformation 2 3Transformation attributes allow you to rotate, translate, scale, or transform a component. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9## rotate 10 11rotate(value: RotateOptions) 12 13Rotates the component. 14 15**Widget capability**: This API can be used in ArkTS widgets since API version 9. 16 17**Atomic service API**: This API can be used in atomic services since API version 11. 18 19**System capability**: SystemCapability.ArkUI.ArkUI.Full 20 21**Parameters** 22 23| Name| Type | Mandatory| Description | 24| ------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 25| value | [RotateOptions](#rotateoptions) | Yes | How the component rotates in the coordinate system (as shown below) with the upper left corner of the component as the coordinate origin. (x, y, z) specifies a vector as the axis of rotation.<br>The axis and center of rotation are set based on the coordinate system, which remains where it is when the component is moved.<br>Default value: When **x**, **y**, and **z** are not specified, their default values are **0**, **0**, and **1**, respectively. If any of **x**, **y**, and **z** is specified, the default value for the unspecified one is **0**.<br>{<br>centerX: '50%',<br>centerY: '50%'<br>centerZ: 0,<br>perspective: 0<br>}<br>Unit: vp<br><br>Since API version 10, **CenterZ** and **perspective** are supported in ArkTS widgets.| 26 27## rotate<sup>18+</sup> 28 29rotate(options: Optional\<RotateOptions>) 30 31Rotates the component. Compared to [rotate](#rotate), this API supports the **undefined** type for the **options** parameter. 32 33**Widget capability**: This API can be used in ArkTS widgets since API version 18. 34 35**Atomic service API**: This API can be used in atomic services since API version 18. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39**Parameters** 40 41| Name | Type | Mandatory| Description | 42| ------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 43| options | Optional\<[RotateOptions](#rotateoptions)> | Yes | How the component rotates in the coordinate system (as shown below) with the upper left corner of the component as the coordinate origin. (x, y, z) specifies a vector as the axis of rotation.<br>The axis and center of rotation are set based on the coordinate system, which remains where it is when the component is moved.<br>Default value: When **x**, **y**, and **z** are not specified, their default values are **0**, **0**, and **1**, respectively. If any of **x**, **y**, and **z** is specified, the default value for the unspecified one is **0**.<br>{<br>centerX: '50%',<br>centerY: '50%'<br>centerZ: 0,<br>perspective: 0<br>}<br>Unit: vp<br><br>Since API version 10, **CenterZ** and **perspective** are supported in ArkTS widgets.<br>If **options** is **undefined**, the component reverts to its original state with no rotation.| 44 45## translate 46 47translate(value: TranslateOptions) 48 49Translates the component. 50 51**Widget capability**: This API can be used in ArkTS widgets since API version 9. 52 53**Atomic service API**: This API can be used in atomic services since API version 11. 54 55**System capability**: SystemCapability.ArkUI.ArkUI.Full 56 57**Parameters** 58 59| Name| Type | Mandatory| Description | 60| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 61| value | [TranslateOptions](#translateoptions) | Yes | How the component is translated in the coordinate system (as shown below) with the upper left corner of the component as the coordinate origin. Values of **x**, **y**, and **z** indicate the translation distance along the respective axis. A positive value indicates a forward movement towards the respective axis, and a negative value indicates a backward movement towards the respective axis. The translation distance can be a number or a string (for example, **'10px'** or **'10%'**).<br>Default value:<br>{<br>x: 0,<br>y: 0,<br>z: 0<br>}<br>Unit: vp<br><br>**NOTE**<br>When the component is translated along the z-axis, the position of the observation point remains unchanged. As such, the component appears larger when the value of **z** places it closer to the observation point and smaller when the value of **z** places it further away from the observation point.<br> | 62 63## translate<sup>18+</sup> 64 65translate(translate: Optional\<TranslateOptions>) 66 67Translates the component. Compared to [translate](#translate), this API supports the **undefined** type for the **translate** parameter. 68 69**Widget capability**: This API can be used in ArkTS widgets since API version 18. 70 71**Atomic service API**: This API can be used in atomic services since API version 18. 72 73**System capability**: SystemCapability.ArkUI.ArkUI.Full 74 75**Parameters** 76 77| Name | Type | Mandatory| Description | 78| --------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 79| translate | Optional\<[TranslateOptions](#translateoptions)> | Yes | How the component is translated in the coordinate system (as shown below) with the upper left corner of the component as the coordinate origin. Values of **x**, **y**, and **z** indicate the translation distance along the respective axis. A positive value indicates a forward movement towards the respective axis, and a negative value indicates a backward movement towards the respective axis. The translation distance can be a number or a string (for example, **'10px'** or **'10%'**).<br>Default value:<br>{<br>x: 0,<br>y: 0,<br>z: 0<br>}<br>Unit: vp<br><br>**NOTE**<br>When the component is translated along the z-axis, the position of the observation point remains unchanged. As such, the component appears larger when the value of **z** places it closer to the observation point and smaller when the value of **z** places it further away from the observation point.<br><br>If **options** is **undefined**, the component reverts to its original state with no translation.| 80 81## scale 82 83scale(value: ScaleOptions) 84 85Scales the component. 86 87**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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**Parameters** 94 95| Name| Type | Mandatory| Description | 96| ------ | ------------------------------------- | ---- | ------------------------------------------------------------ | 97| value | [ScaleOptions](#scaleoptions) | Yes | Scale ratio along the x-, y-, and z-axis. The default value is **1**. **centerX** and **centerY** are used to set the scale center point.<br>Default value:<br>{<br>x: 1,<br>y: 1,<br>z: 1,<br>centerX:'50%',<br>centerY:'50%'<br>} | 98 99## scale<sup>18+</sup> 100 101scale(options: Optional\<ScaleOptions>) 102 103Scales the component. Compared to [scale](#scale), this API supports the **undefined** type for the **options** parameter. 104 105**Widget capability**: This API can be used in ArkTS widgets since API version 18. 106 107**Atomic service API**: This API can be used in atomic services since API version 18. 108 109**System capability**: SystemCapability.ArkUI.ArkUI.Full 110 111**Parameters** 112 113| Name | Type | Mandatory| Description | 114| ------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 115| options | Optional\<[ScaleOptions](#scaleoptions)> | Yes | Scale ratio along the x-, y-, and z-axis. The default value is **1**. **centerX** and **centerY** are used to set the scale center point.<br>Default value:<br>{<br>x: 1,<br>y: 1,<br>z: 1,<br>centerX:'50%',<br>centerY:'50%'<br>}<br>If **options** is **undefined**, the component reverts to its original state with no scaling.| 116 117## transform 118 119transform(value: object) 120 121Sets the transformation matrix of the component. 122 123**Atomic service API**: This API can be used in atomic services since API version 11. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Parameters** 128 129| Name| Type | Mandatory| Description | 130| ------ | ------ | ---- | ------------------------------------------------------------ | 131| value | object | Yes | Transformation matrix of the component. Only the [Matrix4Transit](../js-apis-matrix4.md) object type is supported.| 132 133## transform<sup>18+</sup> 134 135transform(transform: Optional\<object>) 136 137Sets the transformation matrix of the component. Compared to [transform](#transform), this API supports the **undefined** type for the **transform** parameter. 138 139**Atomic service API**: This API can be used in atomic services since API version 18. 140 141**System capability**: SystemCapability.ArkUI.ArkUI.Full 142 143**Parameters** 144 145| Name| Type | Mandatory| Description | 146| ------ | --------------------------------------- | ---- | ------------------------ | 147| transform | Optional\<object> | | Transformation matrix of the component. Only the [Matrix4Transit](../js-apis-matrix4.md) object type is supported.<br>If **transform** is **undefined**, the component reverts to the identity matrix (no transformation).| 148 149## RotateOptions 150 151**Atomic service API**: This API can be used in atomic services since API version 11. 152 153**System capability**: SystemCapability.ArkUI.ArkUI.Full 154 155| Name | Type | Mandatory| Description | 156| ------------------------- | -------------------------- | ---- | ------------------------------------------------------------ | 157| x | number | No | X coordinate of the rotation axis vector.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 158| y | number | No | Y coordinate of the rotation axis vector.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 159| z | number | No | Z coordinate of the rotation axis vector.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 160| angle | number \| string | Yes | Angle to rotate. A positive angle indicates a clockwise rotation, and a negative angle indicates a counterclockwise rotation. The value can be of the string type, for example, **'90deg'**.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 161| centerX | number \| string | No | X coordinate of the transformation center point (anchor).<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 162| centerY | number \| string | No | Y coordinate of the transformation center point (anchor).<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 163| centerZ<sup>10+</sup> | number | No | Z-axis anchor, that is, the z-component of the 3D rotation center point.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 164| perspective<sup>10+</sup> | number | No | Distance from the user to the z=0 plane.<br>The axis and center of rotation are set based on the coordinate system, which remains where it is when the component is moved.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 165 166## TranslateOptions 167 168**Widget capability**: This API can be used in ArkTS widgets since API version 9. 169 170**Atomic service API**: This API can be used in atomic services since API version 11. 171 172**System capability**: SystemCapability.ArkUI.ArkUI.Full 173 174| Name| Type | Mandatory| Description | 175| ---- | -------------------------- | ---- | --------------- | 176| x | number \| string | No | Translation distance along the x-axis.<br>For the number type, the unit is VP, and the value range is (-∞, +∞).<br>For the string type, the value follows the format of [Length](ts-types.md#length) string type.| 177| y | number \| string | No | Translation distance along the y-axis.<br>For the number type, the unit is VP, and the value range is (-∞, +∞).<br>For the string type, the value follows the format of [Length](ts-types.md#length) string type.| 178| z | number \| string | No | Translation distance along the z-axis.<br>For the number type, the unit is VP, and the value range is (-∞, +∞).<br>For the string type, the value follows the format of [Length](ts-types.md#length) string type.| 179 180## ScaleOptions 181 182**Widget capability**: This API can be used in ArkTS widgets since API version 9. 183 184**Atomic service API**: This API can be used in atomic services since API version 11. 185 186**System capability**: SystemCapability.ArkUI.ArkUI.Full 187 188| Name | Type | Mandatory| Description | 189| ------- | -------------------------- | ---- | ------------------------------------------------------------ | 190| x | number | No | Scale ratio along the x-axis. x > 1: The component is scaled up along the x-axis.<br>0 < x < 1: The component is scaled down along the x-axis.<br>x < 0: The component is scaled in the reverse direction of the x-axis.| 191| y | number | No | Scale ratio along the y-axis. y > 1: The component is scaled up along the y-axis.<br>0 < y < 1: The component is scaled down along the y-axis.<br>y < 0: The component is scaled in the reverse direction of the y-axis.| 192| z | number | No | Scale ratio along the z-axis. z > 1: The component is scaled up along the z-axis.<br>0 < z < 1: The component is scaled down along the z-axis.<br>z < 0: The component is scaled in the reverse direction of the z-axis.| 193| centerX | number \| string | No | X coordinate of the transformation center point (anchor).<br>Unit: vp| 194| centerY | number \| string | No | Y coordinate of the transformation center point (anchor).<br>Unit: vp| 195 196> **NOTE** 197> 198> If the **rotate** and **scale** attributes are both set for a component, the values of **centerX** and **centerY** conflict. In this case, the one that is set later in time is used. 199 200## Example 201 202### Example 1: Adding Graphical Transformation Effects 203 204This example demonstrates how to apply various graphical transformations using the **rotate**, **translate**, **scale**, and **transform** APIs. 205 206```ts 207// xxx.ets 208import { matrix4 } from '@kit.ArkUI'; 209 210@Entry 211@Component 212struct TransformExample { 213 build() { 214 Column() { 215 Text('rotate').width('90%').fontColor(0xCCCCCC).padding(15).fontSize(14) 216 Row() 217 .rotate({ 218 x: 0, 219 y: 0, 220 z: 1, 221 centerX: '50%', 222 centerY: '50%', 223 angle: 300 224 })// The component rotates around the center point of the rotation axis (0, 0, 1) clockwise by 300 degrees. 225 .width(100).height(100).backgroundColor(0xAFEEEE) 226 227 Text('translate').width('90%').fontColor(0xCCCCCC).padding(10).fontSize(14) 228 Row() 229 .translate({ x: 100, y: 10 })// The component translates by 100 along the x-axis and by 10 along the y-axis. 230 .width(100) 231 .height(100) 232 .backgroundColor(0xAFEEEE) 233 .margin({ bottom: 10 }) 234 235 Text('scale').width('90%').fontColor(0xCCCCCC).padding(15).fontSize(14) 236 Row() 237 .scale({ x: 2, y: 0.5 })// The height and width are doubled. The z-axis has no effect in 2D mode. 238 .width(100).height(100).backgroundColor(0xAFEEEE) 239 240 Text('Matrix4').width('90%').fontColor(0xCCCCCC).padding(15).fontSize(14) 241 Row() 242 .width(100).height(100).backgroundColor(0xAFEEEE) 243 .transform(matrix4.identity().translate({ x: 50, y: 50 }).scale({ x: 1.5, y: 1 }).rotate({ 244 x: 0, 245 y: 0, 246 z: 1, 247 angle: 60 248 })) 249 }.width('100%').margin({ top: 5 }) 250 } 251} 252``` 253 254 255 256### Example 2: Setting the Rotation Perspective 257 258This example demonstrates how to use the **perspective** API to add a perspective effect to a component. 259 260```ts 261// xxx.ets 262@Entry 263@Component 264struct Index { 265 @State prep: number = 10; 266 267 build() { 268 Row() { 269 Column() { 270 Stack() 271 .width(100) 272 .height(100) 273 .backgroundColor(Color.Red) 274 .rotate({ y: 1, angle: 45, perspective: this.prep }) 275 Button('change prep') 276 .margin({ top: 100 }) 277 .onClick(() => { 278 animateTo({ 279 duration: 2000, 280 curve: Curve.EaseIn, 281 iterations: 1, 282 playMode: PlayMode.Normal, 283 onFinish: () => { 284 console.info('play end') 285 } 286 }, () => { 287 this.prep = 500 // Change the component's perspective from 10 to 500. 288 }) 289 }) 290 } 291 .width('100%') 292 } 293 .height('100%') 294 } 295} 296``` 297 298 299 300### Example 3: Implementing Rotation Around a Center Point 301 302This example shows how to achieve the same rotation effect by setting different parameters for** rotate** and **transform**. 303 304```ts 305import { matrix4 } from '@kit.ArkUI' 306 307@Entry 308@Component 309struct MatrixExample { 310 build() { 311 Column({ space: 100 }) { 312 Text('Hello1') 313 .textAlign(TextAlign.Center) 314 .width(100) 315 .height(60) 316 .borderWidth(1) 317 318 Text('Hello2') 319 .textAlign(TextAlign.Center) 320 .width(100) 321 .height(60) 322 .borderWidth(1) 323 .rotate({ 324 // Rotate 90 degrees around the anchor (100 vp, 60 vp), where the value of centerX and centerY in rotate or scale are the component's anchors. 325 z: 1, 326 angle: 90, 327 centerX: 100, 328 centerY: 60 329 }) 330 331 Text('Hello3') 332 .textAlign(TextAlign.Center) 333 .width(100) 334 .height(60) 335 .borderWidth(1) 336 .transform(matrix4.identity() 337 .rotate({ 338 // The component's anchor (centerX, centerY) is (50%, 50%) by default, which is (50 vp, 30 vp). 339 // Set (centerX, centerY) of rotate in transform to (50 vp, 30 vp), which is an additional offset from the component's own anchor. 340 // This transformation is equivalent to rotating around (100 vp, 60 vp), achieving the same rotation effect as "Hello2." 341 z: 1, 342 angle: 90, 343 centerX: vp2px(50), 344 centerY: vp2px(30) 345 })) 346 347 Text('Hello4') 348 .textAlign(TextAlign.Center) 349 .width(100) 350 .height(60) 351 .borderWidth(1) 352 .scale({ 353 // centerX and centerY take effect only when x or y is set. 354 // Set the component anchor to (100 vp, 60 vp). 355 x: 1, 356 y: 1, 357 centerX: 100, 358 centerY: 60 359 })// If centerX and centerY are not specified, the rotation uses the component's own anchor as the center. 360 // Here, the component rotates around (100 vp, 60 vp) through the anchor set by scale, achieving the same rotation effect as "Hello2." 361 .transform(matrix4.identity().rotate({ z: 1, angle: 90 })) 362 }.width('100%') 363 .height('100%') 364 } 365} 366``` 367 368 369
