1# Explicit Animation (animateTo) 2 3With **animateTo**, you can build explicit animations for state changes caused by closure code. In an explicit animation that involves width and height changes, as in a property animation, a component's content (such as text, [canvas](ts-components-canvas-canvas.md) content, and [linear gradient](ts-universal-attributes-gradient-color.md)) is changed straight to the final state. To enable the content to change with the width and height during the animation process, you can use the [renderFit](ts-universal-attributes-renderfit.md) attribute. 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> 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. For details, see [UIContext](../js-apis-arkui-UIContext.md#uicontext). 10> 11>**Widget capability**: This API can be used in ArkTS widgets since API version 9. 12> 13> Since API version 10, you can use the [animateTo](../js-apis-arkui-UIContext.md#animateto) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext), which ensures that your animation is executed in the intended UI instance. 14> This API can be used in atomic services since API version 11. 15 16## APIs 17animateTo(value: AnimateParam, event: () => void): void 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**Parameters** 22| Name | Type | Mandatory| Description | 23| ----- | --------------------------------- | ---- | ------------------------------------- | 24| value | [AnimateParam](#animateparam)| Yes | Animation settings. | 25| event | () => void | Yes | Closure function for the animation. The system automatically inserts the transition animation if the state changes in the closure function.| 26 27## AnimateParam 28 29| Name | Type | Mandatory | Description | 30| ---------- | ---------------|------------------------ | ---------------------------------------- | 31| duration | number | No | Animation duration, in ms.<br>Default value: **1000**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<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>- A value less than 0 evaluates to the value **0**.<br>- Floating-point values will be rounded down to integers. For example, if the value set is 1.2, **1** will be used.| 32| tempo | number | No| 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**<br><br>**Atomic service API**: This API can be used in atomic services since API version 11. **NOTE**<br>A value less than 0 evaluates to the value **1**.| 33| curve | [Curve](ts-appendix-enums.md#curve) \| [ICurve<sup>9+</sup>](../js-apis-curve.md#icurve9) \| string | No| Animation curve.<br>Default value: **Curve.EaseInOut**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 34| delay | number | No| Delay of animation playback, in ms. By default, the playback is not delayed.<br>Default value: **0**<br>Value range: (-∞, +∞)<br><br>**Atomic service API**: This API can be used in atomic services since API version 11. **NOTE**<br>- A value greater than 0 means to begin the animation after the specified amount of time has elapsed.<br>A value less than 0 means to begin the animation in advance. If the absolute value of **delay** is less than the actual animation duration, the animation starts its first frame from the state at the absolute value. If the absolute value of **delay** is greater than or equal to the actual animation duration, the animation starts its first frame from the end state. The actual animation duration is equal to the duration of a single animation multiplied by the number of animation playback times.<br>- Floating-point values will be rounded down to integers. For example, if the value set is 1.2, **1** will be used.| 35| iterations | number | No| 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. The value **0** indicates that there is no animation.<br>Default value: **1**<br>Value range: [-1, +∞)<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 36| playMode | [PlayMode](ts-appendix-enums.md#playmode)|No| Playback mode. By default, the animation is played from the beginning after the playback is complete.<br>Default value: **PlayMode.Normal**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>For details about the restrictions, see **Notes about PlayMode**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 37| onFinish | () => void | No| Callback invoked when the animation playback is complete.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| finishCallbackType<sup>11+</sup> | [FinishCallbackType](#finishcallbacktype11)|No| Type of the **onFinish** callback.<br>Default value: **FinishCallbackType.REMOVED**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 11.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 39| expectedFrameRateRange<sup>11+</sup> | [ExpectedFrameRateRange](#expectedframeraterange11) | No| Expected frame rate range of the animation. **Atomic service API**: This API can be used in atomic services since API version 12.| 40 41> **Notes about PlayMode**: 42> 43> - **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. 44> - 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. 45> - **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. 46 47## FinishCallbackType<sup>11+</sup> 48 49**Widget capability**: This API can be used in ArkTS widgets since API version 11. 50 51**Atomic service API**: This API can be used in atomic services since API version 12. 52 53**System capability**: SystemCapability.ArkUI.ArkUI.Full 54 55| Name | Description | 56| --------- | ------------------------------------------------------------ | 57| REMOVED | The callback is invoked when the entire animation is removed once it has finished. | 58| LOGICALLY | The callback is invoked when the animation logically enters the falling state, though it may still be in its long tail state.| 59 60## ExpectedFrameRateRange<sup>11+</sup> 61 62**Atomic service API**: This API can be used in atomic services since API version 12. 63 64| Name | Type | Description | 65|-----|--------|---------| 66| min | number | Expected minimum frame rate.| 67| max | number | Expected maximum frame rate.| 68| expected | number | Expected optimal frame rate.| 69 70## Example 71 72```ts 73// xxx.ets 74@Entry 75@Component 76struct AnimateToExample { 77 @State widthSize: number = 250 78 @State heightSize: number = 100 79 @State rotateAngle: number = 0 80 private flag: boolean = true 81 82 build() { 83 Column() { 84 Button('change size') 85 .width(this.widthSize) 86 .height(this.heightSize) 87 .margin(30) 88 .onClick(() => { 89 if (this.flag) { 90 animateTo({ 91 duration: 2000, 92 curve: Curve.EaseOut, 93 iterations: 3, 94 playMode: PlayMode.Normal, 95 onFinish: () => { 96 console.info('play end') 97 } 98 }, () => { 99 this.widthSize = 150 100 this.heightSize = 60 101 }) 102 } else { 103 animateTo({}, () => { 104 this.widthSize = 250 105 this.heightSize = 100 106 }) 107 } 108 this.flag = !this.flag 109 }) 110 Button('change rotate angle') 111 .margin(50) 112 .rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle }) 113 .onClick(() => { 114 animateTo({ 115 duration: 1200, 116 curve: Curve.Friction, 117 delay: 500, 118 iterations: -1, // The value -1 indicates that the animation is played for an unlimited number of times. 119 playMode: PlayMode.Alternate, 120 onFinish: () => { 121 console.info('play end') 122 }, 123 expectedFrameRateRange: { 124 min: 10, 125 max: 120, 126 expected: 60, 127 } 128 }, () => { 129 this.rotateAngle = 90 130 }) 131 }) 132 }.width('100%').margin({ top: 5 }) 133 } 134} 135``` 136 137 138
