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