1# 关键帧动画 (keyframeAnimateTo)
2
3在[UIContext](../js-apis-arkui-UIContext.md#uicontext)中提供keyframeAnimateTo接口来指定若干个关键帧状态，实现分段的动画。同属性动画，布局类改变宽高的动画，内容都是直接到终点状态，例如文字、[Canvas](ts-components-canvas-canvas.md)的内容等，如果要内容跟随宽高变化，可以使用[renderFit](ts-universal-attributes-renderfit.md)属性配置。
4
5>  **说明：**
6>
7>  从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9>  该接口为[UIContext](../js-apis-arkui-UIContext.md#uicontext)类的成员函数，需要通过UIContext实例对象调用。
10
11keyframeAnimateTo(param: KeyframeAnimateParam, keyframes: Array<KeyframeState>): void
12
13设置关键帧动画。
14
15**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
16
17**系统能力：** SystemCapability.ArkUI.ArkUI.Full
18
19**参数：**
20
21| 参数名        | 类型                                              | 必填 | 描述                         |
22| ------------ | ---------------------------------------------------- | ------- | ---------------------------- |
23| param        | [KeyframeAnimateParam](#keyframeanimateparam对象说明) | 是      | 关键帧动画的整体动画参数。     |
24| keyframes    | Array<[KeyframeState](#keyframestate对象说明)>  | 是      | 所有的关键帧状态。            |
25
26## KeyframeAnimateParam对象说明
27
28**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
29
30| 名称       | 参数类型    | 是否必填 | 描述                                    |
31| ---------- | ---------- | ------- | ------------------------------------- |
32| delay      | number     | 否      | 动画的整体延时时间，单位为ms(毫秒)，默认不延时播放。<br/>默认值：0<br/>**说明：** <br/>&nbsp;delay>=0为延迟播放，delay<0表示提前播放。对于delay<0的情况：当delay的绝对值小于实际动画时长，动画将在开始后第一帧直接运动到delay绝对值的时刻的状态；当delay的绝对值大于等于实际动画时长，动画将在开始后第一帧直接运动到终点状态。其中实际动画时长等于单次动画时长乘以动画播放次数。 |
33| iterations | number     | 否      | 动画播放次数。默认播放一次，设置为-1时表示无限次播放。设置为0时表示无动画效果。<br/>默认值：1 <br/>取值范围：[-1, +∞) |
34| onFinish   | () => void | 否      | 动画播放完成回调。当keyframe动画所有次数播放完成后调用。UIAbility从前台切换至后台时会立即结束仍在步进中的有限循环keyframe动画，触发播放完成回调。 |
35
36## KeyframeState对象说明
37
38**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
39
40| 名称       | 参数类型                              | 是否必填 | 描述                                       |
41| ---------- | ------------------------------------ | ------- | ---------------------------------------- |
42| duration   | number                               | 是      | 该段关键帧动画的持续时间，单位为毫秒。<br/>取值范围：[0, +∞)<br/>**说明：**<br/>-&nbsp;设置小于0的值时按0处理。<br/>-&nbsp;设置浮点型类型的值时，向下取整。例如，设置值为1.2，按照1处理。 |
43| curve      | [Curve](ts-appendix-enums.md#curve)\|&nbsp;string&nbsp;\|&nbsp;[ICurve](../js-apis-curve.md#icurve) | 否  | 该关键帧使用的动画曲线。<br/>默认值：Curve.EaseInOut<br/>**说明：**<br/>由于[springMotion](../js-apis-curve.md#curvesspringmotion9)、[responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9)、[interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10)曲线时长不生效，故不支持这三种曲线。 |
44| event      | () => void                           | 是      | 指定在该关键帧时刻状态的闭包函数，即在该关键帧时刻要达到的状态。 |
45
46## 示例
47
48该示例主要演示如何通过keyframeAnimateTo来设置关键帧动画。
49
50```ts
51// xxx.ets
52import { UIContext } from '@kit.ArkUI';
53
54@Entry
55@Component
56struct KeyframeDemo {
57  @State myScale: number = 1.0;
58  uiContext: UIContext | undefined = undefined;
59
60  aboutToAppear() {
61    this.uiContext = this.getUIContext?.();
62  }
63
64  build() {
65    Column() {
66      Circle()
67        .width(100)
68        .height(100)
69        .fill("#46B1E3")
70        .margin(100)
71        .scale({ x: this.myScale, y: this.myScale })
72        .onClick(() => {
73          if (!this.uiContext) {
74            console.info("no uiContext, keyframe failed");
75            return;
76          }
77          this.myScale = 1;
78          // 设置关键帧动画整体播放3次
79          this.uiContext.keyframeAnimateTo({ iterations: 3 }, [
80            {
81              // 第一段关键帧动画时长为800ms，scale属性做从1到1.5的动画
82              duration: 800,
83              event: () => {
84                this.myScale = 1.5;
85              }
86            },
87            {
88              // 第二段关键帧动画时长为500ms，scale属性做从1.5到1的动画
89              duration: 500,
90              event: () => {
91                this.myScale = 1;
92              }
93            }
94          ]);
95        })
96    }.width('100%').margin({ top: 5 })
97  }
98}
99```
100
101![keyframeAnimateTo](figures/keyframeAnimateTo1.gif)
102