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