harmony 鸿蒙Property Animation (animation)

2025-06-12
浏览 (2)

Property Animation (animation)

With property animations, you can animate changes to certain component properties, such as width, height, backgroundColor, opacity, scale, rotate and translate. In a property animation that involves width and height changes, a component’s content (such as text and canvas content) is changed straight to the final state. To enable the content to change with the width and height during the animation process, use the renderFit attribute.

NOTE

This event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

Widget capability: This API can be used in ArkTS widgets since API version 9.

APIs

animation(value:AnimateParam)

Atomic service API: This API can be used in atomic services since API version 11.

Property animations only affect attributes that are specified before the animation API and do not affect properties of the component constructor.

@State widthSize: number = 250;
@State heightSize: number = 100;
@State rotateAngle: number = 0;
@State flag: boolean = true;
@State space: number = 10;
// ...
Column({ space: this.space }) // Changing space in the Column constructor will not be animated.
  .onClick(() => {
    if (this.flag) {
      this.widthSize = 150;
      this.heightSize = 60;
      this.space = 20; // Changing this.space will not be animated.
    } else {
      this.widthSize = 250;
      this.heightSize = 100;;
      this.space = 10; //  Changing this.space will not be animated.
    }
    this.flag = !this.flag;
  })
  .margin(30)
  .width(this.widthSize) // Only effective if specified before the animation API.
  .height(this.heightSize) // Only effective if specified before the animation API.
  .animation({
    duration: 2000,
    curve: Curve.EaseOut,
    iterations: 3,
    playMode: PlayMode.Normal
  })
  // .width(this.widthSize) // The animation API does not take effect here.
  // .height(this.heightSize) //  The animation API does not take effect here.

Example

This example demonstrates property animations using the animation API.

// xxx.ets
@Entry
@Component
struct AttrAnimationExample {
  @State widthSize: number = 250
  @State heightSize: number = 100
  @State rotateAngle: number = 0
  @State flag: boolean = true

  build() {
    Column() {
      Button('change size')
        .onClick(() => {
          if (this.flag) {
            this.widthSize = 150
            this.heightSize = 60
          } else {
            this.widthSize = 250
            this.heightSize = 100
          }
          this.flag = !this.flag
        })
        .margin(30)
        .width(this.widthSize)
        .height(this.heightSize)
        .animation({
          duration: 2000,
          curve: Curve.EaseOut,
          iterations: 3,
          playMode: PlayMode.Normal
        })
      Button('change rotate angle')
        .onClick(() => {
          this.rotateAngle = 90
        })
        .margin(50)
        .rotate({ angle: this.rotateAngle })
        .animation({
          duration: 1200,
          curve: Curve.Friction,
          delay: 500,
          iterations: -1, // The value -1 indicates that the animation is played for an unlimited number of times.
          playMode: PlayMode.Alternate,
          expectedFrameRateRange: {
            min: 20,
            max: 120,
            expected: 90,
          }
        })
    }.width('100%').margin({ top: 20 })
  }
}

animation