HarmonyOS 6 UIContext 关键帧动画 keyframeAnimateTo 使用文档

接口功能

UIContext.keyframeAnimateTo是 HarmonyOS 提供的关键帧动画核心接口，用于实现多阶段连续动画，支持自定义每段动画的时长、属性变化，同时可配置动画循环次数、帧率范围等全局参数，实现比普通动画更灵活的复杂动效。

核心能力：

1. 定义多段连续的关键帧动画（如放大→缩小→放大循环）；
2. 配置动画整体循环次数；
3. 自定义动画执行的帧率范围，优化性能；
4. 绑定 UI 上下文，确保动画与组件生命周期同步。

接口定义与参数

1. 接口签名

keyframeAnimateTo(options:KeyframeAnimateOptions,keyframes:Array<Keyframe>):void

2. 参数详解

（1）KeyframeAnimateOptions（全局动画配置）

控制整个关键帧动画的通用属性，示例中使用核心配置：

• FrameRateRange 子参数：
  • min：最小帧率（示例：10）
  • max：最大帧率（示例：120）
  • expected：目标帧率（示例：60，标准流畅帧率）

（2）keyframes: Array<Keyframe>（关键帧数组）

多段动画的核心配置，数组中每一个对象代表一段独立的动画，按顺序执行。

Keyframe 核心参数：

完整示例

// xxx.etsimport{UIContext}from'@kit.ArkUI';@Entry@Componentstruct KeyframeDemo{@StatemyScale: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的动画event:()=>{this.myScale=1;}}]);})}.width('100%').margin({top:5})}}

运行效果如图：

代码执行流程

1. 组件初始化：aboutToAppear生命周期中获取当前组件的UIContext并赋值，为动画执行做准备；
2. 交互触发：点击圆形组件，先校验UIContext是否有效，无效则打印日志并终止；
3. 初始化状态：重置缩放比例myScale = 1，保证动画起始状态一致；
4. 执行关键帧动画：
   • 全局配置：动画循环3次，帧率 10~120，目标60帧；
   • 第一段（800ms）：组件从原始大小放大到 1.5倍；
   • 第二段（500ms）：组件从1.5倍缩小回原始大小；
   • 「放大→缩小」为一个完整周期，重复执行3次后动画结束。

使用规范

1. UIContext 获取规范

• 必须在组件生命周期aboutToAppear中调用this.getUIContext()获取；
• 执行动画前必须判空，避免空对象导致动画失败（示例中已做判空处理）。

2. 状态变量绑定规范

• 驱动动画的变量（如myScale）必须用@State装饰；
• 仅在event回调中修改该变量，禁止在回调外直接修改干扰动画。

3. 动画参数最佳实践

• 帧率配置：expected推荐 60，保证流畅度；min不低于10，避免卡顿；
• 循环次数：iterations为正整数，设置为0无动画，设置为-1无限循环（官方支持）；
• 时长配置：单段动画时长建议 ≥100ms，避免动画过快无视觉效果。

总结

1. keyframeAnimateTo是多阶段关键帧动画专用接口，依赖UIContext执行；
2. 核心分为全局配置（循环次数、帧率）+关键帧数组（多段动画）；
3. 必须在aboutToAppear获取上下文，在event中修改状态变量驱动动画；

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力