HarmonyOS Development: Understanding Explicit Animation animateTo

Foreword 

this article is based on Api12 

in the previous article, we simply understood the attribute animation and learned that there are two ways to implement the attribute animation, one is animation and the other is animateTo. The previous case is basically implemented by animation. In fact, in the case, everyone also found that animation is a common attribute of the component, that is, it is bound to the component. If you want to let multiple components play animation, then you need to bind multiple components. Is there a way to execute it that can be applied for animations with multiple animatable attributes configured with the same animation parameters, the answer is a must, and this is animateTo. 

To give a very simple case, it takes 1 second for two components to translate the 100 in the x-axis direction at the same time.

 

@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("click")
        .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%')
  }
}

from the above case, we can see that animateTo is a global way to implement property animation. It can be applied to multiple components. However, there are two points to pay attention to when using it, that is calling animations in aboutToAppear, aboutToDisappear is not recommend; in aboutToAppear, it is because the build in the custom component has not been executed, the internal component has not been created, the animation timing is too early, and the animation attribute has no initial value to animate the component. The reason for aboutToDisappear is that the component is about to be destroyed and cannot be animated in aboutToDisappear. 

Related parameters

Through the source code, we can see that there are two parameters. The first parameter is AnimateParam, which is used to control the relevant properties of animation execution, such as delay, time, speed, etc., and the second parameter is a closure callback function, which is used to change animation properties.

 

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

AnimateParam parameter 

name	type	whether required	description
duration	number	no	duration of the animation, in milliseconds. Default value: 1000
tempo	number	no	the animation playback speed, the larger the value, the faster the animation playback, the smaller the value, the slower the playback, no animation effect when 0. Default value: 1.0
curve	Curve	ICurve9 +	string
delay	number	no	delayed animation playback time, in ms (milliseconds). By default, the animation is played without delay. Default value: 0
iterations	number	no	number of animation plays. By default, it plays once, and when set to -1, it means unlimited playback. Set to 0 to indicate no animation. Default value: 1
playMode	PlayMode	no	animation playback mode, the default playback after the completion of the start. Default value: PlayMode.Normal
onFinish	() => void	no	animation playback complete callback.
finishCallbackType 11 +	FinishCallbackType	no	defines the type of onFinish callback in the animation. Default value: FinishCallbackType.REMOVED
expectedFrameRateRange 11 +	ExpectedFrameRateRange	no	sets the desired frame rate for the animation.

Each of the above parameters may be used in specific situations.

The duration parameter, not to mention, is the overall time to execute the animation, which is also the most common attribute in actual attribute animation. tempo,delay,iterations,playMode,onFinish are all common and simple attributes after all, so we will not repeat them too much. We will focus on the remaining parameters. 

curve, the Curve for animation execution, takes the form of Bezier curve. There are many types that can be set. The default value is Curve.EaseInOut, that is, the animation starts and ends at a low speed. In addition, there is Linear, which means that the speed of the animation is the same from beginning to end. Ease: indicates that the animation starts at a low speed, then speeds up and slows down before it ends. EaseOut: indicates that the animation ends at a low speed; FastOutSlowIn: Standard curve, LinearOutSlowIn: retarder curve; Lineereforward: sharp curve; Rhythm: Rhythm curve; Smooth: Smooth curve; Friction: damping curve. 

playMode, you can set the animation playback mode, currently provides four playback modes, the default is Normal is playing forward, Reverse is play in Reverse, after all, Alternate is fun, allowing the animation to be played forward in odd numbers (1, 3, 5...) and reverse in even numbers (2, 4, 6...); AlternateReverse is and Alternate the opposite,The animation plays in reverse at odd times (1, 3, 5...) and in forward at even times (2, 4, 6...). 

In the version after Api11, two more attributes are added, namely finishCallbackType and expectedFrameRateRange. The former can define the type of callback at the end of the animation, while the latter can set the frame rate of animation execution. The frame rate includes maximum, minimum and optimal, which can be set according to requirements. 

Related Summary 

in actual development, the specification should be followed, and the property animation animateTo should be used correctly, and it should not be used in polling. Otherwise, it will cause the animation that is not the current animation to be executed, resulting in UI errors. Another point to note is that using animateTo directly may lead to the problem of unclear instances. It is recommended to use gettext to obtain the text instance and use animateTo call animateTo that binds the instance.