Implementing a Masking Effect When a Component Moves Upward

#harmonyos #arkts #curtainmaskanimation #zindex

Read the original article：Implementing a Masking Effect When a Component Moves Upward

Requirement Description

The goal is to create a visual effect where a component moves upward until it becomes fully covered by a “curtain” (mask) component.
Initially, the moving component is below the curtain. When clicked, it gradually moves upward until it is completely hidden beneath the curtain layer.

Background Knowledge

animateTo: A global explicit animation API in HarmonyOS that provides smooth transition effects for state changes. It can animate layout-related properties (e.g., width, height, position).
zIndex: Defines the stacking order of sibling components within the same container. A higher zIndex means the component will appear above those with a lower zIndex.
translate: Applies translation (movement) to a component relative to its top-left corner as the origin.
renderFit: Ensures that content, such as text or Canvas drawings, scales appropriately with layout changes when necessary.

Implementation Steps

Define the Curtain Component
- Set its zIndex to a higher value (e.g., 100) to ensure it visually overlaps other components.
- Position it vertically using the position property (e.g., top = 250).
Define the Moving Component
- Set its zIndex to a lower value (e.g., 50) so it can be visually hidden under the curtain.
- Bind its vertical position to a reactive variable (e.g., @State y).
Animate the Movement
- In the component’s onClick event, obtain the UIContext instance using getUIContext().
- Use the animateTo API to smoothly update the component’s Y-axis position (translate.y) to simulate upward motion.
- As the moving component reaches the curtain’s lower edge, it gradually disappears underneath it because of the zIndex difference.

Code Snippet / Configuration

@Entry
@Component
struct Index {
  @State y: number = 400; // Initial vertical position

  build() {
    Column() {
      // Curtain component
      Column() {
        Text('Curtain Component')
          .textAlign(TextAlign.Center)
          .align(Alignment.Center)
      }
      .justifyContent(FlexAlign.Center)
      .size({ width: '100%', height: 100 })
      .position({ top: 250 })
      .zIndex(100)
      .backgroundColor('#f0f2f4')

      // Moving component
      Row() {
        Text()
          .size({ width: 60, height: 60 })
          .fontSize(12)
          .fontColor('#81D3F8')
          .borderRadius(40)
          .backgroundColor('#1d52c2')
          .zIndex(50)
      }
      .size({ width: 60, height: 60 })
      .margin({ top: 50 })
      .translate({ y: this.y })
      .onClick(() => {
        setTimeout(() => {
          this.getUIContext().animateTo({ duration: 1000 }, () => {
            this.y = 230; // Move upward
          })
        }, 1000);
      })
    }
    .width('100%')
    .height('100%')
    .backgroundColor(Color.White)
  }
}

Test Results

After compilation and execution:

The component starts below the curtain.
When clicked, it smoothly moves upward over one second.
As it reaches the curtain’s edge, it gradually disappears beneath it due to the zIndex-based layering.

Limitations or Considerations

Ensure that the curtain’s zIndex value is greater than that of the moving component.
Remember to manage animation timing carefully for smoother transitions.
For dynamic layouts, use relative positioning or constraints to maintain proper alignment.
Supported from API Version 20 Release and above.
Requires HarmonyOS 6.0.0 Release SDK or later.
Must be compiled and executed using DevEco Studio 6.0.0 Release or later.