HarmonyOS 6 ArkUI animateToImmediately 显式动画使用文档

核心 API

1. animateToImmediately

• 作用：立即执行动画，不等待下一帧同步，动画指令立即生效。
• 特点：执行时机比普通animateTo更精准，适合串联、延时、分步动画。
• 语法：

animateToImmediately(options,animationCallback)

2. animateTo（普通显式动画）

• 等待 Vsync 同步后执行，适合常规动画。

示例代码逐模块解析

1 状态变量定义

@StatewidthSize:number=250;// 宽度@StateheightSize:number=100;// 高度@StateopacitySize:number=0;// 透明度（初始隐藏）privateflag:boolean=true;// 切换标记

• 初始状态：宽250、高100、透明度0（隐藏）

2 动画组件

Column().width(this.widthSize).height(this.heightSize).backgroundColor(Color.Red).opacity(this.opacitySize)

• 红色盒子，尺寸、透明度由@State驱动动画。

3 点击事件

.onClick(()=>{if(this.flag){// 第一段：立即执行 → 透明度从0→1（淡入）animateToImmediately({delay:0,duration:1000},()=>{this.opacitySize=1;})// 第二段：延迟1秒执行 → 宽高缩小this.getUIContext()?.animateTo({delay:1000,duration:1000},()=>{this.widthSize=150;this.heightSize=60;})}else{// 第一段：立即执行 → 宽高放大animateToImmediately({delay:0,duration:1000},()=>{this.widthSize=250;this.heightSize=100;})// 第二段：延迟1秒执行 → 透明度淡出this.getUIContext()?.animateTo({delay:1000,duration:1000},()=>{this.opacitySize=0;})}this.flag=!this.flag;})

执行逻辑

正向动画（flag = true）

1. animateToImmediately：立即执行，透明度 0 → 1（1秒）
2. animateTo：延迟1秒后执行，宽高缩小（1秒）
   →先淡入，再缩小

反向动画（flag = false）

1. animateToImmediately：立即执行，宽高放大（1秒）
2. animateTo：延迟1秒后执行，透明度 1 → 0（1秒）
   →先放大，再淡出

运行效果

1. 初始：红色方块隐藏（透明度0）
2. 点击按钮：
   • 方块立即淡入（1秒）
   • 淡入完成后自动缩小（1秒）
3. 再次点击：
   • 方块立即放大（1秒）
   • 放大完成后淡出隐藏（1秒）
4. 全程时序精准、无卡顿、无等待

运行结果如图：

完整代码

// xxx.ets@Entry@Componentstruct AnimateToImmediatelyExample{@StatewidthSize:number=250;@StateheightSize:number=100;@StateopacitySize:number=0;privateflag:boolean=true;build(){Column(){Column().width(this.widthSize).height(this.heightSize).backgroundColor(Color.Red).opacity(this.opacitySize)Button('change size').margin(30).onClick(()=>{if(this.flag){animateToImmediately({delay:0,duration:1000},()=>{this.opacitySize=1;})this.getUIContext()?.animateTo({delay:1000,duration:1000},()=>{this.widthSize=150;this.heightSize=60;})}else{animateToImmediately({delay:0,duration:1000},()=>{this.widthSize=250;this.heightSize=100;})this.getUIContext()?.animateTo({delay:1000,duration:1000},()=>{this.opacitySize=0;})}this.flag=!this.flag;})}.width('100%').margin({top:5})}}

总结

1. animateToImmediately 立即执行
   不等待 Vsync，指令发出立刻执行，时序精度更高。

2. 必须放在 onClick 等交互事件中
   显式动画只能在事件回调中触发。

3. delay 与 duration 单位均为毫秒
   delay：动画等待时间
   duration：动画执行时间

4. 与 animateTo 混用可实现串联动画
   本示例是官方推荐的分步动画标准写法。

5. @State 变量必须在动画回调中修改
   才能触发属性动画。

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