大网数据广告活动
OpenHarmony 设备与应用开发

关键帧动画 (keyframeAnimateTo)

· 52CE 我爱测

在UIContext中提供keyframeAnimateTo接口来指定若干个关键帧状态,实现分段的动画。同属性动画,布局类改变宽高的动画,内容都是直接到终点状态,例如文字、Canvas的内容等,如果要内容跟随宽高变化,可以使用renderFit属性配置。

关键帧动画 (keyframeAnimateTo)

在UIContext中提供keyframeAnimateTo接口来指定若干个关键帧状态,实现分段的动画。同属性动画,布局类改变宽高的动画,内容都是直接到终点状态,例如文字、Canvas的内容等,如果要内容跟随宽高变化,可以使用renderFit属性配置。

说明:

  • 从API version 11开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

  • 本模块接口仅可在Stage模型下使用。

  • 该接口为UIContext类的成员函数,需要通过UIContext实例对象调用。

keyframeAnimateTo(param: KeyframeAnimateParam, keyframes: Array<KeyframeState>): void

设置关键帧动画。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
param KeyframeAnimateParam 是 关键帧动画的整体动画参数。
keyframes Array<KeyframeState> 是 所有的关键帧状态。

KeyframeAnimateParam对象说明

动画选项设置。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
delay number 否 是 动画的整体延时时间,单位为ms(毫秒),默认不延时播放。
默认值:0
说明:
 delay>=0为延迟播放,delay<0表示提前播放。对于delay<0的情况:当delay的绝对值小于实际动画时长,动画将在开始后第一帧直接运动到delay绝对值的时刻的状态;当delay的绝对值大于等于实际动画时长,动画将在开始后第一帧直接运动到终点状态。其中实际动画时长等于单次动画时长乘以动画播放次数。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
iterations number 否 是 动画播放次数。默认播放一次,设置为-1时表示无限次播放。设置为0时表示无动画效果。
默认值:1
取值范围:[-1, +∞)
说明:
- 设置浮点型类型的值时,向下取整。例如,设置值为1.2,按照1处理。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
onFinish () => void 否 是 动画播放完成回调。当keyframe动画所有次数播放完成后调用。在设置的开发者选项中关闭过渡动画,或UIAbility从前台切换至后台时会立即结束仍在播放中的有限循环keyframe动画,触发播放完成回调。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
expectedFrameRateRange19+ ExpectedFrameRateRange 否 是 设置动画的期望帧率。
默认值:{min:0, max:0, expected:0},即跟随应用帧率。
说明:
开发者通过设置有效的期望帧率后,系统会收集设置的请求帧率,进行决策和分发,在渲染管线上进行分频,尽量能够满足开发者的期望帧率。开发者设置的期望帧率值不能代表最终实际效果,会受限于系统能力和屏幕刷新率。
原子化服务API: 从API version 19开始,该接口支持在原子化服务中使用。

KeyframeState对象说明

设置关键帧选项。

系统能力: SystemCapability.ArkUI.ArkUI.Full

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

名称 类型 只读 可选 说明
duration number 否 否 该段关键帧动画的持续时间,单位为毫秒。
取值范围:[0, +∞)
说明:
- 设置小于0的值时按0处理。
- 设置浮点型的值时,向下取整。例如,设置值为1.2,按照1处理。
curve Curve| string | ICurve 否 是 该关键帧使用的动画曲线。
推荐以Curve或ICurve形式指定。
当类型为string时,为动画插值曲线,取值参考AnimateParam的curve参数。
默认值:Curve.EaseInOut
说明:
由于springMotion、responsiveSpringMotion、interpolatingSpring曲线时长不生效,故不支持这三种曲线。
event () => void 否 否 指定在该关键帧时刻状态的闭包函数,即在该关键帧时刻要达到的状态。

示例

该示例主要演示如何通过keyframeAnimateTo来设置关键帧动画。

// xxx.ets

@Entry
@Component
struct KeyframeDemo {
  @State myScale: number = 1.0;
  uiContext: UIContext | undefined = undefined;

  aboutToAppear() {
    this.uiContext = this.getUIContext?.();
  }

  build() {
    Column() {
      Circle()
        .width(100)
        .height(100)
        .fill("#46B1E3")
        .margin(100)
        .scale({ x: this.myScale, y: this.myScale })
        .onClick(() => {
          if (!this.uiContext) {
            console.info("no uiContext, keyframe failed");
            return;
          }
          this.myScale = 1;
          // 设置关键帧动画整体播放3次
          this.uiContext.keyframeAnimateTo({
              iterations: 3,
              expectedFrameRateRange: {
                min: 10,
                max: 120,
                expected: 60,
              }
            }, [
            {
              // 第一段关键帧动画时长为800ms,scale属性做从1到1.5的动画
              duration: 800,
              event: () => {
                this.myScale = 1.5;
              }
            },
            {
              // 第二段关键帧动画时长为500ms,scale属性做从1.5到1的动画
              duration: 500,
              event: () => {
                this.myScale = 1;
              }
            }
          ]);
        })
    }.width('100%').margin({ top: 5 })
  }
}

[图示请参阅官方原文]

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。