HarmonyOS：ArkTS 显式动画 animateTo 自学指南

在最近的项目开发工作中，我频繁需要为界面元素添加过渡动画效果，以提升用户体验。在这个过程中，我接触到了 ArkTS 提供的 animateTo 全局显式动画接口。它为由于闭包代码导致的状态变化插入过渡动效提供了便捷的方式，能让布局类的宽高变化以及内容呈现出流畅的动画效果。然而，这个接口的使用细节和相关参数较多，文档虽然详细但较为零散，对于初学者来说理解和掌握起来有一定难度。因此，我决定撰写这篇博客，将自己的学习经验和理解整理成一份自学指南，希望能帮助其他开发者更快速、深入地掌握 animateTo 接口的使用。

一、animateTo 接口概述

animateTo 接口提供了一种显式的方式来为状态变化添加过渡动画。它支持属性动画、布局类的宽高变化动画等。不过需要注意的是，默认情况下内容（如文字、Canvas 内容）会直接到达终点状态，若要让内容跟随宽高变化，可以使用 renderFit 属性进行配置。

支持版本

  • 从 API Version 7 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
  • 从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
  • 从 API version 10 开始，可以通过使用 UIContext 中的 animateTo 来明确 UI 的执行上下文。
  • 从 API version 11 开始，该接口支持在元服务中使用。

接口定义

typescript

animateTo(value: AnimateParam, event: () => void): void
  • 参数说明：
    • value：AnimateParam 类型，必填，用于设置动画效果相关参数。
    • event：() => void 类型，必填，指定动效的闭包函数，在闭包函数中导致的状态变化系统会自动插入过渡动画。

二、AnimateParam 对象详细说明

AnimateParam 对象包含了多个用于配置动画效果的参数，下面是各个参数的详细介绍：

1. duration

  • 类型：number
  • 是否必填：否
  • 描述：动画持续时间，单位为毫秒。默认值为 1000。
    • 在 ArkTS 卡片上最大动画持续时间为 1000 毫秒，若超出则固定为 1000 毫秒。
    • 设置小于 0 的值时按 0 处理。
    • 设置浮点型类型的值时，向下取整。例如，设置值为 1.2，按照 1 处理。

2. tempo

  • 类型：number
  • 是否必填：否
  • 描述：动画播放速度，值越大动画播放越快，值越小播放越慢，为 0 时无动画效果。默认值为 1.0。当设置小于 0 的值时按值为 1 处理。

3. curve

  • 类型：Curve | ICurve9+ | string
  • 是否必填：否
  • 描述：动画曲线。默认值为 Curve.EaseInOut。

4. delay

  • 类型：number
  • 是否必填：否
  • 描述：动画延迟播放时间，单位为 ms（毫秒），默认不延时播放。默认值为 0，取值范围为 (-∞, +∞)。
    • delay >= 0 为延迟播放，delay < 0 表示提前播放。对于 delay < 0 的情况：当 delay 的绝对值小于实际动画时长，动画将在开始后第一帧直接运动到 delay 绝对值的时刻的状态；当 delay 的绝对值大于等于实际动画时长，动画将在开始后第一帧直接运动到终点状态。其中实际动画时长等于单次动画时长乘以动画播放次数。
    • 设置浮点型类型的值时，向下取整。例如，设置值为 1.2，按照 1 处理。

5. iterations

  • 类型：number
  • 是否必填：否
  • 描述：动画播放次数。默认播放一次，设置为 -1 时表示无限次播放。设置为 0 时表示无动画效果。默认值为 1，取值范围为 [-1, +∞)。

6. playMode

  • 类型：PlayMode
  • 是否必填：否
  • 描述：动画播放模式，默认播放完成后重头开始播放。默认值为 PlayMode.Normal。
    • 推荐使用 PlayMode.Normal 和 PlayMode.Alternate，此场景下动画的第一轮是正向播放的。如使用 PlayMode.Reverse 和 PlayMode.AlternateReverse，则动画的第一轮是逆向播放的，在动画刚开始时会跳变到终止状态，然后逆向播放动画。
    • 使用 PlayMode.Alternate 或 PlayMode.AlternateReverse 时，开发者应保证动画最终状态和状态变量的取值一致，即应保证动画的最后一轮是正向播放的。使用 PlayMode.Alternate 时，iterations 应为奇数。使用 PlayMode.AlternateReverse 时，iterations 应为偶数。
    • 不推荐使用 PlayMode.Reverse，此场景下不仅会导致动画刚开始就跳变到终止状态，也会导致动画最终状态和状态变量的取值不同。

7. onFinish

  • 类型：() => void
  • 是否必填：否
  • 描述：动画播放完成回调。UIAbility 从前台切换至后台时会立即结束仍在步进中的有限循环动画，触发播放完成回调。

8. finishCallbackType11+

  • 类型：FinishCallbackType
  • 是否必填：否
  • 描述：在动画中定义 onFinish 回调的类型。默认值为 FinishCallbackType.REMOVED。
    • FinishCallbackType 说明：
      • REMOVED：当整个动画结束并立即删除时，将触发回调。
      • LOGICALLY：当动画在逻辑上处于下降状态，但可能仍处于其长尾状态时，将触发回调。

9. expectedFrameRateRange11+

  • 类型：ExpectedFrameRateRange
  • 是否必填：否
  • 描述：设置动画的期望帧率。
    • ExpectedFrameRateRange 说明：
      • min：期望的最小帧率。
      • max：期望的最大帧率。
      • expected：期望的最优帧率。

三、使用注意事项

  • 在 duration 为 0 的动画闭包函数中改变属性，可以实现停止该属性动画的效果。
  • 如果需要在组件出现时创建动画，可以在 onAppear 中实现动画的创建。不推荐在 aboutToAppear、aboutToDisappear 中调用动画。因为在 aboutToAppear 中调用动画，自定义组件内的 build 还未执行，内部组件还未创建，动画时机过早，动画属性没有初值无法对组件产生动画；执行 aboutToDisappear 时，组件即将销毁，不能在 aboutToDisappear 里面做动画。
  • 也可以使用组件内转场，在组件出现和消失时做动画。组件内转场不支持的属性，可以使用 animateTo 实现组件消失动画效果。

四、示例代码

示例 1：设置动画在 onAppear 中执行

  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct AnimateToExample {
  5.   @State widthSize: number = 300
  6.   @State heightSize: number = 120
  7.   @State rotateAngle: number = 0
  8.   private flag: boolean = true
  9.  
  10.   build() {
  11.     Column() {
  12.       Button('change size')
  13.         .width(this.widthSize)
  14.         .height(this.heightSize)
  15.         .margin(40)
  16.         .onClick(() => {
  17.           if (this.flag) {
  18.             // 建议使用this.getUIContext()?.animateTo()
  19.             animateTo({
  20.               duration: 2500,
  21.               curve: Curve.EaseIn,
  22.               iterations: 4,
  23.               playMode: PlayMode.Normal,
  24.               onFinish: () => {
  25.                 console.info('play end')
  26.               }
  27.             }, () => {
  28.               this.widthSize = 180
  29.               this.heightSize = 80
  30.             })
  31.           } else {
  32.             // 建议使用this.getUIContext()?.animateTo()
  33.             animateTo({}, () => {
  34.               this.widthSize = 300
  35.               this.heightSize = 120
  36.             })
  37.           }
  38.           this.flag = !this.flag
  39.         })
  40.       Button('stop rotating')
  41.         .margin(60)
  42.         .rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle })
  43.         .onAppear(() => {
  44.           // 组件出现时开始做动画
  45.           // 建议使用this.getUIContext()?.animateTo()
  46.           animateTo({
  47.             duration: 1500,
  48.             curve: Curve.EaseIn,
  49.             delay: 600,
  50.             iterations: -1, // 设置-1表示动画无限循环
  51.             playMode: PlayMode.Alternate,
  52.             expectedFrameRateRange: {
  53.               min: 15,
  54.               max: 130,
  55.               expected: 70,
  56.             }
  57.           }, () => {
  58.             this.rotateAngle = 120
  59.           })
  60.         })
  61.         .onClick(() => {
  62.           // 建议使用this.getUIContext()?.animateTo()
  63.           animateTo({ duration: 0 }, () => {
  64.             // this.rotateAngle之前为120，在duration为0的动画中修改属性，可以停止该属性之前的动画，按新设置的属性显示
  65.             this.rotateAngle = 0
  66.           })
  67.         })
  68.     }.width('100%').margin({ top: 10 })
  69.   }
  70. }

示例 2：动画执行结束后组件消失

  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct AttrAnimationExample {
  5.   @State heightSize: number = 120;
  6.   @State isShow: boolean = true;
  7.   @State count: number = 0;
  8.   private isToBottom: boolean = true; // 向下
  9.  
  10.   build() {
  11.     Column() {
  12.       if (this.isShow) {
  13.         Column()
  14.           .width(220)
  15.           .height(this.heightSize)
  16.           .backgroundColor('green')
  17.           .onClick(() => {
  18.             // 建议使用this.getUIContext()?.animateTo()
  19.             animateTo({
  20.               duration: 2200,
  21.               curve: Curve.EaseInOut,
  22.               iterations: 1,
  23.               playMode: PlayMode.Normal,
  24.               onFinish: () => {
  25.                 this.count--;
  26.                 if (this.count == 0 && !this.isToBottom) { // 组件只有在向下做完动画才会消失
  27.                   this.isShow = false;
  28.                 }
  29.               }
  30.             }, () => {
  31.               this.count++;
  32.               if (this.isToBottom) {
  33.                 this.heightSize = 70;
  34.               } else {
  35.                 this.heightSize = 120;
  36.               }
  37.               this.isToBottom = !this.isToBottom;
  38.             })
  39.           })
  40.       }
  41.     }.width('100%').height('100%').margin({ top: 10 })
  42.     .justifyContent(FlexAlign.End)
  43.   }
  44. }

通过以上的介绍和示例，相信你已经对 ArkTS 的 animateTo 接口有了更深入的了解。在实际开发中，你可以根据具体需求灵活配置 AnimateParam 对象的参数，实现各种炫酷的动画效果。

最后如果这篇文章对你有帮助，希望您能关注，点赞，加收藏哦～～～～

注：本文转载自blog.csdn.net的李游Leo的文章"https://blog.csdn.net/liyou041/article/details/146568408"。版权归原作者所有，此博客不拥有其著作权，亦不承担相应法律责任。如有侵权，请联系我们删除。
复制链接
相关推荐
发表评论

评论记录：

未查询到任何数据！