Shape clipping changes the visible portion of a component through clipping or masking.
The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
clip12+
clip(value: boolean): T
Sets whether to clip the areas of child components that extend beyond this component's bounds, that is, whether to perform clipping based on the edge contour of the parent container If this API is not used, the area of child components extending beyond the current component's bounds is not clipped by default.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | boolean | Yes | Whether to clip the areas of child components that extend beyond the current component's bounds. The value true means to clip the areas of child components that extend beyond the current component's bounds, and false means the opposite. Note: If this parameter is set to true, child components exceeding the current component's bounds will not respond to bound gesture events. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
clip18+
clip(clip: Optional<boolean>): T
Sets whether to clip the areas of child components that extend beyond this component's bounds, that is, whether to perform clipping based on the edge contour of the parent container If this API is not used, the area of child components extending beyond the current component's bounds is not clipped by default. Compared with clip12+, this API supports the undefined type.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 18.
Atomic service API: This API can be used in atomic services since API version 18.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| clip | Optional<boolean> | Yes | Whether to clip the areas of child components that extend beyond the current component's bounds. Note: If this parameter is set to true, child components exceeding the current component's bounds will not respond to bound gesture events. If clip is set to undefined, clipping is disabled, and child components are not clipped. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
clip(deprecated)
clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute): T
Sets whether to clip this component based on the given shape.
This API is supported since API version 7 and deprecated since API version 12. You are advised to use clipShape instead.
Widget capability: This API can be used in ArkTS widgets since API version 9.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | Yes | Clip mode. If the value is a shape attribute, the component is clipped based on the specified shape. If the value is of the Boolean type, it specifies whether to clip the component based on the boundaries of the parent container. Default value: false. Note: If the value is a shape attribute, the clipped area can still respond to bound gesture events. If the value is of the Boolean type, the clipped area will not respond to bound gesture events. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
clipShape12+
clipShape(value: CircleShape | EllipseShape | PathShape | RectShape): T
Clips this component according to the specified shape (which may include position information).
Different shapes support different ranges of attributes. A path is one type of shape, along with others like ellipses and rectangles.
Path shapes do not support setting width and height attributes. For details about the supported attributes, see the specific shape documentation.
The fill attribute of shapes has no effect on the clipShape API.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | CircleShape | EllipseShape | PathShape | RectShape | Yes | Shape (which may include position information) to clip the current component. Note: The clipped area remains responsive to bound gesture events. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
clipShape18+
clipShape(shape: Optional<CircleShape | EllipseShape | PathShape | RectShape>): T
Clips this component according to the specified shape (which may include position information). Compared with clipShape12+, this API supports the undefined type.
Different shapes support different ranges of attributes. A path is one type of shape, along with others like ellipses and rectangles.
Path shapes do not support setting width and height attributes. For details about the supported attributes, see the specific shape documentation.
The fill attribute of shapes has no effect on the clipShape API.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 18.
Atomic service API: This API can be used in atomic services since API version 18.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| shape | Optional<CircleShape | EllipseShape | PathShape | RectShape> | Yes | Shape (which may include position information) to clip the current component. Note: The clipped area remains responsive to bound gesture events. If the value of shape is undefined, the current setting will be reset to its default state. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
CircleShape12+
type CircleShape = CircleShape
Defines the CircleShape type.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
| Type | Description |
|---|---|
| CircleShape | Circle shape. |
EllipseShape12+
type EllipseShape = EllipseShape
Defines the EllipseShape type.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
| Type | Description |
|---|---|
| EllipseShape | Ellipse shape. |
PathShape12+
type PathShape = PathShape
Defines the PathShape type.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
| Type | Description |
|---|---|
| PathShape | Path shape. |
RectShape12+
type RectShape = RectShape
Defines the RectShape type.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
| Type | Description |
|---|---|
| RectShape | Rectangle shape. |
mask12+
mask(value: ProgressMask): T
Adds a mask to the component to indicate the progress.
System capability: SystemCapability.ArkUI.ArkUI.Full
Atomic service API: This API can be used in atomic services since API version 12.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | ProgressMask | Yes | Mask to add to the component, which allows for dynamic adjustment of progress, maximum value, and color settings. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
mask18+
mask(mask: Optional<ProgressMask>): T
Adds a mask to the component to indicate the progress. Compared with mask12+, this API supports the undefined type.
System capability: SystemCapability.ArkUI.ArkUI.Full
Atomic service API: This API can be used in atomic services since API version 18.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| mask | Optional<ProgressMask> | Yes | Mask to add to the component, which allows for dynamic adjustment of progress, maximum value, and color settings. If mask is set to undefined, the component to revert to its original effect without the mask to indicate the progress. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
mask(deprecated)
mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask): T
Adds a mask of the specified shape to the component.
This API is supported since API version 7 and deprecated since API version 12. You are advised to use maskShape instead.
Widget capability: This API can be used in ArkTS widgets since API version 9.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask10+ | Yes | Mask of the specified shape to add to the component. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
maskShape12+
maskShape(value: CircleShape | EllipseShape | PathShape | RectShape): T
Adds a mask of the specified shape to the component.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | CircleShape | EllipseShape | PathShape | RectShape | Yes | Mask of the specified shape to add to the component. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
maskShape18+
maskShape(shape: Optional<CircleShape | EllipseShape | PathShape | RectShape>): T
Adds a mask of the specified shape to the component. Compared with maskShape12+, this API supports the undefined type.
System capability: SystemCapability.ArkUI.ArkUI.Full
Widget capability: This API can be used in ArkTS widgets since API version 18.
Atomic service API: This API can be used in atomic services since API version 18.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| shape | Optional<CircleShape | EllipseShape | PathShape | RectShape> | Yes | Mask of the specified shape to add to the component. If the value of shape is undefined, the current setting will be reset to its default state. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
ProgressMask10+
Sets the progress, maximum value, and color for a mask.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
[h2]constructor10+
constructor(value: number, total: number, color: ResourceColor)
Constructs a ProgressMask object.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | number | Yes | Current value of the progress mask. Value range: [0.0, +∞) |
| total | number | Yes | Maximum value of the progress mask. Value range: [0.0, +∞) |
| color | ResourceColor | Yes | Color of the progress mask. |
[h2]updateProgress10+
updateProgress(value: number): void
Updates the progress value of the progress mask.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | number | Yes | Current value of the progress mask. |
[h2]updateColor10+
updateColor(value: ResourceColor): void
Updates the color of the progress mask.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | ResourceColor | Yes | Color of the progress mask. |
[h2]enableBreathingAnimation12+
enableBreathingAnimation(value: boolean): void
Sets whether to enable the breathing animation when the progress indicator is full. If this API is not set, the breathing animation is disabled by default.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | boolean | Yes | Whether to enable the breathing animation. true: The breathing animation is enabled. false: The breathing halo animation is disabled. |
[h2]Example 1: Using Different Clipping Attributes
This example demonstrates how to clip and mask an image using clipShape, clip, and maskShape.
// xxx.ets
import { CircleShape, RectShape } from '@kit.ArkUI';
@Entry
@Component
struct ClipAndMaskExample {
build() {
Column({ space: 15 }) {
Text('clip').fontSize(12).width('75%').fontColor('#DCDCDC')
Row() {
// Replace $r("app.media.testImg") with the image resource file you use.
Image($r('app.media.testImg')).width('500px').height('280px')
}
.clip(true) // If clip is not set to true, the image is not confined by the rounded corners of the <Row> component and may extend beyond the <Row> component.
.borderRadius(20)
// Clip the image based on a circle with a diameter of 280 px.
// Replace $r("app.media.testImg") with the image resource file you use.
Image($r('app.media.testImg'))
.clipShape(new CircleShape({ width: '280px', height: '280px' }))
.width('500px').height('280px')
Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC')
// Add a 500 × 280 px square mask to the image.
// Replace $r("app.media.testImg") with the image resource file you use.
Image($r('app.media.testImg'))
.maskShape(new RectShape({ width: '500px', height: '280px' }).fill(Color.Gray))
.width('500px').height('280px')
// Add a 280 × 280 px circular mask to the image.
// Replace $r("app.media.testImg") with the image resource file you use.
Image($r('app.media.testImg'))
.maskShape(new CircleShape({ width: '280px', height: '280px' }).fill(Color.Gray))
.width('500px').height('280px')
}
.width('100%')
.margin({ top: 15 })
}
} 
[h2]Example 2: Implementing Component Masking
This example demonstrates how to mask an image using mask.
@Entry
@Component
struct ProgressMaskExample {
@State progressFlag1: boolean = true;
@State color: Color = 0x01006CDE;
@State value: number = 10.0;
@State enableBreathingAnimation: boolean = false;
@State progress: ProgressMask = new ProgressMask(10.0, 100.0, Color.Gray);
build() {
Column({ space: 15 }) {
Text('progress mask').fontSize(12).width('75%').fontColor('#DCDCDC')
// Add a 280 × 280 px progress mask to the image.
// Replace $r("app.media.testImg") with the image resource file you use.
Image($r('app.media.testImg'))
.width('500px').height('280px')
.mask(this.progress)
.animation({
duration: 2000, // Animation duration.
curve: Curve.Linear, // Animation curve.
delay: 0, // Animation delay.
iterations: 1, // Number of playback times.
playMode: PlayMode.Normal // Animation playback mode.
}) // Animation configuration for the width and height attributes of the <Button> component.
// Update the progress value of the progress mask.
Button('updateProgress')
.onClick((event?: ClickEvent) => {
this.value += 10;
this.progress.updateProgress(this.value);
}).width(200).height(50).margin(20)
// Update the color of the progress mask.
Button('updateColor')
.onClick((event?: ClickEvent) => {
if (this.progressFlag1) {
this.progress.updateColor(0x9fff0000);
} else {
this.progress.updateColor(0x9f0000ff);
}
this.progressFlag1 = !this.progressFlag1
}).width(200).height(50).margin(20)
// Enable or disable the breathing animation.
Button('enableBreathingAnimation:' + this.enableBreathingAnimation)
.onClick((event?: ClickEvent) => {
this.enableBreathingAnimation = !this.enableBreathingAnimation;
this.progress.enableBreathingAnimation(this.enableBreathingAnimation);
}).width(200).height(50).margin(20)
// Restore the progress mask.
Button('click reset!')
.onClick((event?: ClickEvent) => {
this.value = 0;
this.progress.updateProgress(this.value);
}).width(200).height(50).margin(20)
}
.width('100%')
.margin({ top: 15 })
}
} 