1# Keyframe Animation (keyframeAnimateTo)
2
3The [UIContext](../js-apis-arkui-UIContext.md#uicontext) provides the **keyframeAnimateTo** API to specify several keyframes to implement segment-based animation. In an 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>  This feature is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version.
8>
9>  This API is a member function of the [UIContext](../js-apis-arkui-UIContext.md#uicontext) class and needs to be called through a **UIContext** instance.
10
11keyframeAnimateTo(param: KeyframeAnimateParam, keyframes: Array<KeyframeState>): void
12
13Sets the keyframe animation.
14
15**Atomic service API**: This API can be used in atomic services since API version 12.
16
17**System capability**: SystemCapability.ArkUI.ArkUI.Full
18
19**Parameters**
20
21| Name       | Type                                             | Mandatory| Description                        |
22| ------------ | ---------------------------------------------------- | ------- | ---------------------------- |
23| param        | [KeyframeAnimateParam](#keyframeanimateparam) | Yes     | Global parameters of the keyframe animation.    |
24| keyframes    | Array<[KeyframeState](#keyframestate)>  | Yes     | Array of keyframes.           |
25
26## KeyframeAnimateParam
27
28**Atomic service API**: This API can be used in atomic services since API version 12.
29
30| Name      | Type   | Mandatory| Description                                   |
31| ---------- | ---------- | ------- | ------------------------------------- |
32| delay      | number     | No     | Delay of animation playback, in ms.<br>Default value: **0**, indicating that the playback is not delayed.<br>**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.|
33| 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, +∞)|
34| onFinish   | () => void | No     | Callback invoked when the animation playback is complete. This API is called after the keyframe animation has played for the specified number of times.|
35
36## KeyframeState
37
38**Atomic service API**: This API can be used in atomic services since API version 12.
39
40| Name      | Type                             | Mandatory| Description                                      |
41| ---------- | ------------------------------------ | ------- | ---------------------------------------- |
42| duration   | number                               | Yes     | Duration of the keyframe animation, in ms.<br>Value range: [0, +∞)<br>**NOTE**<br>- If this parameter is set to a value less than 0, the value **0** is used.<br>- Floating-point values will be rounded down to integers. For example, if the value set is 1.2, **1** will be used.|
43| curve      | [Curve](ts-appendix-enums.md#curve)\| string \| [ICurve](../js-apis-curve.md#icurve9) | No | Animation curve used by the keyframe.<br>Default value: **Curve.EaseInOut**<br>**NOTE**<br>Because the[springMotion](../js-apis-curve.md#curvesspringmotion9), [responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9), and [interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10) curves do not have effective duration settings, they are not supported.|
44| event      | () => void                           | Yes     | Closure function of the state at the time of the keyframe, that is, the state to be reached at the time of the keyframe.|
45
46## Example
47
48```ts
49// xxx.ets
50import { UIContext } from '@kit.ArkUI';
51
52@Entry
53@Component
54struct KeyframeDemo {
55  @State myScale: number = 1.0;
56  uiContext: UIContext | undefined = undefined;
57
58  aboutToAppear() {
59    this.uiContext = this.getUIContext?.();
60  }
61
62  build() {
63    Column() {
64      Circle()
65        .width(100)
66        .height(100)
67        .fill("#46B1E3")
68        .margin(100)
69        .scale({ x: this.myScale, y: this.myScale })
70        .onClick(() => {
71          if (!this.uiContext) {
72            console.info("no uiContext, keyframe failed");
73            return;
74          }
75          this.myScale = 1;
76          // Set the keyframe animation to play three times.
77          this.uiContext.keyframeAnimateTo({ iterations: 3 }, [
78            {
79              // The first keyframe animation lasts for 800 ms, during which the scale attribute changes from 1 to 1.5.
80              duration: 800,
81              event: () => {
82                this.myScale = 1.5;
83              }
84            },
85            {
86              // The second keyframe animation lasts for 500 ms, during which the scale attribute changes from 1.5 to 1.
87              duration: 500,
88              event: () => {
89                this.myScale = 1;
90              }
91            }
92          ]);
93        })
94    }.width('100%').margin({ top: 5 })
95  }
96}
97```
98
99![keyframeAnimateTo](figures/keyframeAnimateTo1.gif)
100