鸿蒙新特性实战：@ohos.animator 打造逐帧动画实验室

前言动画是提升应用质感的关键但不同的动画需求需要不同的工具。HarmonyOS NEXT 提供了两套截然不同的动画机制animateTo属性隐式动画修改组件属性时自动补间用起来极简但它是一次性的——触发即执行你无法在动画进行到一半时暂停、反转也拿不到每一帧的插值。ohos.animatorAnimator 逐帧动画一个命令式的动画对象可以play播放、pause暂停、reverse反转、cancel取消并通过onFrame回调在每一帧拿到当前插值。它把时间驱动的数值变化这件事完全交给你掌控。当你需要精确控制动画的生命周期或者要用动画驱动那些不是组件属性的东西比如 Canvas 绘制、复杂的自定义状态、多个元素的联动时Animator才是正确答案。本文用一个可交互的逐帧动画实验室把ohos.animator讲透一个由onFrame逐帧驱动的小球和进度条配合播放/暂停/反转/重置的完整控制以及缓动曲线、时长、循环次数的实时调节。全文含完整可运行代码适合想深入掌握 HarmonyOS 动画体系的中级开发者。一、Animator 与 animateTo 的本质区别先把两者的定位讲清楚这决定了你该在什么场景用哪个。维度animateToAnimator形态函数包裹属性修改对象有生命周期方法驱动方式修改组件属性触发onFrame回调逐帧给值生命周期控制无一次性执行play / pause / reverse / cancel拿到中间值不能每帧都能拿到典型用途简单属性过渡位移、缩放、透明度自定义绘制、非属性动画、可交互动画一句话总结animateTo 让属性变化变得平滑Animator 让你拿到随时间变化的数值怎么用这个数值完全由你决定。前者面向属性后者面向数据。举个例子做一个进度环从 0 走到 100%如果用 Canvas 手绘弧线那当前百分比不是任何组件的属性animateTo无能为力而Animator的onFrame(value)正好把 0→100 的插值一帧帧喂给你去绘制。二、Animator 核心 API2.1 创建推荐通过UIContext创建 Animatorimport{AnimatorResult,AnimatorOptions}fromkit.ArkUI;constoptions:AnimatorOptions{duration:2000,easing:ease-in-out,delay:0,fill:forwards,direction:normal,iterations:1,begin:0,end:100};constanim:AnimatorResultthis.getUIContext().createAnimator(options);2.2 AnimatorOptions 参数字段说明duration动画时长mseasing缓动曲线linear/ease/ease-in/ease-out/ease-in-out/ 贝塞尔delay延迟开始msfill结束后的停留状态none/forwards/backwards/bothdirection方向normal/reverse/alternate/alternate-reverseiterations循环次数-1 为无限begin插值起始值end插值结束值begin和end定义了onFrame回调值的范围。本文设为 0~100正好当百分比用。2.3 回调与控制方法anim.onFrame(value:number){/* 每帧的插值 */};anim.onFinish(){/* 播放完成 */};anim.onCancel(){/* 被取消 */};anim.onRepeat(){/* 每次循环重复 */};anim.play();// 播放anim.pause();// 暂停anim.reverse();// 反向播放anim.cancel();// 取消回到初始anim.update(opts);// 更新参数anim.finish();// 直接结束到终点onFrame是核心——动画运行期间系统按屏幕刷新率高频调用它把当前插值传给你。你在这里更新State界面就动起来了。三、实战:逐帧动画实验室3.1 状态与 Animator 持有import{router,AnimatorResult,AnimatorOptions}fromkit.ArkUI;import{FontSize,Spacing}from../common/Constants;EntryComponentstruct FrameAnimatorLabPage{StateframeValue:number0;// onFrame 给的当前值StatestatusText:string就绪;StateeasingIndex:number4;Stateduration:number2000;Stateiterations:number1;privateeasings:string[][linear,ease,ease-in,ease-out,ease-in-out];privateanim:AnimatorResult|undefinedundefined;}注意anim是一个普通成员不是State因为 Animator 对象本身不参与 UI 渲染真正驱动界面的是它回调里更新的frameValue。3.2 创建与参数更新把创建和更新合并到一个方法里首次调用时创建并绑定回调之后只更新参数。这样切换缓动曲线、时长时不必重复创建对象privatebuildOptions():AnimatorOptions{constoptions:AnimatorOptions{duration:this.duration,easing:this.easings[this.easingIndex],delay:0,fill:forwards,direction:normal,iterations:this.iterations,begin:0,end:100};returnoptions;}// 首次创建 Animator 并绑定帧回调之后仅更新参数privateensureAnimator():void{if(this.animundefined){constcreated:AnimatorResultthis.getUIContext().createAnimator(this.buildOptions());created.onFrame(value:number){this.frameValueMath.round(value);};created.onFinish(){this.statusText播放完成;};created.onCancel(){this.statusText已取消;};created.onRepeat(){this.statusText循环中;};this.animcreated;}else{this.anim.update(this.buildOptions());}}onFrame里把插值四舍五入后写进frameValue触发界面刷新。这就是逐帧动画的核心闭环系统给值 → 更新状态 → 界面重绘。3.3 生命周期控制四个控制方法直接映射到 Animator 的能力privateplay():void{this.ensureAnimator();if(this.anim!undefined){this.anim.play();this.statusText播放中;}}privatepause():void{if(this.anim!undefined){this.anim.pause();this.statusText已暂停;}}privatereverse():void{this.ensureAnimator();if(this.anim!undefined){this.anim.reverse();this.statusText反向播放;}}privatereset():void{if(this.anim!undefined){this.anim.cancel();}this.frameValue0;this.statusText就绪;}这正是 Animator 相对 animateTo 的杀手锏——你能在动画运行到 47% 时按下暂停它就停在 47按反向它从 47 往回走。animateTo 做不到这种精细控制。注意用if (this.anim ! undefined)做判空而不是this.anim!非空断言因为 ArkTS 对非空断言的支持有限显式判空更稳妥。3.4 页面离开时清理动画对象持有系统资源页面销毁时要取消避免泄漏aboutToDisappear():void{if(this.anim!undefined){this.anim.cancel();}}3.5 用帧值驱动可视元素拿到frameValue0~100后可以驱动任意界面元素。实验室里用了三种呈现大数字直接显示当前帧值Text(this.frameValue.toString()).fontSize(64).fontColor(#FFFFFF).fontWeight(FontWeight.Bold)进度填充条用百分比宽度width支持百分比字符串Row().width(this.frameValue%).height(10).borderRadius(5).linearGradient({angle:90,colors:[[#34D399,0],[#059669,1]]})水平移动的小球用layoutWeight巧妙定位——左右两个空 Row 按frameValue和100 - frameValue分配权重把小球挤到对应位置Row(){Row().layoutWeight(this.frameValue0?this.frameValue:0.001)Column().width(28).height(28).borderRadius(14).backgroundColor(#059669)Row().layoutWeight(this.frameValue100?100-this.frameValue:0.001)}这个技巧不需要知道容器的具体宽度纯靠权重比例定位frameValue从 0 到 100小球就从最左平滑滑到最右。layoutWeight为 0 时用0.001兜底避免某些边界情况下的布局异常。3.6 参数实时调节缓动曲线用一排按钮切换切换后调ensureAnimator()更新下次播放生效ForEach(this.easings,(e:string,index:number){Text(e).backgroundColor(this.easingIndexindex?#059669:#D1FAE5).onClick((){this.easingIndexindex;this.ensureAnimator();})})时长和循环次数用滑块同样在改变时更新参数。切到ease-in-out播放你会看到小球两头慢、中间快切linear则匀速ease-out是先快后慢。这直观展示了缓动曲线对动画节奏的影响。四、几个实战要点与坑4.1 onFrame 里只做轻量更新onFrame每秒可能被调用 60~120 次里面只应做轻量的状态赋值别做复杂计算、日志、网络等操作否则会掉帧。需要复杂计算时先在动画外算好onFrame里只做插值映射。4.2 记得在页面销毁时 cancelAnimator 持有系统级动画资源aboutToDisappear里务必cancel()。忘记清理页面反复进出会累积泄漏甚至出现看不见的动画还在跑。4.3 update 后需重新 play调用update(options)只更新参数不会自动重新播放。改完参数要再play()才生效。本文在改参数时先ensureAnimator()更新用户下次点播放即用新参数。4.4 判空优于非空断言ArkTS 严格模式下this.anim!.play()这种非空断言可能不被支持或触发告警。统一用if (this.anim ! undefined)判空更稳更清晰。4.5 begin/end 决定回调值域onFrame的值域完全由begin/end决定。想要角度就设 0~360想要像素位移就设 0~屏宽想要百分比就设 0~100。灵活利用这一点能省去自己做数值映射的麻烦。五、典型应用场景Canvas 自定义动画用onFrame的插值驱动画布重绘实现进度环、波浪、粒子等属性动画覆盖不到的效果可暂停/可拖拽的动画需要用户能中途暂停、回退的引导动画、教程演示数值滚动数字从 0 滚动到目标值计数器、金额、评分多元素联动一个 Animator 的插值同时驱动多个元素按不同规律运动物理感交互配合缓动曲线模拟加速、减速、回弹。六、小结本文以逐帧动画实验室为载体系统讲解了 HarmonyOS NEXT 的ohos.animator核心定位命令式动画对象通过onFrame逐帧回调交出插值可 play / pause / reverse / cancel 精细控制生命周期AnimatorOptionsduration/easing/iterations/begin/end等参数定义动画行为与值域与 animateTo 的区别animateTo 面向属性、一次性Animator 面向数据、可控制、可拿中间值工程要点onFrame 保持轻量、页面销毁要 cancel、update 后需重新 play、判空优于非空断言实用技巧用layoutWeight比例定位小球、用百分比宽度做进度条、用begin/end直接定义值域。Animator 是 HarmonyOS 动画体系里更底层、更灵活的那一半。当 animateTo 的简单属性过渡不够用时Animator 让你拿回对时间和数值的完全掌控去实现任何你能想象的动画。