Implement attribute animation

#harmonyosnext

Property Animation in ArkUI

Understanding Property Animation

Property animation in ArkUI refers to the continuous visual effects on the UI caused by changes in animatable properties. It's a fundamental and easy-to-understand animation type. ArkUI offers two interfaces for property animation: animateTo and animation. These interfaces drive component properties to change continuously according to animation parameters like curves, creating smooth property animations.

Animation Interface	Scope	Principle	Use Case
animateTo	Animates UI changes caused by property modifications within a closure. Used for appearance/disappearance transitions. A general function that animates differences between the UI before the closure and the UI defined by state variables within the closure. Supports multiple calls and nesting.	Ideal for scenarios where multiple animatable properties need to be configured with the same animation parameters and nested animations are required.
animation	Binds to component properties via an attribute interface. Automatically adds animations when animatable properties change. Since component interface calls are executed from bottom to top, `animation` only affects properties called above it. Components can set different `animation` for multiple properties based on call order.	Suitable for scenarios where multiple animatable properties need to be configured with different animation parameters.

Using animateTo for Property Animation

The animateTo interface triggers animations based on property changes within a closure. It's often used for transition effects like appearance and disappearance. It's a general-purpose function that animates differences between the UI before the closure and the UI defined by state variables within the closure. It supports multiple calls and nesting, making it ideal for scenarios requiring the same animation parameters for multiple properties or nested animations.

Syntax

animateTo(value: AnimateParam, event: () => void): void

value: Specifies the AnimateParam object, which includes animation parameters like duration and curve.
event: The closure function where property changes trigger animations. Property changes within this closure follow the specified animation parameters.

Usage Example

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

@Entry
@Component
struct AnimateToDemo {
  @State animate: boolean = false;
  // Step 1: Declare relevant state variables
  @State rotateValue: number = 0; // Rotation angle for component one
  @State translateX: number = 0; // Translation value for component two
  @State opacityValue: number = 1; // Opacity for component two

  build() {
    Row() {
      // Component one
      Column() {
      }
      .rotate({ angle: this.rotateValue })
      .backgroundColor('#317AF7')
      .justifyContent(FlexAlign.Center)
      .width(100)
      .height(100)
      .borderRadius(30)
      .onClick(() => {
        this.getUIContext()?.animateTo({ curve: curves.springMotion() }, () => {
          this.animate = !this.animate;
          // Step 3: Modify state variables within the closure to change the UI
          // Any logic that changes the UI can be placed here, such as adding items to an array or controlling visibility
          // The system detects differences between the new and old UI and adds animations to the changed parts
          // For component one, the rotate property changes, triggering a rotation animation
          this.rotateValue = this.animate ? 90 : 0;
          // For component two, the opacity property changes, triggering an opacity animation
          this.opacityValue = this.animate ? 0.6 : 1;
          // For component two, the translate property changes, triggering a translation animation
          this.translateX = this.animate ? 50 : 0;
        })
      })

      // Component two
      Column() {
      }
      .justifyContent(FlexAlign.Center)
      .width(100)
      .height(100)
      .backgroundColor('#D94838')
      .borderRadius(30)
      .opacity(this.opacityValue)
      .translate({ x: this.translateX })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

Using animation for Property Animation

Unlike animateTo, which requires property changes to be placed within a closure, the animation interface doesn't use a closure. Instead, adding the animation interface after an animatable property enables automatic animation whenever the property changes. This allows different animation parameters for different properties, whereas animateTo requires property changes to be within the animation closure.

Usage Example

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

@Entry
@Component
struct AnimationDemo {
  @State animate: boolean = false;
  // Step 1: Declare relevant state variables
  @State rotateValue: number = 0; // Rotation angle for component one
  @State translateX: number = 0; // Translation value for component two
  @State opacityValue: number = 1; // Opacity for component two

  build() {
    Row() {
      // Component one
      Column() {
      }
      .opacity(this.opacityValue)
      .rotate({ angle: this.rotateValue })
      // Step 3: Enable property animation using the animation interface
      .animation({ curve: curves.springMotion() })
      .backgroundColor('#317AF7')
      .justifyContent(FlexAlign.Center)
      .width(100)
      .height(100)
      .borderRadius(30)
      .onClick(() => {
        this.animate = !this.animate;
        // Step 4: Modify state variables within the closure to change the UI
        // Any logic that changes the UI can be placed here, such as adding items to an array or controlling visibility
        // The system detects differences between the new and old UI and adds animations to the changed parts
        // For component one, the rotate property changes, triggering a rotation animation
        this.rotateValue = this.animate ? 90 : 0;
        // For component two, the translate property changes, triggering a translation animation
        this.translateX = this.animate ? 50 : 0;
        // The opacity property of the parent column changes, affecting its child nodes' opacity as well
        this.opacityValue = this.animate ? 0.6 : 1;
      })

      // Component two
      Column() {
      }
      .justifyContent(FlexAlign.Center)
      .width(100)
      .height(100)
      .backgroundColor('#D94838')
      .borderRadius(30)
      .opacity(this.opacityValue)
      .translate({ x: this.translateX })
      .animation({ curve: curves.springMotion() })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

Key Differences Between animateTo and animation

Feature	animateTo	animation
Closure Usage	Requires property changes to be within a closure	No closure needed
Animation Trigger	Animates differences between UI before and after closure execution	Automatically triggers when bound properties change
Parameter Sharing	All property changes within the closure share the same animation parameters	Each property can have its own animation parameters
Call Sequence	Supports nested calls	Animation effect depends on the order of property calls
Use Case	Suitable for simple animations with the same parameters for multiple properties or nested animations	Ideal for complex animations with different parameters for different properties