1# Explicit Animation 2 3You can create explicit animation with your custom settings. 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 9animateTo(value: AnimateParam, event: () => void): void 10 11Since API version 9, this API is supported in ArkTS widgets. 12 13| Name | Type | Mandatory | Description | 14| ---------------- | ------------ | -------------------- | -------------------- | 15| value | [AnimateParam](#animateparam)| Yes| Animation settings.| 16| event | () => void | Yes| Closure function that displays the dynamic effect. The system automatically inserts the transition animation if the status changes in the closure function.| 17 18## AnimateParam 19 20| Name| Type| Description| 21| -------- | -------- | -------- | 22| duration | number | Animation duration, in ms.<br>Default value: **1000**<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>- The maximum animation duration on an ArkTS widget is 1000 ms. If the set value exceeds the limit, the value **1000** will be used.<br>- Floating-point values will be rounded down to integers. For example, if the value set is 1.2, **1** will be used.| 23| tempo | number | Animation playback speed. A larger value indicates faster animation playback, and a smaller value indicates slower animation playback. The value **0** means that there is no animation.<br>Default value: **1.0**| 24| curve | [Curve](ts-appendix-enums.md#curve) \| [ICurve](../apis/js-apis-curve.md#icurve)<sup>9+</sup> \| string | Animation curve.<br>Default value: **Curve.EaseInOut**<br>Since API version 9, this API is supported in ArkTS widgets.| 25| delay | number | Delay of animation playback, in ms. By default, the playback is not delayed.<br>Default value: **0**<br>**NOTE**<br>- Floating-point values will be rounded down to integers. For example, if the value set is 1.2, **1** will be used.| 26| iterations | number | Number of times that the animation is played. By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times.<br>Default value: **1**| 27| playMode | [PlayMode](ts-appendix-enums.md#playmode) | Animation playback mode. By default, the animation is played from the beginning after the playback is complete.<br>Default value: **PlayMode.Normal**<br>Since API version 9, this API is supported in ArkTS widgets.<br>For details about the restrictions, see **Notes about PlayMode**.| 28| onFinish | () => void | Callback invoked when the animation playback is complete.<br>Since API version 9, this API is supported in ArkTS widgets.| 29 30> **Notes about PlayMode**: 31> - **PlayMode.Normal** and **PlayMode.Alternate** are recommended. Under these settings, the first round of the animation is played forwards. If **PlayMode.Reverse** or **PlayMode.AlternateReverse** is used, the first round of the animation is played backwards. In this case, the animation jumps to the end state and then starts from there. 32> - When using **PlayMode.Alternate** or **PlayMode.AlternateReverse**, make sure the final state of the animation is the same as the value of the state variable. In other words, make sure the last round of the animation is played forwards. When **PlayMode.Alternate** is used, **iterations** must be set to an odd number. When **PlayMode.AlternateReverse** is used, **iterations** must be set to an even number. 33> - **PlayMode.Reverse** is not recommended. Under this setting, the animation jumps to the end state at the beginning, and its final state will be different from the value of the state variable. 34 35## Example 36 37```ts 38// xxx.ets 39@Entry 40@Component 41struct AnimateToExample { 42 @State widthSize: number = 250 43 @State heightSize: number = 100 44 @State rotateAngle: number = 0 45 private flag: boolean = true 46 47 build() { 48 Column() { 49 Button('change size') 50 .width(this.widthSize) 51 .height(this.heightSize) 52 .margin(30) 53 .onClick(() => { 54 if (this.flag) { 55 animateTo({ 56 duration: 2000, 57 curve: Curve.EaseOut, 58 iterations: 3, 59 playMode: PlayMode.Normal, 60 onFinish: () => { 61 console.info('play end') 62 } 63 }, () => { 64 this.widthSize = 150 65 this.heightSize = 60 66 }) 67 } else { 68 animateTo({}, () => { 69 this.widthSize = 250 70 this.heightSize = 100 71 }) 72 } 73 this.flag = !this.flag 74 }) 75 Button('change rotate angle') 76 .margin(50) 77 .rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle }) 78 .onClick(() => { 79 animateTo({ 80 duration: 1200, 81 curve: Curve.Friction, 82 delay: 500, 83 iterations: -1, // The value -1 indicates that the animation is played for an unlimited number of times. 84 playMode: PlayMode.Alternate, 85 onFinish: () => { 86 console.info('play end') 87 } 88 }, () => { 89 this.rotateAngle = 90 90 }) 91 }) 92 }.width('100%').margin({ top: 5 }) 93 } 94} 95``` 96 97 98
