1# 形状裁剪 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @CCFFWW--> 5<!--Designer: @yangfan229--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9用于对组件进行裁剪、遮罩处理。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## clip<sup>12+</sup> 16 17clip(value: boolean): T 18 19是否对子组件超出当前组件范围外的区域进行裁剪。 20 21**系统能力：** SystemCapability.ArkUI.ArkUI.Full 22 23**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 24 25**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------ | ------- | ---- | ------------------------------------------------------------ | 31| value | boolean | 是 | 参数为boolean类型，设置是否按照父容器边缘轮廓进行裁剪。<br/>默认值：false <br/>true表示按照父容器边缘轮廓进行裁剪，false表示不对子组件进行裁剪。 <br/>**说明：** 设置为true后，子组件超出当前组件范围外的区域将不响应绑定的手势事件。 | 32 33**返回值：** 34 35| 类型 | 说明 | 36| ------ | ------------------------ | 37| T | 返回当前组件。 | 38 39## clip<sup>18+</sup> 40 41clip(clip: Optional\<boolean>): T 42 43是否对子组件超出当前组件范围外的区域进行裁剪。与[clip<sup>12+</sup>](#clip12)相比，clip参数新增了对undefined类型的支持。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 48 49**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| ------ | ------------------ | ------------------------------------------------------------ | ---- | 55| clip | Optional\<boolean> | 是 | 参数为boolean类型，设置是否按照父容器边缘轮廓进行裁剪。<br/>默认值：false <br/>**说明：** 设置为true后，子组件超出当前组件范围外的区域将不响应绑定的手势事件。<br/>当clip的值为undefined时，恢复为不对子组件超出当前组件范围外的区域进行裁剪。 | 56 57**返回值：** 58 59| 类型 | 说明 | 60| ------ | ------------------------ | 61| T | 返回当前组件。 | 62 63## clip<sup>(deprecated)</sup> 64 65clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute): T 66 67按指定的形状对当前组件进行裁剪。 68 69> **说明：** 70> 71> 从API version 7开始支持，从API version 12开始废弃。建议使用[clip](#clip12)和[clipShape](#clipshape12)替代。 72 73**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 74 75**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79**参数：** 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 83| 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类型时，裁剪会导致被裁剪区域无法响应绑定的手势事件。 | 84 85**返回值：** 86 87| 类型 | 说明 | 88| ------ | ------------------------ | 89| T | 返回当前组件。 | 90 91## clipShape<sup>12+</sup> 92 93clipShape(value: CircleShape | EllipseShape | PathShape | RectShape): T 94 95按指定的形状（形状中可包含位置信息）对当前组件进行裁剪。 96 97> **说明：** 98> 99> 不同的形状支持的属性范围不同，路径是一种形状，除此之外还有椭圆、矩形等形状。 100> 101> 路径的形状不支持设置宽度和高度。具体形状支持的属性参考具体形状的文档。 102> 103> 形状中的[fill](../js-apis-arkui-shape.md#fill)属性对clipShape接口不生效。 104 105**系统能力：** SystemCapability.ArkUI.ArkUI.Full 106 107**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 108 109**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 115| value | [CircleShape](#circleshape12) \| [EllipseShape](#ellipseshape12) \| [PathShape](#pathshape12) \| [RectShape](#rectshape12) | 是 | 参数为相应类型的组件，按指定的形状（形状中可包含位置信息）对当前组件进行裁剪。<br/>**说明：** 裁剪不会导致被裁剪区域无法响应绑定的手势事件。 | 116 117**返回值：** 118 119| 类型 | 说明 | 120| ------ | ------------------------ | 121| T | 返回当前组件。 | 122 123## clipShape<sup>18+</sup> 124 125clipShape(shape: Optional\<CircleShape | EllipseShape | PathShape | RectShape>): T 126 127按指定的形状（形状中可包含位置信息）对当前组件进行裁剪。与[clipShape<sup>12+</sup>](#clipshape12)相比，shape参数新增了对undefined类型的支持。 128 129> **说明：** 130> 131> 不同的形状支持的属性范围不同，路径是一种形状，除此之外还有椭圆、矩形等形状。 132> 133> 路径的形状不支持设置宽度和高度。具体形状支持的属性参考具体形状的文档。 134> 135> 形状中的[fill](../js-apis-arkui-shape.md#fill)属性对clipShape接口不生效。 136 137**系统能力：** SystemCapability.ArkUI.ArkUI.Full 138 139**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 140 141**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 142 143**参数：** 144 145| 参数名 | 类型 | 必填 | 说明 | 146| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 147| shape | Optional\<[CircleShape](#circleshape12) \| [EllipseShape](#ellipseshape12) \| [PathShape](#pathshape12) \| [RectShape](#rectshape12)> | 是 | 参数为相应类型的组件，按指定的形状（形状中可包含位置信息）对当前组件进行裁剪。<br/>**说明：** 裁剪不会导致被裁剪区域无法响应绑定的手势事件。<br/>当shape的值为undefined时，维持上次取值。 | 148 149**返回值：** 150 151| 类型 | 说明 | 152| ------ | ------------------------ | 153| T | 返回当前组件。 | 154 155## CircleShape<sup>12+</sup> 156 157type CircleShape = CircleShape 158 159导入CircleShape类型对象。 160 161**系统能力：** SystemCapability.ArkUI.ArkUI.Full 162 163**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 164 165**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 166 167| 类型 | 说明 | 168| ------ | ------------------------ | 169| [CircleShape](../js-apis-arkui-shape.md#circleshape) | 圆形形状。 | 170 171## EllipseShape<sup>12+</sup> 172 173type EllipseShape = EllipseShape 174 175导入EllipseShape类型对象。 176 177**系统能力：** SystemCapability.ArkUI.ArkUI.Full 178 179**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 180 181**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 182 183| 类型 | 说明 | 184| ------ | ------------------------ | 185| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) | 椭圆形状。 | 186 187## PathShape<sup>12+</sup> 188 189type PathShape = PathShape 190 191导入PathShape类型对象。 192 193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 194 195**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 196 197**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 198 199| 类型 | 说明 | 200| ------ | ------------------------ | 201| [PathShape](../js-apis-arkui-shape.md#pathshape) | 接口路径。 | 202 203## RectShape<sup>12+</sup> 204 205type RectShape = RectShape 206 207导入RectShape类型对象。 208 209**系统能力：** SystemCapability.ArkUI.ArkUI.Full 210 211**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 212 213**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 214 215| 类型 | 说明 | 216| ------ | ------------------------ | 217| [RectShape](../js-apis-arkui-shape.md#rectshape) | 矩形形状。 | 218 219## mask<sup>12+</sup> 220 221mask(value: ProgressMask): T 222 223为组件上添加可调节进度的遮罩。 224 225**系统能力：** SystemCapability.ArkUI.ArkUI.Full 226 227**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| ------ | ------------------------------- | ---- | ---------------------------------------------------- | 233| value | [ProgressMask](#progressmask10) | 是 | 在当前组件上加上可动态设置进度、最大值和颜色的遮罩。 | 234 235**返回值：** 236 237| 类型 | 说明 | 238| ------ | ------------------------ | 239| T | 返回当前组件。 | 240 241## mask<sup>18+</sup> 242 243mask(mask: Optional\<ProgressMask>): T 244 245为组件上添加可调节进度的遮罩。与[mask<sup>12+</sup>](#mask12)相比，mask参数新增了对undefined类型的支持。 246 247**系统能力：** SystemCapability.ArkUI.ArkUI.Full 248 249**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 250 251**参数：** 252 253| 参数名 | 类型 | 必填 | 说明 | 254| ------ | ------------------------------------------------------------ | ---- | -------------------------------- | 255| mask | Optional\<[ProgressMask](#progressmask10)> | 是 | 在当前组件上加上可动态设置进度、最大值和颜色的遮罩。<br/>当mask的值为undefined时，恢复为无进度遮罩效果。 | 256 257**返回值：** 258 259| 类型 | 说明 | 260| ------ | ------------------------ | 261| T | 返回当前组件。 | 262 263## mask<sup>(deprecated)</sup> 264 265mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask): T 266 267为组件上添加指定形状的遮罩。 268 269> **说明：** 270> 271> 从API version 7开始支持，从API version 12开始废弃。建议使用[mask](#mask12)和[maskShape](#maskshape12)替代。 272 273**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 274 275**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 276 277**系统能力：** SystemCapability.ArkUI.ArkUI.Full 278 279**参数：** 280 281| 参数名 | 类型 | 必填 | 说明 | 282| ------ | ------------------------------------------------------------ | ---- | -------------------------------- | 283| 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> | 是 | 在当前组件上加上指定形状的遮罩。 | 284 285**返回值：** 286 287| 类型 | 说明 | 288| ------ | ------------------------ | 289| T | 返回当前组件。 | 290 291## maskShape<sup>12+</sup> 292 293maskShape(value: CircleShape | EllipseShape | PathShape | RectShape): T 294 295为组件上添加指定形状的遮罩。 296 297**系统能力：** SystemCapability.ArkUI.ArkUI.Full 298 299**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 300 301**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 302 303**参数：** 304 305| 参数名 | 类型 | 必填 | 说明 | 306| ------ | ------------------------------------------------------------ | ---- | -------------------------------- | 307| value | [CircleShape](#circleshape12) \| [EllipseShape](#ellipseshape12) \| [PathShape](#pathshape12) \| [RectShape](#rectshape12) | 是 | 在当前组件上加上指定形状的遮罩。 | 308 309**返回值：** 310 311| 类型 | 说明 | 312| ------ | ------------------------ | 313| T | 返回当前组件。 | 314 315## maskShape<sup>18+</sup> 316 317maskShape(shape: Optional\<CircleShape | EllipseShape | PathShape | RectShape>): T 318 319为组件上添加指定形状的遮罩。与[maskShape<sup>12+</sup>](#maskshape12)相比，shape参数新增了对undefined类型的支持。 320 321**系统能力：** SystemCapability.ArkUI.ArkUI.Full 322 323**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 324 325**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 331| shape | Optional\<[CircleShape](#circleshape12) \| [EllipseShape](#ellipseshape12) \| [PathShape](#pathshape12) \| [RectShape](#rectshape12)> | 是 | 在当前组件上加上指定形状的遮罩。<br/>当shape的值为undefined时，维持上次取值。 | 332 333**返回值：** 334 335| 类型 | 说明 | 336| ------ | ------------------------ | 337| T | 返回当前组件。 | 338 339## ProgressMask<sup>10+</sup> 340 341ProgressMask设置遮罩的进度、最大值和颜色。 342 343**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 344 345**系统能力：** SystemCapability.ArkUI.ArkUI.Full 346 347### constructor<sup>10+</sup> 348 349constructor(value: number, total: number, color: ResourceColor) 350 351构造ProgressMask对象。 352 353**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 354 355**系统能力：** SystemCapability.ArkUI.ArkUI.Full 356 357**参数：** 358 359| 参数名 | 类型 | 必填 | 说明 | 360| ------ | ------------------------------------------ | ---- | ------------------ | 361| value | number | 是 | 进度遮罩的当前值。<br/> 取值范围：[0.0, +∞) | 362| total | number | 是 | 进度遮罩的最大值。<br/> 取值范围：[0.0, +∞) | 363| color | [ResourceColor](ts-types.md#resourcecolor) | 是 | 进度遮罩的颜色。 | 364 365### updateProgress<sup>10+</sup> 366 367updateProgress(value: number): void 368 369更新进度遮罩的进度值。 370 371**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 372 373**系统能力：** SystemCapability.ArkUI.ArkUI.Full 374 375**参数：** 376 377| 参数名 | 类型 | 必填 | 说明 | 378| ------ | -------- | ---- | ------------------ | 379| value | number | 是 | 进度遮罩的当前值。 | 380 381### updateColor<sup>10+</sup> 382 383updateColor(value: ResourceColor): void 384 385更新进度遮罩的颜色。 386 387**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 388 389**系统能力：** SystemCapability.ArkUI.ArkUI.Full 390 391**参数：** 392 393| 参数名 | 类型 | 必填 | 说明 | 394| ------ | ------------------------------------------ | ---- | ---------------- | 395| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 进度遮罩的颜色。 | 396 397### enableBreathingAnimation<sup>12+</sup> 398 399enableBreathingAnimation(value: boolean): void 400 401进度满时的呼吸光晕动画开关。默认关闭呼吸光晕动画。 402 403**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 404 405**系统能力：** SystemCapability.ArkUI.ArkUI.Full 406 407**参数：** 408 409| 参数名 | 类型 | 必填 | 说明 | 410| ------ | ------------------------------------------ | ---- | ---------------- | 411| value | boolean | 是 | 设置为true则开启呼吸光晕动画。默认值：false | 412 413 414## 示例 415 416### 示例1（使用不同裁剪属性） 417 418```ts 419// xxx.ets 420import { CircleShape, RectShape } from '@kit.ArkUI'; 421 422@Entry 423@Component 424struct ClipAndMaskExample { 425 build() { 426 Column({ space: 15 }) { 427 Text('clip').fontSize(12).width('75%').fontColor('#DCDCDC') 428 Row() { 429 // $r("app.media.testImg")需要替换为开发者所需的图像资源文件。 430 Image($r('app.media.testImg')).width('500px').height('280px') 431 } 432 .clip(true) // 如这里不设置clip为true，则Row组件的圆角不会限制其中的Image组件，Image组件的四个角会超出Row 433 .borderRadius(20) 434 435 // 用一个280px直径的圆对图片进行裁剪 436 // $r("app.media.testImg")需要替换为开发者所需的图像资源文件。 437 Image($r('app.media.testImg')) 438 .clipShape(new CircleShape({ width: '280px', height: '280px' })) 439 .width('500px').height('280px') 440 441 Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC') 442 // 给图片添加了一个500px*280px的方形遮罩 443 // $r("app.media.testImg")需要替换为开发者所需的图像资源文件。 444 Image($r('app.media.testImg')) 445 .maskShape(new RectShape({ width: '500px', height: '280px' }).fill(Color.Gray)) 446 .width('500px').height('280px') 447 448 // 给图片添加了一个280px*280px的圆形遮罩 449 // $r("app.media.testImg")需要替换为开发者所需的图像资源文件。 450 Image($r('app.media.testImg')) 451 .maskShape(new CircleShape({ width: '280px', height: '280px' }).fill(Color.Gray)) 452 .width('500px').height('280px') 453 } 454 .width('100%') 455 .margin({ top: 15 }) 456 } 457} 458``` 459 460 461 462### 示例2（裁剪属性动画） 463 464```ts 465@Entry 466@Component 467struct ProgressMaskExample { 468 @State progressFlag1: boolean = true; 469 @State color: Color = 0x01006CDE; 470 @State value: number = 10.0; 471 @State enableBreathingAnimation: boolean = false; 472 @State progress: ProgressMask = new ProgressMask(10.0, 100.0, Color.Gray); 473 474 build() { 475 Column({ space: 15 }) { 476 Text('progress mask').fontSize(12).width('75%').fontColor('#DCDCDC') 477 // 给图片添加了一个280px*280px的进度遮罩 478 // $r("app.media.testImg")需要替换为开发者所需的图像资源文件。 479 Image($r('app.media.testImg')) 480 .width('500px').height('280px') 481 .mask(this.progress) 482 .animation({ 483 duration: 2000, // 动画时长 484 curve: Curve.Linear, // 动画曲线 485 delay: 0, // 动画延迟 486 iterations: 1, // 播放次数 487 playMode: PlayMode.Normal // 动画模式 488 }) // 对Button组件的宽高属性进行动画配置 489 490 // 更新进度遮罩的进度值 491 Button('updateProgress') 492 .onClick((event?: ClickEvent) => { 493 this.value += 10; 494 this.progress.updateProgress(this.value); 495 }).width(200).height(50).margin(20) 496 497 // 更新进度遮罩的颜色 498 Button('updateColor') 499 .onClick((event?: ClickEvent) => { 500 if (this.progressFlag1) { 501 this.progress.updateColor(0x9fff0000); 502 } else { 503 this.progress.updateColor(0x9f0000ff); 504 } 505 this.progressFlag1 = !this.progressFlag1 506 }).width(200).height(50).margin(20) 507 508 // 开关呼吸光晕动画 509 Button('enableBreathingAnimation:' + this.enableBreathingAnimation) 510 .onClick((event?: ClickEvent) => { 511 this.enableBreathingAnimation = !this.enableBreathingAnimation; 512 this.progress.enableBreathingAnimation(this.enableBreathingAnimation); 513 }).width(200).height(50).margin(20) 514 515 // 恢复进度遮罩 516 Button('click reset!') 517 .onClick((event?: ClickEvent) => { 518 this.value = 0; 519 this.progress.updateProgress(this.value); 520 }).width(200).height(50).margin(20) 521 } 522 .width('100%') 523 .margin({ top: 15 }) 524 } 525} 526``` 527 528 529
