HarmonyOS鸿蒙Next中什么是animateTo？如何去使用？

HarmonyOS鸿蒙Next中什么是animateTo？如何去使用？ 在之前的问答中，我们简单的了解了属性动画，知道了属性动画有两种实现方式，一种是animation，另一种是animateTo，之前的案例基本上也都是使用animation来实现的，其实在案例中，大家也都发现了，animation是组件的通用属性，也就是说是和组件进行绑定的，如果想让多个组件进行动画播放，那么就需要绑定多个组件。有没有一种方式，执行起来，可以适用于多个可动画属性配置相同动画参数的动画呢，答案是必须有的，这就是animateTo。

3 回复

举一个很简单的案例，让两个组件，同时在X轴方向，平移100，用时1秒。

@Entry
@Component
struct Index {
  @State translateX: number = 0

  build() {
    RelativeContainer() {

      Text("1")
        .width(50)
        .height(50)
        .textAlign(TextAlign.Center)
        .backgroundColor(Color.Red)
        .translate({ x: this.translateX })
        .margin({ top: 100 })
        .id("view1")
        .alignRules({
          top: { anchor: "__container__", align: VerticalAlign.Top },
          middle: { anchor: "__container__", align: HorizontalAlign.Center }
        })

      Text("2")
        .width(50)
        .height(50)
        .textAlign(TextAlign.Center)
        .backgroundColor(Color.Red)
        .translate({ x: this.translateX })
        .margin({ top: 100 })
        .alignRules({
          top: { anchor: "view1", align: VerticalAlign.Top },
          middle: { anchor: "__container__", align: HorizontalAlign.Center }
        })

      Button("点击")
        .margin({ top: 10 })
        .onClick(() => {
          animateTo({ duration: 1000 }, () => {
            this.translateX = 100
          })
        })
        .alignRules({
          center: { anchor: "__container__", align: VerticalAlign.Center },
          middle: { anchor: "__container__", align: HorizontalAlign.Center }
        })
    }
    .height('100%')
    .width('100%')
  }
}

动画效果：

从上边的案例中我们可以看到，animateTo是一个全局实现属性动画的方式，它可以应用于多个组件之间，但是呢使用它，有两个需要注意的点，那就是不推荐在aboutToAppear、aboutToDisappear中调用动画；在aboutToAppear中，是因为自定义组件内的build还未执行，内部组件还未创建，动画时机过早，动画属性没有初值无法对组件产生动画；aboutToDisappear原因是，组件即将销毁，不能在aboutToDisappear里面做动画。

相关参数

通过源码，我们看到有两个参数，第一个参数是AnimateParam，用于控制动画执行的相关属性，比如延时，时间，速度等等，第二个参数是一个闭包回调函数，用于改变动画属性。

declare function animateTo(value: AnimateParam, event: () => void): void;

AnimateParam参数

名称 类型 是否必填 描述
duration number 否 动画持续时间，单位为毫秒。默认值：1000
tempo number 否 动画播放速度，值越大动画播放越快，值越小播放越慢，为0时无动画效果。默认值：1.0
curve Curve| ICurve9+|string 否 动画曲线。默认值：Curve.EaseInOut
delay number 否 动画延迟播放时间，单位为ms(毫秒)，默认不延时播放。
默认值：0
iterations number 否 动画播放次数。默认播放一次，设置为-1时表示无限次播放。设置为0时表示无动画效果。默认值：1
playMode PlayMode 否 动画播放模式，默认播放完成后重头开始播放。
默认值：PlayMode.Normal
onFinish () => void 否 动画播放完成回调。
finishCallbackType11+ FinishCallbackType 否 在动画中定义onFinish回调的类型。
默认值：FinishCallbackType.REMOVED
expectedFrameRateRange11+ ExpectedFrameRateRange 否 设置动画的期望帧率。

以上的每个参数，都可能在特定的情况下进行运用。

duration参数，不多说了，就是执行动画的总体时间，这个也是实际属性动画中最常见的一个属性；像tempo，delay，iterations，playMode，onFinish都是毕竟常见而且简单的属性，就不过多赘述了，我们重点概述下剩下的几个参数。

curve，动画执行的曲线，走的是贝塞尔曲线形式，可设置的类型比较多，默认值是Curve.EaseInOut，也就是动画以低速开始和结束，除此之外，还有Linear，表示动画从头到尾的速度都是相同的；Ease：表示动画以低速开始，然后加快，在结束前变慢；EaseIn：表示动画以低速开始；EaseOut：表示动画以低速结束；FastOutSlowIn：标准曲线，LinearOutSlowIn：减速曲线；FastOutLinearIn：加速曲线；ExtremeDeceleration：急缓曲线；Sharp：锐利曲线；Rhythm：节奏曲线；Smooth：平滑曲线；Friction：阻尼曲线。

playMode，可以设置动画播放模式，目前提供的有四种播放模式，默认是Normal也就是正向播放，Reverse是反向播放，Alternate毕竟好玩，可以让动画在奇数次（1、3、5…）正向播放，在偶数次（2、4、6…）反向播放；AlternateReverse是和Alternate相反的，动画在奇数次（1、3、5…）反向播放，在偶数次（2、4、6…）正向播放。

在Api11之后的版本，又增加了两个属性，分别是finishCallbackType和expectedFrameRateRange，前者可以定义动画结束时回调的类型，后者可以设置动画执行的帧率，帧率包括，最大，最小和最优，可以根据需求进行设置。

相关总结

在实际的开发中，应该遵循规范，正确的使用属性动画animateTo，切莫在轮询中使用，否则就会造成本不属当前的动画进行执行，造成UI错误，还有一点需要注意，那就是直接使用animateTo可能导致实例不明确的问题，建议使用getUIContext获取UIContext实例，并使用animateTo调用绑定实例的animateTo。

更多关于HarmonyOS鸿蒙Next中什么是animateTo？如何去使用？的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


animateTo是HarmonyOS中的动画API，用于实现组件属性变化的平滑过渡效果。

使用方式：在ArkTS中调用animateTo函数，传入目标属性和动画参数（如时长、曲线）。例如：

animateTo({
  duration: 1000,
  curve: Curve.EaseIn
}, () => {
  this.width = 200
})

该API支持同步更新多个状态变量，并自动生成过渡动画。

animateTo 是 HarmonyOS Next 中 ArkUI 提供的一个全局动画方法，用于同时驱动多个组件的多个属性，按照统一的动画参数（时长、曲线等）执行动画过渡。它解决了 animation 属性需要逐个绑定组件的问题，更适合对一组属性或组件进行协同动画控制。

核心概念：

  • 全局动画执行器：它不是组件的属性，而是一个 API 函数。
  • 闭包内的状态驱动：在 animateTo 的闭包（{}）内，改变状态变量的值，所有依赖于这些状态变量的 UI 属性都会自动以动画形式过渡到新值。
  • 统一配置：只需在 animateTo 函数调用时设置一次动画参数（如 duration, curve），这些参数将应用于该次动画触发的所有属性变化。

基本语法：

import { animateTo } from '@kit.ArkUI';

animateTo(
  { 
    duration: 1000, // 动画时长，单位ms
    curve: Curve.EaseInOut, // 动画曲线
    delay: 100, // 延迟开始，可选
    iterations: 1, // 播放次数，可选
    playMode: PlayMode.Normal // 播放模式，可选
    // ... 其他参数
  }, 
  () => {
    // 在此闭包内，改变状态变量（@State, @Link, @Prop等）
    this.customWidth = 200;
    this.customHeight = 200;
    this.customOpacity = 0.5;
    // 所有绑定这些状态变量的组件属性（如.width, .height, .opacity）都会执行动画。
  }
);

如何使用：

  1. 定义状态变量：使用 @State, @Link, @Prop 等装饰器定义驱动 UI 的状态变量。
  2. UI 绑定状态：在 build() 方法中，将组件的属性（如 width(), height(), offset()）与这些状态变量绑定。
  3. 触发动画：在事件回调（如按钮的 onClick）中，调用 animateTo 函数。
    • 在第一个参数对象中配置动画参数。
    • 在第二个参数（闭包函数）中，更新状态变量的值。
  4. 自动过渡：ArkUI 框架会自动识别闭包内所有发生变化的状态变量，并将其绑定的所有 UI 属性，以配置的动画参数进行平滑过渡。

示例：同时动画化两个组件的尺寸和透明度

import { animateTo } from '@kit.ArkUI';

@Entry
@Component
struct AnimateToExample {
  @State boxWidth: number = 100;
  @State boxHeight: number = 100;
  @State boxOpacity: number = 1.0;

  build() {
    Column({ space: 20 }) {
      // 组件1：其尺寸和透明度绑定到状态变量
      Row()
        .width(this.boxWidth)
        .height(this.boxHeight)
        .backgroundColor(Color.Blue)
        .opacity(this.boxOpacity)

      // 组件2：同样绑定到相同的状态变量
      Row()
        .width(this.boxWidth)
        .height(this.boxHeight)
        .backgroundColor(Color.Red)
        .opacity(this.boxOpacity)

      Button('执行协同动画')
        .onClick(() => {
          // 使用animateTo触发全局动画
          animateTo({
            duration: 1200,
            curve: Curve.EaseOut
          }, () => {
            // 在闭包内改变状态，所有绑定组件都会响应动画
            this.boxWidth = this.boxWidth === 100 ? 200 : 100;
            this.boxHeight = this.boxHeight === 100 ? 200 : 100;
            this.boxOpacity = this.boxOpacity === 1.0 ? 0.5 : 1.0;
          })
        })
    }
    .padding(20)
    .width('100%')
    .height('100%')
  }
}

与 animation 属性的主要区别：

  • animation：是组件的属性。需要为每个需要动画的组件单独配置，更精细地控制单个组件的动画行为（如 onFinish 回调）。动画参数直接绑定在组件上。
  • animateTo：是全局的函数。一次调用可以驱动多个组件/属性的动画，动画参数在调用时统一设置。逻辑集中在状态改变处，更适合复杂的、联动的动画场景。

总结： 当需要对多个属性或组件应用相同动画参数的过渡效果时，animateTo 是更简洁、高效的选择。它通过状态驱动，将动画逻辑与 UI 更新分离，使代码更易于维护。对于简单的、独立的组件动画，使用 animation 属性即可。

回到顶部