• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Shape Clipping
2
3Shape clipping changes the visible portion of a component through clipping or masking.
4
5>  **NOTE**
6>
7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
8
9## clip
10
11clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute)
12
13Clips the component based on the given shape.
14
15**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
16
17**System capability**: SystemCapability.ArkUI.ArkUI.Full
18
19**Parameters**
20
21| Name| Type                                                        | Mandatory| Description                                                        |
22| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
23| value  | boolean \| [CircleAttribute](ts-drawing-components-circle.md) \| [EllipseAttribute](ts-drawing-components-ellipse.md) \| [PathAttribute](ts-drawing-components-path.md) \| [RectAttribute](ts-drawing-components-rect.md) | Yes  | Clip mode. If the value is a shape, 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 edge outline of the parent container.<br>Default value: **false**|
24
25## mask
26
27mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask)
28
29Adds a mask of the specified shape to the component.
30
31**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
32
33**System capability**: SystemCapability.ArkUI.ArkUI.Full
34
35**Parameters**
36
37| Name| Type                                                        | Mandatory| Description                            |
38| ------ | ------------------------------------------------------------ | ---- | -------------------------------- |
39| value  | [ProgressMask](##progressmask10)<sup>10+</sup> \| [CircleAttribute](ts-drawing-components-circle.md) \| [EllipseAttribute](ts-drawing-components-ellipse.md) \| [PathAttribute](ts-drawing-components-path.md) \| [RectAttribute](ts-drawing-components-rect.md) | Yes  | Mask of the specified shape to add to the component.|
40
41## ProgressMask<sup>10+</sup>
42
43Implements a **ProgressMask** object to set the progress, maximum value, and color of the mask.
44
45### constructor<sup>10+</sup>
46
47constructor(value: number, total: number, color: ResourceColor)
48
49Constructs a **ProgressMask** object.
50
51**Parameters**
52
53| Name| Type                                  | Mandatory| Description          |
54| ------ | ------------------------------------------ | ---- | ------------------ |
55| value  | number                                     | Yes  | Current value of the progress mask.|
56| total  | number                                     | Yes  | Maximum value of the progress mask.|
57| color  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the progress mask.  |
58
59### updateProgress<sup>10+</sup>
60
61updateProgress(value: number): void
62
63Updates the progress value of the progress mask.
64
65**Parameters**
66
67| Name| Type| Mandatory| Description          |
68| ------ | -------- | ---- | ------------------ |
69| value  | number   | Yes  | Current value of the progress mask.|
70
71### updateColor<sup>10+</sup>
72
73updateColor(value: ResourceColor): void
74
75Updates the color of the progress mask.
76
77**Parameters**
78
79| Name| Type                                  | Mandatory| Description        |
80| ------ | ------------------------------------------ | ---- | ---------------- |
81| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the progress mask.|
82
83
84
85## Example
86
87### Example 1
88
89```ts
90// xxx.ets
91@Entry
92@Component
93struct ClipAndMaskExample {
94  build() {
95    Column({ space: 15 }) {
96      Text('clip').fontSize(12).width('75%').fontColor('#DCDCDC')
97      Row() {
98        Image($r('app.media.testImg')).width('500px').height('280px')
99      }
100      .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.
101      .borderRadius(20)
102      // Clip the image based on a circle with a diameter of 280 px.
103      Image($r('app.media.testImg'))
104        .clip(new Circle({ width: '280px', height: '280px' }))
105        .width('500px').height('280px')
106
107      Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC')
108      // Add a 500 px x 280 px square mask to the image.
109      Image($r('app.media.testImg'))
110        .mask(new Rect({ width: '500px', height: '280px' }).fill(Color.Gray))
111        .width('500px').height('280px')
112
113      // Add a 280 px x 280 px circular mask to the image.
114      Image($r('app.media.testImg'))
115        .mask(new Circle({ width: '280px', height: '280px' }).fill(Color.Gray))
116        .width('500px').height('280px')
117    }
118    .width('100%')
119    .margin({ top: 15 })
120  }
121}
122```
123
124![clipAndMask](figures/clipAndMask.PNG)
125
126### Example 2
127
128```ts
129@Entry
130@Component
131struct ProgressMaskExample {
132  @State progressflag1: boolean = true;
133  @State color: Color = 0x01006CDE;
134  @State value: number = 10.0;
135  @State progress: ProgressMask = new ProgressMask(10.0, 100.0, Color.Gray);
136  build() {
137    Column({ space: 15 }) {
138      Text('progress mask').fontSize(12).width('75%').fontColor('#DCDCDC')
139      // Add a 280px x 280px progress mask to the image.
140      Image($r('app.media.testImg'))
141        .width('500px').height('280px')
142        .mask(this.progress)
143        .animation({
144          duration: 2000, // Animation duration.
145          .curve(Curve.Linear) // Animation curve.
146          delay: 0, // Animation delay.
147          iterations: 1, // Number of playback times.
148          playMode: PlayMode.Normal // Animation playback mode.
149        }) // Animation configuration for the width and height attributes of the <Button> component.
150
151      // Update the progress value of the progress mask.
152      Button('updateProgress')
153        .onClick((event?: ClickEvent) => {
154          this.value += 10;
155          this.progress.updateProgress(this.value);
156        }).width(200).height(50).margin(20)
157
158      // Update the color of the progress mask.
159      Button('updateColor')
160        .onClick((event?: ClickEvent) => {
161          if (this.progressflag1) {
162            this.progress.updateColor(0x9fff0000);
163          } else {
164            this.progress.updateColor(0x9f0000ff);
165          }
166          this.progressflag1 = !this.progressflag1
167        }).width(200).height(50).margin(20)
168
169      // Restores the progress mask.
170      Button('click reset!')
171        .onClick((event?: ClickEvent) => {
172          this.value = 0;
173          this.progress.updateProgress(this.value);
174        }).width(200).height(50).margin(20)
175    }
176    .width('100%')
177    .margin({ top: 15 })
178  }
179}
180```
181
182![progressMask](figures/progressMask.PNG)
183