用于对组件进行裁剪、遮罩处理。
从API version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
clip(value: boolean): T
是否对子组件超出当前组件范围外的区域进行裁剪。设置value为true时,子组件超出当前组件范围外的区域将被裁剪不可见;设置value为false时,不对子组件进行裁剪。未设置时,默认不对子组件超出当前组件范围外的区域进行裁剪。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | boolean | 是 | 设置子组件是否按照当前组件边缘轮廓进行裁剪。 true表示子组件按照当前组件边缘轮廓进行裁剪,false表示不对子组件进行裁剪。 说明: 设置为true后,子组件超出当前组件范围外的区域将不响应绑定的手势事件。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
clip(clip: Optional<boolean>): T
是否对子组件超出当前组件范围外的区域进行裁剪。未设置时,默认不对子组件超出当前组件范围外的区域进行裁剪。与clip12+相比,新增了对undefined类型的支持。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 18开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 18开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| clip | Optional<boolean> | 是 | 设置子组件是否按照当前组件边缘轮廓进行裁剪。true表示子组件按照当前组件边缘轮廓进行裁剪,false表示不对子组件进行裁剪。 说明: 设置为true后,子组件超出当前组件范围外的区域将不响应绑定的手势事件。 当clip的值为undefined时,恢复为不对子组件超出当前组件范围外的区域进行裁剪。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute): T
按指定的形状对当前组件进行裁剪,或设置是否按照当前组件边缘轮廓进行裁剪。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | 是 | 参数为相应类型的组件,按指定的形状对当前组件和子组件进行裁剪;参数为boolean类型时,设置是否按照当前组件边缘轮廓进行裁剪。 默认值:false true表示按当前组件边缘轮廓进行裁剪,false表示不进行裁剪。 说明: 参数为对应类型的组件时,裁剪不会导致被裁剪区域无法响应绑定的手势事件。参数为boolean类型时,裁剪会导致被裁剪区域无法响应绑定的手势事件。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
clipShape(value: CircleShape | EllipseShape | PathShape | RectShape): T
按指定的形状(形状中可包含位置信息)对当前组件进行裁剪,将组件超出形状范围外的区域裁剪掉使其不可见。与maskShape不同,clipShape是将组件超出形状范围外的区域裁剪掉(不可见),而maskShape是在组件上叠加指定形状的遮罩覆盖层。
不同的形状支持的属性范围不同,路径是一种形状,除此之外还有椭圆、矩形等形状。
路径的形状不支持设置宽度和高度。具体形状支持的属性参考具体形状的文档。
形状中的fill属性对clipShape接口不生效。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | CircleShape | EllipseShape | PathShape | RectShape | 是 | 参数为相应类型的组件,按指定的形状(形状中可包含位置信息)对当前组件进行裁剪。 说明: 裁剪不会导致被裁剪区域无法响应绑定的手势事件。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
clipShape(shape: Optional<CircleShape | EllipseShape | PathShape | RectShape>): T
按指定的形状(形状中可包含位置信息)对当前组件进行裁剪。与clipShape12+相比,新增了对undefined类型的支持。
不同的形状支持的属性范围不同,路径是一种形状,除此之外还有椭圆、矩形等形状。
路径的形状不支持设置宽度和高度。具体形状支持的属性参考具体形状的文档。
形状中的fill属性对clipShape接口不生效。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 18开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 18开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| shape | Optional<CircleShape | EllipseShape | PathShape | RectShape> | 是 | 参数为相应类型的组件,按指定的形状(形状中可包含位置信息)对当前组件进行裁剪。 说明: 裁剪不会导致被裁剪区域无法响应绑定的手势事件。 当shape的值为undefined时,恢复为不添加指定形状的裁剪。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
type CircleShape = import('../api/@ohos.arkui.shape').CircleShape
导入CircleShape类型对象。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
| 类型 | 说明 |
|---|---|
| import('../api/@ohos.arkui.shape').CircleShape | 圆形形状。 |
type EllipseShape = import('../api/@ohos.arkui.shape').EllipseShape
导入EllipseShape类型对象。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
| 类型 | 说明 |
|---|---|
| import('../api/@ohos.arkui.shape').EllipseShape | 椭圆形状。 |
type PathShape = import('../api/@ohos.arkui.shape').PathShape
导入PathShape类型对象。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
| 类型 | 说明 |
|---|---|
| import('../api/@ohos.arkui.shape').PathShape | 路径形状。 |
type RectShape = import('../api/@ohos.arkui.shape').RectShape
导入RectShape类型对象。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
| 类型 | 说明 |
|---|---|
| import('../api/@ohos.arkui.shape').RectShape | 矩形形状。 |
mask(value: ProgressMask): T
为组件添加可调节进度的遮罩,遮罩覆盖在组件内容上方,通过进度值控制遮罩的显示范围。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
元服务API: 从API version 12开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | ProgressMask | 是 | 在当前组件上加上可动态设置进度、最大值和颜色的遮罩。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
mask(mask: Optional<ProgressMask>): T
为组件添加可调节进度的遮罩,遮罩覆盖在组件内容上方,通过进度值控制遮罩的显示范围。与mask12+相比,新增了对undefined类型的支持。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
元服务API: 从API version 18开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mask | Optional<ProgressMask> | 是 | 在当前组件上加上可动态设置进度和颜色的遮罩。遮罩的最大值(total)在构造ProgressMask对象时设定,不可动态修改。可通过ProgressMask对象的updateProgress()方法更新进度值、updateColor()方法更新颜色、enableBreathingAnimation()方法开关呼吸光晕动画。 当mask的值为undefined时,恢复为无进度遮罩效果。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask): T
为组件添加指定形状或可调节进度的遮罩。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask10+ | 是 | 参数为对应形状类型的组件时,在当前组件上加上指定形状的遮罩(圆形、椭圆、路径或矩形);参数为ProgressMask时,在当前组件上加上可动态设置进度和颜色的遮罩。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
maskShape(value: CircleShape | EllipseShape | PathShape | RectShape): T
为组件添加指定形状的遮罩,在组件上叠加指定形状的覆盖层。
不同的形状支持的属性范围不同,路径是一种形状,除此之外还有椭圆、矩形等形状。
路径的形状不支持设置宽度和高度。具体形状支持的属性参考具体形状的文档。
形状中的fill属性对maskShape接口生效,用于设置遮罩的颜色。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | CircleShape | EllipseShape | PathShape | RectShape | 是 | 在当前组件上加上指定形状的遮罩或可调节进度的遮罩。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
maskShape(shape: Optional<CircleShape | EllipseShape | PathShape | RectShape>): T
为组件添加指定形状的遮罩,在组件上叠加指定形状的覆盖层。与maskShape12+相比,新增了对undefined类型的支持。
不同的形状支持的属性范围不同,路径是一种形状,除此之外还有椭圆、矩形等形状。
路径的形状不支持设置宽度和高度。具体形状支持的属性参考具体形状的文档。
形状中的fill属性对maskShape接口生效,用于设置遮罩的颜色。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
卡片能力: 从API version 18开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 18开始,该接口支持在元服务中使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| shape | Optional<CircleShape | EllipseShape | PathShape | RectShape> | 是 | 参数为对应形状类型的组件时,在当前组件上加上指定形状的遮罩(圆形、椭圆、路径或矩形);参数为ProgressMask时,在当前组件上加上可动态设置进度、最大值和颜色的遮罩。 当shape的值为undefined时,会重置当前值,恢复为无指定形状遮罩效果。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
ProgressMask用于设置遮罩的进度、最大值和颜色。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
constructor(value: number, total: number, color: ResourceColor)
构造ProgressMask对象。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | number | 是 | 进度遮罩的当前值,与total配合使用确定进度比例,当value等于total时表示进度满。 取值范围:[0.0, +∞)。传入负数时自动修正为0。 |
| total | number | 是 | 进度遮罩的最大值。 取值范围:[0.0, +∞)。传入负数时自动修正为100。 |
| color | ResourceColor | 是 | 进度遮罩的颜色。 |
updateProgress(value: number): void
更新进度遮罩的进度值。
使用说明:
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | number | 是 | 进度遮罩的当前值。 取值范围:[0.0, +∞)。传入负数时自动修正为0。 |
updateColor(value: ResourceColor): void
更新进度遮罩的颜色。
使用说明:
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | ResourceColor | 是 | 进度遮罩的颜色。 |
enableBreathingAnimation(value: boolean): void
进度满时的呼吸光晕动画开关,开启后进度满时遮罩边缘会出现周期性明暗变化的发光效果。未设置时,默认关闭呼吸光晕动画。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | boolean | 是 | 是否开启进度满时的呼吸光晕动画。 true:开启呼吸光晕动画。 false:关闭呼吸光晕动画。 |
该示例通过clipShape、clip、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() {
// $r("app.media.testImg")需要替换为开发者所需的图像资源文件。
Image($r('app.media.testImg')).width('500px').height('280px')
}
.clip(true) // 如这里不设置clip为true,则Row组件的圆角不会限制其中的Image组件,Image组件的四个角会超出Row
.borderRadius(20)
// 用一个280px直径的圆对图片进行裁剪
// $r("app.media.testImg")需要替换为开发者所需的图像资源文件。
Image($r('app.media.testImg'))
.clipShape(new CircleShape({ width: '280px', height: '280px' }))
.width('500px').height('280px')
Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC')
// 给图片添加了一个500px*280px的方形遮罩
// $r("app.media.testImg")需要替换为开发者所需的图像资源文件。
Image($r('app.media.testImg'))
.maskShape(new RectShape({ width: '500px', height: '280px' }).fill(Color.Gray))
.width('500px').height('280px')
// 给图片添加了一个280px*280px的圆形遮罩
// $r("app.media.testImg")需要替换为开发者所需的图像资源文件。
Image($r('app.media.testImg'))
.maskShape(new CircleShape({ width: '280px', height: '280px' }).fill(Color.Gray))
.width('500px').height('280px')
}
.width('100%')
.margin({ top: 15 })
}
} 
该示例通过mask实现图片的遮罩。
@Entry
@Component
struct ProgressMaskExample {
@State isRedColor: boolean = true;
@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')
// 给图片添加了一个进度遮罩
// $r("app.media.testImg")需要替换为开发者所需的图像资源文件。
Image($r('app.media.testImg'))
.width('500px').height('280px')
.mask(this.progress)
.animation({
duration: 2000, // 动画时长
curve: Curve.Linear, // 动画曲线
delay: 0, // 动画延迟
iterations: 1, // 播放次数
playMode: PlayMode.Normal // 动画模式
}) // 对Image组件的遮罩进度变化进行动画配置
// 更新进度遮罩的进度值
Button('updateProgress')
.onClick((event?: ClickEvent) => {
this.value += 10;
this.progress.updateProgress(this.value);
}).width(200).height(50).margin(20)
// 更新进度遮罩的颜色
Button('updateColor')
.onClick((event?: ClickEvent) => {
if (this.isRedColor) {
this.progress.updateColor(0x9fff0000);
} else {
this.progress.updateColor(0x9f0000ff);
}
this.isRedColor = !this.isRedColor;
}).width(200).height(50).margin(20)
// 开关呼吸光晕动画
Button('enableBreathingAnimation:' + this.enableBreathingAnimation)
.onClick((event?: ClickEvent) => {
this.enableBreathingAnimation = !this.enableBreathingAnimation;
this.progress.enableBreathingAnimation(this.enableBreathingAnimation);
}).width(200).height(50).margin(20)
// 恢复进度遮罩
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 })
}
} 