1# Implementing Property Animation
2
3
4ArkUI provides two types of APIs, namely, [animateTo](../reference/apis-arkui/arkui-ts/ts-explicit-animation.md) and [animation](../reference/apis-arkui/arkui-ts/ts-animatorproperty.md), to implement a property animation – an illusion of continuity created by driving component properties to change over time based on animation parameters such as the animation curve.
5
6
7| Property Animation API| Scope| Principle| Use Scenario|
8| -------- | -------- | -------- | -------- |
9| animateTo | UI changes caused by property changes in closures.<br>Transition for appearance and disappearance.| This API is a common function. It animates the differences between the UIs before and after the state variable in the closure is changed.<br>This API can be called multiple times and can be nested.| A single set of animation parameters is used to animate multiple properties.<br>Animations need to be nested.|
10| animation | GUI changes caused by attribute changes bound to components through attribute APIs.| This API identifies the change of the animatable properties of a component and automatically adds an animation.<br>As the API call sequence of the component is from bottom to top, this API applies only to the properties above it.<br>In a component, you can set **animation** for individual properties based on the API call sequence.| Different sets of animation parameters are used to animate different properties.|
11
12## animateTo
13
14
15```
16animateTo(value: AnimateParam, event: () => void): void
17```
18
19Among the parameters of [animateTo](../reference/apis-arkui/arkui-ts/ts-explicit-animation.md), **value** specifies an [AnimateParam object](../reference/apis-arkui/arkui-ts/ts-explicit-animation.md#animateparam) (including duration and [curve](../reference/apis-arkui/js-apis-curve.md#curve)); **event** indicates the closure of the animation. Property animations generated by variable changes within a closure follow the same animation parameters.
20
21> **NOTE**
22>
23> To avoid confusion with **animateTo** instances, it is recommended that you obtain a **UIContext** instance using the [getUIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext) API, and then use the [animateTo](../reference/apis-arkui/js-apis-arkui-UIContext.md#animateto) API to invoke the instance's **animateTo** method.
24
25```ts
26import { curves } from '@kit.ArkUI';
27
28@Entry
29@Component
30struct AnimateToDemo {
31  @State animate: boolean = false;
32  // Step 1: Declare related state variables.
33  @State rotateValue: number = 0; // Rotation angle of component 1.
34  @State translateX: number = 0; // Offset of component 2
35  @State opacityValue: number = 1; // Opacity of component 2.
36
37  // Step 2: Set the declared state variables to the related animatable property APIs.
38  build() {
39    Row() {
40      // Component 1
41      Column() {
42      }
43      .rotate({ angle: this.rotateValue })
44      .backgroundColor('#317AF7')
45      .justifyContent(FlexAlign.Center)
46      .width(100)
47      .height(100)
48      .borderRadius(30)
49      .onClick(() => {
50        this.getUIContext()?.animateTo({ curve: curves.springMotion() }, () => {
51          this.animate = !this.animate;
52          // Step 3: Change the state variables in the closure to update the UI.
53          // You can write any logic that can change the UI, such as array adding and visibility control. The system detects the differences between the new UI and the previous UI and adds animations for the differences.
54          // The rotate property of component 1 is changed. Therefore, a rotate animation is added to component 1.
55          this.rotateValue = this.animate ? 90 : 0;
56          // The opacity property of component 2 is changed. Therefore, an opacity animation is added to component 2.
57          this.opacityValue = this.animate ? 0.6 : 1;
58          // The translate property of component 2 is changed. Therefore, a translate animation is added to component 2.
59          this.translateX = this.animate ? 50 : 0;
60        })
61      })
62
63      // Component 2
64      Column() {
65
66      }
67      .justifyContent(FlexAlign.Center)
68      .width(100)
69      .height(100)
70      .backgroundColor('#D94838')
71      .borderRadius(30)
72      .opacity(this.opacityValue)
73      .translate({ x: this.translateX })
74    }
75    .width('100%')
76    .height('100%')
77    .justifyContent(FlexAlign.Center)
78  }
79}
80```
81
82![en-us_image_0000001599958466](figures/en-us_image_0000001599958466.gif)
83
84
85## animation
86
87Unlike the **animateTo** API, the [animation](../reference/apis-arkui/arkui-ts/ts-animatorproperty.md) API does not need to use a closure. Just add it to the end of the target animatable property, and the API will automatically add a property animation once it detects that the bound property is changed.
88
89
90```ts
91import { curves } from '@kit.ArkUI';
92
93@Entry
94@Component
95struct AnimationDemo {
96  @State animate: boolean = false;
97  // Step 1: Declare related state variables.
98  @State rotateValue: number = 0; // Rotation angle of component 1.
99  @State translateX: number = 0; // Offset of component 2
100  @State opacityValue: number = 1; // Opacity of component 2.
101
102  // Step 2: Set the declared state variables to the related animatable property APIs.
103  build() {
104    Row() {
105      // Component 1
106      Column() {
107      }
108      .opacity(this.opacityValue)
109      .rotate({ angle: this.rotateValue })
110      // Step 3: Enable property animation.
111      .animation({ curve: curves.springMotion() })
112      .backgroundColor('#317AF7')
113      .justifyContent(FlexAlign.Center)
114      .width(100)
115      .height(100)
116      .borderRadius(30)
117      .onClick(() => {
118        this.animate = !this.animate;
119        // Step 4: Change the state variables in the closure to update the UI.
120        // You can write any logic that can change the UI, such as array adding and visibility control. The system detects the differences between the new UI and the previous UI and adds animations for the differences.
121        // The rotate property of component 1 is changed. Therefore, a rotate animation is added to component 1.
122        this.rotateValue = this.animate ? 90 : 0;
123        // The translate property of component 2 is changed. Therefore, a translate animation is added to component 2.
124        this.translateX = this.animate ? 50 : 0;
125        // The opacity property of the parent component <Column> is changed, which results in an opacity change of its child components. Therefore, opacity animations are added to <Column> and its child components.
126        this.opacityValue = this.animate ? 0.6 : 1;
127      })
128
129      // Component 2
130      Column() {
131      }
132      .justifyContent(FlexAlign.Center)
133      .width(100)
134      .height(100)
135      .backgroundColor('#D94838')
136      .borderRadius(30)
137      .opacity(this.opacityValue)
138      .translate({ x: this.translateX })
139      .animation({ curve: curves.springMotion() })
140    }
141    .width('100%')
142    .height('100%')
143    .justifyContent(FlexAlign.Center)
144  }
145}
146```
147
148![en-us_image_0000001649279705](figures/en-us_image_0000001649279705.gif)
149
150> **NOTE**
151> - When an animation is applied to the position or size change of a component, as layout measurement is involved, performance overheads are high. To reduce performance overheads, use the [scale](../reference/apis-arkui/arkui-ts/ts-universal-attributes-transformation.md#scale) attribute instead, whose value change does not involve layout re-measurement. This practice is applicable where the component location and size change continuously, for example, where the component size changes as a response to gestures.
152>
153> - Property animations should be applied to the components that are always visible. For those components whose visibility may change, use the [transition animation](arkts-transition-overview.md).
154>
155> - Avoid using end callbacks for property animations. Property animations are applied to states that have occurred. As such, you do not need to process the end logic. If end callbacks are needed, be sure to correctly handle the data management for continuous operations.
156