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

php 复制代码
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​​ 中执行

less 复制代码
// xxx.ets
@Entry
@Component
struct AnimateToExample {
  @State widthSize: number = 300
  @State heightSize: number = 120
  @State rotateAngle: number = 0
  private flag: boolean = true

  build() {
    Column() {
      Button('change size')
        .width(this.widthSize)
        .height(this.heightSize)
        .margin(40)
        .onClick(() => {
          if (this.flag) {
            // 建议使用this.getUIContext()?.animateTo()
            animateTo({
              duration: 2500,
              curve: Curve.EaseIn,
              iterations: 4,
              playMode: PlayMode.Normal,
              onFinish: () => {
                console.info('play end')
              }
            }, () => {
              this.widthSize = 180
              this.heightSize = 80
            })
          } else {
            // 建议使用this.getUIContext()?.animateTo()
            animateTo({}, () => {
              this.widthSize = 300
              this.heightSize = 120
            })
          }
          this.flag = !this.flag
        })
      Button('stop rotating')
        .margin(60)
        .rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle })
        .onAppear(() => {
          // 组件出现时开始做动画
          // 建议使用this.getUIContext()?.animateTo()
          animateTo({
            duration: 1500,
            curve: Curve.EaseIn,
            delay: 600,
            iterations: -1, // 设置-1表示动画无限循环
            playMode: PlayMode.Alternate,
            expectedFrameRateRange: {
              min: 15,
              max: 130,
              expected: 70,
            }
          }, () => {
            this.rotateAngle = 120
          })
        })
        .onClick(() => {
          // 建议使用this.getUIContext()?.animateTo()
          animateTo({ duration: 0 }, () => {
            // this.rotateAngle之前为120,在duration为0的动画中修改属性,可以停止该属性之前的动画,按新设置的属性显示
            this.rotateAngle = 0
          })
        })
    }.width('100%').margin({ top: 10 })
  }
}

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

kotlin 复制代码
// xxx.ets
@Entry
@Component
struct AttrAnimationExample {
  @State heightSize: number = 120;
  @State isShow: boolean = true;
  @State count: number = 0;
  private isToBottom: boolean = true; // 向下

  build() {
    Column() {
      if (this.isShow) {
        Column()
          .width(220)
          .height(this.heightSize)
          .backgroundColor('green')
          .onClick(() => {
            // 建议使用this.getUIContext()?.animateTo()
            animateTo({
              duration: 2200,
              curve: Curve.EaseInOut,
              iterations: 1,
              playMode: PlayMode.Normal,
              onFinish: () => {
                this.count--;
                if (this.count == 0 && !this.isToBottom) { // 组件只有在向下做完动画才会消失
                  this.isShow = false;
                }
              }
            }, () => {
              this.count++;
              if (this.isToBottom) {
                this.heightSize = 70;
              } else {
                this.heightSize = 120;
              }
              this.isToBottom = !this.isToBottom;
            })
          })
      }
    }.width('100%').height('100%').margin({ top: 10 })
    .justifyContent(FlexAlign.End)
  }
}

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

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

相关推荐
鸿蒙布道师6 小时前
鸿蒙NEXT开发Base64工具类(ArkTs)
android·ios·华为·harmonyos·arkts·鸿蒙系统·huawei
The 旺7 小时前
《HarmonyOS Next开发实战:从零构建响应式Todo应用的基石》
华为·harmonyos
Industio_触觉智能7 小时前
鸿蒙北向开发OpenHarmony5.0 DevEco Studio开发工具安装与配置
harmonyos·鸿蒙系统·openharmony·开源鸿蒙·鸿蒙开发·嵌入式开发板
秋叶先生_12 小时前
HarmonyOS NEXT——【鸿蒙监听网络状态变化】
华为·harmonyos·鸿蒙
东林知识库12 小时前
鸿蒙NEXT小游戏开发:围住神经猫
harmonyos
zacksleo12 小时前
鸿蒙Flutter开发故事:不,你不需要鸿蒙化
flutter·harmonyos
别说我什么都不会14 小时前
OpenHarmony解读之设备认证:sts协议-客户端发起sts end请求
物联网·嵌入式·harmonyos
悬空八只脚17 小时前
React-Native开发鸿蒙NEXT-本地与沙盒加载bundle
harmonyos
鸿蒙布道师17 小时前
鸿蒙NEXT开发日志工具类(ArkTs)
android·ios·华为·harmonyos·arkts·鸿蒙系统·huawei
90后的晨仔17 小时前
HarmonyOS的页面生命周期 和 组件生命周期
harmonyos