1# 形状裁剪 2 3用于对组件进行裁剪、遮罩处理。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## clip<sup>12+</sup> 10 11clip(value: boolean) 12 13是否对子组件超出当前组件范围外的区域进行裁剪。 14 15**系统能力：** SystemCapability.ArkUI.ArkUI.Full 16 17**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 18 19**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 20 21**参数：** 22 23| 参数名 | 类型 | 必填 | 说明 | 24| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 25| value | boolean | 是 | 参数为boolean类型，设置是否按照父容器边缘轮廓进行裁剪。<br/>默认值：false <br/>**说明：** 设置为true后，子组件超出当前组件范围外的区域将不响应绑定的手势事件。 | 26 27## clip<sup>(deprecated)</sup> 28 29clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute) 30 31按指定的形状对当前组件进行裁剪。 32 33> **说明：** 34> 35> 从API version 7开始支持，从API version 12开始废弃。建议使用[clip](#clip12)和[clipShape](#clipshape12)替代。 36 37**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 38 39**系统能力：** SystemCapability.ArkUI.ArkUI.Full 40 41**参数：** 42 43| 参数名 | 类型 | 必填 | 说明 | 44| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 45| 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) | 是 | 参数为相应类型的组件，按指定的形状对当前组件进行裁剪；参数为boolean类型时，设置是否按照父容器边缘轮廓进行裁剪。<br/>默认值：false <br/>**说明：** 参数为对应类型的组件时，裁剪不会导致被裁剪区域无法响应绑定的手势事件。参数为boolean类型时，裁剪会导致被裁剪区域无法响应绑定的手势事件。 | 46 47## clipShape<sup>12+</sup> 48 49clipShape(value: CircleShape | EllipseShape | PathShape | RectShape) 50 51按指定的形状对当前组件进行裁剪。 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 56 57**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 58 59**参数：** 60 61| 参数名 | 类型 | 必填 | 说明 | 62| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 63| value | [CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape) | 是 | 参数为相应类型的组件，按指定的形状对当前组件进行裁剪。<br/>**说明：** 裁剪不会导致被裁剪区域无法响应绑定的手势事件。| 64 65## mask<sup>12+</sup> 66 67mask(value: ProgressMask) 68 69为组件上添加可调节进度的遮罩。 70 71**系统能力：** SystemCapability.ArkUI.ArkUI.Full 72 73**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 74 75**参数：** 76 77| 参数名 | 类型 | 必填 | 说明 | 78| ------ | ------------------------------------------------------------ | ---- | -------------------------------- | 79| value | [ProgressMask](#progressmask10) | 是 | 在当前组件上加上可动态设置进度、最大值和颜色的遮罩。 | 80 81## mask<sup>(deprecated)</sup> 82 83mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask) 84 85为组件上添加指定形状的遮罩。 86 87> **说明：** 88> 89> 从API version 7开始支持，从API version 12开始废弃。建议使用[mask](#mask12)和[maskShape](#maskshape12)替代。 90 91**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ------------------------------------------------------------ | ---- | -------------------------------- | 99| value | [CircleAttribute](ts-drawing-components-circle.md) \| [EllipseAttribute](ts-drawing-components-ellipse.md) \| [PathAttribute](ts-drawing-components-path.md) \| [RectAttribute](ts-drawing-components-rect.md) \| [ProgressMask](#progressmask10)<sup>10+</sup> | 是 | 在当前组件上加上指定形状的遮罩。 | 100 101## maskShape<sup>12+</sup> 102 103maskShape(value: CircleShape | EllipseShape | PathShape | RectShape) 104 105为组件上添加指定形状的遮罩。 106 107**系统能力：** SystemCapability.ArkUI.ArkUI.Full 108 109**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 110 111**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| ------ | ------------------------------------------------------------ | ---- | -------------------------------- | 117| value | [CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape) | 是 | 在当前组件上加上指定形状的遮罩。 | 118 119## ProgressMask<sup>10+</sup> 120 121ProgressMask设置遮罩的进度、最大值和遮罩颜色。 122 123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 124 125**系统能力：** SystemCapability.ArkUI.ArkUI.Full 126 127### constructor<sup>10+</sup> 128 129constructor(value: number, total: number, color: ResourceColor) 130 131构造ProgressMask对象。 132 133**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137**参数：** 138 139| 参数名 | 参数类型 | 必填 | 参数描述 | 140| ------ | ------------------------------------------ | ---- | ------------------ | 141| value | number | 是 | 进度遮罩的当前值。 | 142| total | number | 是 | 进度遮罩的最大值。 | 143| color | [ResourceColor](ts-types.md#resourcecolor) | 是 | 进度遮罩的颜色。 | 144 145### updateProgress<sup>10+</sup> 146 147updateProgress(value: number): void 148 149更新进度遮罩的进度值。 150 151**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 152 153**系统能力：** SystemCapability.ArkUI.ArkUI.Full 154 155**参数：** 156 157| 参数名 | 参数类型 | 必填 | 参数描述 | 158| ------ | -------- | ---- | ------------------ | 159| value | number | 是 | 进度遮罩的当前值。 | 160 161### updateColor<sup>10+</sup> 162 163updateColor(value: ResourceColor): void 164 165更新进度遮罩的颜色。 166 167**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 168 169**系统能力：** SystemCapability.ArkUI.ArkUI.Full 170 171**参数：** 172 173| 参数名 | 参数类型 | 必填 | 参数描述 | 174| ------ | ------------------------------------------ | ---- | ---------------- | 175| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 进度遮罩的颜色。 | 176 177### enableBreathingAnimation<sup>12+</sup> 178 179enableBreathingAnimation(value: boolean): void 180 181进度满时的呼吸光晕动画开关。默认关闭呼吸光晕动画。 182 183**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 184 185**系统能力：** SystemCapability.ArkUI.ArkUI.Full 186 187**参数：** 188 189| 参数名 | 参数类型 | 必填 | 参数描述 | 190| ------ | ------------------------------------------ | ---- | ---------------- | 191| value | boolean | 是 | 设置为true则开启呼吸光晕动画。默认值：false | 192 193 194## 示例 195 196### 示例1（使用不同裁剪属性） 197 198```ts 199// xxx.ets 200@Entry 201@Component 202struct ClipAndMaskExample { 203 build() { 204 Column({ space: 15 }) { 205 Text('clip').fontSize(12).width('75%').fontColor('#DCDCDC') 206 Row() { 207 Image($r('app.media.testImg')).width('500px').height('280px') 208 } 209 .clip(true) // 如这里不设置clip为true，则Row组件的圆角不会限制其中的Image组件，Image组件的四个角会超出Row 210 .borderRadius(20) 211 212 // 用一个280px直径的圆对图片进行裁剪 213 Image($r('app.media.testImg')) 214 .clipShape(new Circle({ width: '280px', height: '280px' })) 215 .width('500px').height('280px') 216 217 Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC') 218 // 给图片添加了一个500px*280px的方形遮罩 219 Image($r('app.media.testImg')) 220 .maskShape(new Rect({ width: '500px', height: '280px' }).fill(Color.Gray)) 221 .width('500px').height('280px') 222 223 // 给图片添加了一个280px*280px的圆形遮罩 224 Image($r('app.media.testImg')) 225 .maskShape(new Circle({ width: '280px', height: '280px' }).fill(Color.Gray)) 226 .width('500px').height('280px') 227 } 228 .width('100%') 229 .margin({ top: 15 }) 230 } 231} 232``` 233 234 235 236### 示例2（裁剪属性动画） 237 238```ts 239@Entry 240@Component 241struct ProgressMaskExample { 242 @State progressflag1: boolean = true; 243 @State color: Color = 0x01006CDE; 244 @State value: number = 10.0; 245 @State enableBreathingAnimation: boolean = false; 246 @State progress: ProgressMask = new ProgressMask(10.0, 100.0, Color.Gray); 247 248 build() { 249 Column({ space: 15 }) { 250 Text('progress mask').fontSize(12).width('75%').fontColor('#DCDCDC') 251 // 给图片添加了一个280px*280px的进度遮罩 252 Image($r('app.media.testImg')) 253 .width('500px').height('280px') 254 .mask(this.progress) 255 .animation({ 256 duration: 2000, // 动画时长 257 curve: Curve.Linear, // 动画曲线 258 delay: 0, // 动画延迟 259 iterations: 1, // 播放次数 260 playMode: PlayMode.Normal // 动画模式 261 }) // 对Button组件的宽高属性进行动画配置 262 263 // 更新进度遮罩的进度值 264 Button('updateProgress') 265 .onClick((event?: ClickEvent) => { 266 this.value += 10; 267 this.progress.updateProgress(this.value); 268 }).width(200).height(50).margin(20) 269 270 // 更新进度遮罩的颜色 271 Button('updateColor') 272 .onClick((event?: ClickEvent) => { 273 if (this.progressflag1) { 274 this.progress.updateColor(0x9fff0000); 275 } else { 276 this.progress.updateColor(0x9f0000ff); 277 } 278 this.progressflag1 = !this.progressflag1 279 }).width(200).height(50).margin(20) 280 281 // 开关呼吸光晕动画 282 Button('enableBreathingAnimation:' + this.enableBreathingAnimation) 283 .onClick((event?: ClickEvent) => { 284 this.enableBreathingAnimation = !this.enableBreathingAnimation 285 this.progress.enableBreathingAnimation(this.enableBreathingAnimation); 286 }).width(200).height(50).margin(20) 287 288 // 恢复进度遮罩 289 Button('click reset!') 290 .onClick((event?: ClickEvent) => { 291 this.value = 0; 292 this.progress.updateProgress(this.value); 293 }).width(200).height(50).margin(20) 294 } 295 .width('100%') 296 .margin({ top: 15 }) 297 } 298} 299``` 300 301 302
