Harmony OS Next

Simplified Usage of Shape Clipping

Shape clipping functionality in HarmonyOS development is used for cropping and masking components. Below is a simplified guide to its usage.

Official documentation: https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/ts-universal-attributes-sharp-clipping-V5#mask12

1. Clipping Functionality

   • clip Property (Supported from API Version 7, updated in API Version 12): Determines whether to clip child components of the current component. Accepts a boolean parameter. For example, when an Image component is inside a Row component, setting clip(true) on the Row will constrain the image display within the row’s border (e.g., rounded corners set via borderRadius).
   • clipShape Property (Supported from API Version 12): Clips the component to a specified shape (CircleShape, EllipseShape, PathShape, or RectShape). For example, to crop an image into a circle, create a Circle object with appropriate dimensions and apply it to the Image component’s clipShape property.

2. Masking Functionality

   • mask Property (Supported from API Version 12): Adds a progress-based mask to the component. Accepts a ProgressMask parameter, which allows setting properties like progress value, maximum value, and color for dynamic effects.
   • maskShape Property (Supported from API Version 12): Applies a geometric mask (circle, ellipse, path, or rectangle) to the component. Create a shape object (e.g., Rect, Circle) with properties like fill color, then apply it to the component’s maskShape property.

Example Code Analysis

1. Clipping Example
   In the ClipAndMaskExample struct:

   • The clip property is demonstrated on a Row containing an Image. Setting clip(true) and borderRadius(20) crops the image to rounded corners. Without clip(true), the image corners would extend beyond the row’s rounded border.
   • The clipShape property uses a Circle shape with 280px diameter to crop the image into a perfect circle.

2. Masking Example
   In the ProgressMaskExample struct:

   • A ProgressMask object is applied to an Image via the mask property, creating a progress-based mask. Animation effects are configured including duration, curve, delay, iterations, and play mode.
   • Button click events control:
     • updateProgress: Increases the mask’s progress value
     • updateColor: Changes the mask color
     • enableBreathingAnimation: Toggles the breathing glow animation when progress reaches 100%

Shape clipping provides powerful styling capabilities for components, enabling various personalized UI effects. Developers can flexibly utilize these properties and methods to optimize application interfaces based on specific requirements.