Progress

进度条组件，用于显示内容加载或操作处理等进度。支持线性、环形、圆形、胶囊等多种样式，可自定义颜色、渐变效果和动效，适用于文件下载、数据加载、任务处理等需要展示进度状态的场景。通过丰富的样式与动效配置，可快速实现进度可视化，提升用户体验。

该组件从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

子组件

无

接口

Progress(options: ProgressOptions)

创建进度条组件。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
options	ProgressOptions	是	按进度条类型不同，设置不同属性的进度条组件参数。

ProgressOptions对象说明

进度条选项。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
value	number	否	否	指定当前进度值。默认值：0 取值范围：[0, total]，设置小于0的数值时置为0，设置大于total的数值时置为total，设置非法值时按默认值处理。卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。元服务API：从API version 11开始，该接口支持在元服务中使用。
total	number	否	是	指定进度总长。设置小于0的数值时置为100。默认值：100 取值范围：(0, +∞)。卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。元服务API：从API version 11开始，该接口支持在元服务中使用。
type⁸⁺	Type	否	是	指定进度条类型。Type继承于ProgressStyleMap。默认值：ProgressType.Linear 卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。说明：不同的ProgressType需分别对应相应的style属性设置，详细映射关系参考ProgressStyleMap。元服务API：从API version 11开始，该接口支持在元服务中使用。
style^(deprecated)	ProgressStyle	否	是	指定进度条样式。从API version 7开始支持，从API version 8开始废弃。建议使用type替代。默认值：ProgressStyle.Linear

ProgressType⁸⁺枚举说明

进度条类型。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
Linear	0	线性样式。从API version 9开始，当高度大于宽度时，自适应垂直显示。
Ring	1	环形无刻度样式，环形圆环逐渐显示直至完全填充。
Eclipse	2	圆形样式，显示类似月圆月缺的进度展示效果，从月牙逐渐变化至满月。
ScaleRing	3	环形有刻度样式，显示类似时钟刻度形式的进度展示效果。从API version 9开始，刻度外圈出现重叠时自动转换为环形无刻度进度条。
Capsule	4	胶囊样式，头尾两端圆弧处的进度展示效果与Eclipse相同，中段的进度展示效果与Linear相同。从API version 9开始，当高度大于宽度时，自适应垂直显示。

ProgressStyle枚举说明

进度条样式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
Linear	0	线性样式，进度条沿直线方向从一端逐渐填充至另一端。
Ring⁸⁺	1	环形无刻度样式，环形圆环逐渐显示直至完全填充。
Eclipse	2	圆形样式，显示类似月圆月缺的进度展示效果，从月牙逐渐变化至满月。
ScaleRing⁸⁺	3	环形有刻度样式，显示类似时钟刻度形式的进度展示效果。从API version 9开始，刻度外圈出现重叠时自动转换为环形无刻度进度条。
Capsule⁸⁺	4	胶囊样式，头尾两端圆弧处的进度展示效果与Eclipse相同，中段的进度展示效果与Linear相同。从API version 9开始，当高度大于宽度时，自适应垂直显示。

ProgressStyleMap¹⁰⁺对象说明

进度条类型和样式的映射表。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型
[ProgressType.Linear]	LinearStyleOptions \| ProgressStyleOptions
[ProgressType.Ring]	RingStyleOptions \| ProgressStyleOptions
[ProgressType.Eclipse]	EclipseStyleOptions \| ProgressStyleOptions
[ProgressType.ScaleRing]	ScaleRingStyleOptions \| ProgressStyleOptions
[ProgressType.Capsule]	CapsuleStyleOptions \| ProgressStyleOptions

属性

除支持通用属性外，还支持以下属性：

该组件重写了通用属性backgroundColor，直接添加在Progress组件上，设置进度条的底色。如需设置整个Progress组件的背景色，需要在外层容器上添加backgroundColor，并用该容器包裹Progress组件。

[h2]value

value(value: number)

设置当前进度值。设置小于0的数值时置为0，设置大于total的数值时置为total。设置非法值时按默认值处理。当Ring样式的status属性设置为ProgressStatus.LOADING时，设置进度值不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	当前进度值。默认值：0 取值范围：[0, total]，设置小于0的数值时置为0，设置大于total的数值时置为total，设置非法值时按默认值处理。说明：当Ring类型进度条的status设置为ProgressStatus.LOADING时，设置进度值不生效。

参数名

类型

必填

说明

value

number

是

当前进度值。

默认值：0

取值范围：[0, total]，设置小于0的数值时置为0，设置大于total的数值时置为total，设置非法值时按默认值处理。

说明： 当Ring类型进度条的status设置为ProgressStatus.LOADING时，设置进度值不生效。

[h2]color

color(value: ResourceColor | LinearGradient)

设置进度条前景色。

从API version 10开始支持利用LinearGradient设置Ring样式的渐变色。Ring类型不建议设置透明度，如需设置透明度，建议使用DataPanel。

从API version 23开始支持利用LinearGradient设置Linear样式和Capsule样式的渐变色。API version 22及之前版本使用该方式设置时，会以默认主题色显示。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用，暂不支持LinearGradient。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor \| LinearGradient	是	进度条前景色。从API version 10开始支持利用LinearGradient设置Ring样式的渐变色，从API version 23开始支持利用LinearGradient设置Linear样式和Capsule样式的渐变色。默认值： - Capsule： API version 9及以下：'#ff007dff' API version 10：'#33006cde' API version 11及以上：'#33007dff' - Ring： API version 9及以下：'#ff007dff' API version 10及以上：起始端：'#ff86c1ff'，结束端：'#ff254ff7' - 其他样式：'#ff007dff'

参数名

类型

必填

说明

value

ResourceColor | LinearGradient

是

进度条前景色。

从API version 10开始支持利用LinearGradient设置Ring样式的渐变色，从API version 23开始支持利用LinearGradient设置Linear样式和Capsule样式的渐变色。

默认值：

- Capsule：

API version 9及以下：'#ff007dff'

API version 10：'#33006cde'

API version 11及以上：'#33007dff'

- Ring：

API version 9及以下：'#ff007dff'

API version 10及以上：起始端：'#ff86c1ff'，结束端：'#ff254ff7'

- 其他样式：'#ff007dff'

[h2]style⁸⁺

style(value: Style)

设置组件的样式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Style	是	组件的样式。Style继承于ProgressStyleMap。说明：不同的ProgressType需分别对应相应的style属性设置，详细映射关系参考ProgressStyleMap。 - CapsuleStyleOptions：设置Capsule的样式。 - RingStyleOptions：设置Ring的样式。 - LinearStyleOptions：设置Linear的样式。 - ScaleRingStyleOptions：设置ScaleRing的样式。 - EclipseStyleOptions：设置Eclipse的样式。 - ProgressStyleOptions：仅可设置各类型进度条的strokeWidth、scaleCount、scaleWidth，仅对支持这些样式设置的进度条生效。

参数名

类型

必填

说明

value

Style

是

组件的样式。Style继承于ProgressStyleMap。

说明： 不同的ProgressType需分别对应相应的style属性设置，详细映射关系参考ProgressStyleMap。

- CapsuleStyleOptions：设置Capsule的样式。

- RingStyleOptions：设置Ring的样式。

- LinearStyleOptions：设置Linear的样式。

- ScaleRingStyleOptions：设置ScaleRing的样式。

- EclipseStyleOptions：设置Eclipse的样式。

- ProgressStyleOptions：仅可设置各类型进度条的strokeWidth、scaleCount、scaleWidth，仅对支持这些样式设置的进度条生效。

[h2]contentModifier¹²⁺

contentModifier(modifier:ContentModifier<ProgressConfiguration>)

定制progress内容区的方法。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	ContentModifier<ProgressConfiguration>	是	在Progress组件上，定制内容区的方法。 modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。

参数名

类型

必填

说明

modifier

ContentModifier<ProgressConfiguration>

是

在Progress组件上，定制内容区的方法。

modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。

[h2]privacySensitive¹²⁺

privacySensitive(isPrivacySensitiveMode: Optional<boolean>)

设置隐私敏感。

从API version 20开始，该接口支持在attributeModifier中调用。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
isPrivacySensitiveMode	Optional<boolean>	是	设置隐私敏感，隐私模式下进度清零，文字将被遮罩。true：打开隐私敏感；false：关闭隐私敏感。默认值：false 说明：设置null表示不敏感。

参数名

类型

必填

说明

isPrivacySensitiveMode

Optional<boolean>

是

设置隐私敏感，隐私模式下进度清零，文字将被遮罩。true：打开隐私敏感；false：关闭隐私敏感。

默认值：false

说明：

设置null表示不敏感。

ProgressConfiguration¹²⁺

进度条配置。继承自CommonConfiguration。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
value	number	否	否	当前进度值。当设置的数值小于0时，将其置为0。当设置的数值大于total时，将其置为total。默认值：0 取值范围：[0, total] 说明：当Ring类型进度条的status设置为ProgressStatus.LOADING时，设置进度值不生效。
total	number	否	否	进度总长。取值范围：(0, +∞) 说明： total小于等于0时，按照100处理。

名称

类型

只读

可选

说明

value

number

否

当前进度值。当设置的数值小于0时，将其置为0。当设置的数值大于total时，将其置为total。

默认值：0

取值范围：[0, total]

说明： 当Ring类型进度条的status设置为ProgressStatus.LOADING时，设置进度值不生效。

total

number

否

进度总长。

取值范围：(0, +∞)

说明：

total小于等于0时，按照100处理。

CommonProgressStyleOptions¹⁰⁺

进度条通用样式选项。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
enableSmoothEffect	boolean	否	是	进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，页面会有进度变化的动效；否则进度从当前值突变至设定值，页面无动效。 true：表示开启进度平滑动效。 false：表示关闭进度平滑动效。默认值：true

名称

类型

只读

可选

说明

enableSmoothEffect

boolean

否

是

进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，页面会有进度变化的动效；否则进度从当前值突变至设定值，页面无动效。

true：表示开启进度平滑动效。

false：表示关闭进度平滑动效。

默认值：true

ScanEffectOptions¹⁰⁺

扫光效果选项。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
enableScanEffect	boolean	否	是	扫光效果的开关。仅支持ProgressType类型为Linear、Ring、Capsule的进度条。 true：表示开启扫光效果。 false：表示关闭扫光效果。默认值：false

名称

类型

只读

可选

说明

enableScanEffect

boolean

否

是

扫光效果的开关。仅支持ProgressType类型为Linear、Ring、Capsule的进度条。

true：表示开启扫光效果。

false：表示关闭扫光效果。

默认值：false

ProgressStyleOptions⁸⁺

进度条样式选项。

继承自CommonProgressStyleOptions。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
strokeWidth	Length	否	是	设置进度条宽度（不支持百分比设置）。默认值：4.0vp 取值范围：大于0的数值。超出取值范围或设置非法值时按默认值处理。
scaleCount	number	否	是	设置环形进度条总刻度数。默认值：120 取值范围：[2, min(width, height)*π/scaleWidth]，超出取值范围时，样式显示为环形无刻度进度条。在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。
scaleWidth	Length	否	是	设置环形进度条刻度粗细（不支持百分比设置）。默认值：2.0vp 取值范围：大于0的数值。超出取值范围或设置非法值时按默认值处理。刻度粗细大于进度条宽度时，使用系统默认粗细。在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。

名称

类型

只读

可选

说明

strokeWidth

Length

否

是

设置进度条宽度（不支持百分比设置）。

默认值：4.0vp

取值范围：大于0的数值。

超出取值范围或设置非法值时按默认值处理。

scaleCount

number

否

是

设置环形进度条总刻度数。

默认值：120

取值范围：[2, min(width, height)*π/scaleWidth]，超出取值范围时，样式显示为环形无刻度进度条。

在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。

scaleWidth

Length

否

是

设置环形进度条刻度粗细（不支持百分比设置）。

默认值：2.0vp

取值范围：大于0的数值。

超出取值范围或设置非法值时按默认值处理。

刻度粗细大于进度条宽度时，使用系统默认粗细。

在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。

CapsuleStyleOptions¹⁰⁺

胶囊样式选项。

继承自ScanEffectOptions和CommonProgressStyleOptions。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
borderColor	ResourceColor	否	是	内描边颜色。默认值： API version 10：'#33006cde' API version 11及以上：'#33007dff' 元服务API：从API version 11开始，该接口支持在元服务中使用。
borderWidth	Length	否	是	内描边宽度。默认值：1vp 取值范围：大于等于0的数值，不支持百分比设置。超出取值范围或设置非法值时按默认值处理。元服务API：从API version 11开始，该接口支持在元服务中使用。
content	ResourceStr	否	是	文本内容，应用可自定义。当需要在Capsule进度条上显示自定义文本时传入此参数；不传入时不显示文本内容（若需显示百分比文本，可设置showDefaultPercentage为true）。从API version 20开始，支持Resource类型。元服务API：从API version 11开始，该接口支持在元服务中使用。
font	Font	否	是	文本样式。默认值：文本大小（不支持百分比设置）：12fp 其他文本参数跟随Text组件的主题值。元服务API：从API version 11开始，该接口支持在元服务中使用。
fontColor	ResourceColor	否	是	文本颜色。默认值：'#ff182431' 元服务API：从API version 11开始，该接口支持在元服务中使用。
showDefaultPercentage	boolean	否	是	显示百分比文本的开关。开启后，进度条上显示当前进度的百分比。设置了content属性时该属性不生效。 true：表示显示百分比文本；false：表示不显示百分比文本。默认值：false 元服务API：从API version 11开始，该接口支持在元服务中使用。
borderRadius¹⁸⁺	LengthMetrics	否	是	Capsule进度条圆角半径（不支持百分比设置）。取值范围：[0, 组件高度/2]。默认值：组件高度 / 2。设置非法数值时，按照默认值处理。元服务API：从API version 18开始，该接口支持在元服务中使用。

RingStyleOptions¹⁰⁺

环形无刻度样式选项。

继承自ScanEffectOptions和CommonProgressStyleOptions。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
strokeWidth	Length	否	是	设置进度条宽度。默认值：4.0vp 取值范围：大于0的数值，不支持百分比设置。超出取值范围或设置非法值时按默认值处理。当宽度大于等于半径时，宽度默认修改为半径值的二分之一。
shadow	boolean	否	是	进度条阴影开关。 true：表示打开进度条阴影；false：表示关闭进度条阴影。默认值：false
status	ProgressStatus¹⁰⁺	否	是	设置进度条状态。当设置为ProgressStatus.LOADING时会开启检查更新动效。当从ProgressStatus.LOADING设置为ProgressStatus.PROGRESSING时，检查更新动效会执行到终点再停止。默认值：ProgressStatus.PROGRESSING 说明：当设置为ProgressStatus.LOADING时，进度值设置不生效，具体参见value属性说明。

名称

类型

只读

可选

说明

strokeWidth

Length

否

是

设置进度条宽度。

默认值：4.0vp

取值范围：大于0的数值，不支持百分比设置。

超出取值范围或设置非法值时按默认值处理。

当宽度大于等于半径时，宽度默认修改为半径值的二分之一。

shadow

boolean

否

是

进度条阴影开关。

true：表示打开进度条阴影；false：表示关闭进度条阴影。

默认值：false

status

ProgressStatus¹⁰⁺

否

是

设置进度条状态。当设置为ProgressStatus.LOADING时会开启检查更新动效。当从ProgressStatus.LOADING设置为ProgressStatus.PROGRESSING时，检查更新动效会执行到终点再停止。

默认值：ProgressStatus.PROGRESSING

说明： 当设置为ProgressStatus.LOADING时，进度值设置不生效，具体参见value属性说明。

LinearStyleOptions¹⁰⁺

线性样式选项。

继承自ScanEffectOptions和CommonProgressStyleOptions。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
strokeWidth	Length	否	是	设置进度条宽度。默认值：4.0vp 取值范围：大于0的数值，不支持百分比设置。超出取值范围或设置非法值时按默认值处理。
strokeRadius	PX \| VP \| LPX \| Resource	否	是	设置线性进度条的圆角半径。取值范围[0, strokeWidth / 2]。默认值：strokeWidth / 2。超出取值范围时按默认值处理。

名称

类型

只读

可选

说明

strokeWidth

Length

否

是

设置进度条宽度。

默认值：4.0vp

取值范围：大于0的数值，不支持百分比设置。

超出取值范围或设置非法值时按默认值处理。

strokeRadius

PX | VP | LPX | Resource

否

是

设置线性进度条的圆角半径。

取值范围[0, strokeWidth / 2]。默认值：strokeWidth / 2。

超出取值范围时按默认值处理。

ScaleRingStyleOptions¹⁰⁺

环形有刻度样式选项。

继承自CommonProgressStyleOptions。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
strokeWidth	Length	否	是	设置进度条宽度。默认值：4.0vp 取值范围：大于0的数值（单位：vp），不支持百分比设置。超出取值范围或设置非法值时按默认值处理。
scaleCount	number	否	是	设置环形进度条总刻度数。默认值：120 取值范围：[2, min(width, height)*π/scaleWidth]，超出取值范围时，样式显示为环形无刻度进度条。在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。
scaleWidth	Length	否	是	设置环形进度条刻度粗细（不支持百分比设置）。默认值：2.0vp 取值范围：大于0的数值（单位：vp）。刻度粗细大于进度条宽度时，使用系统默认粗细。在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。

名称

类型

只读

可选

说明

strokeWidth

Length

否

是

设置进度条宽度。

默认值：4.0vp

取值范围：大于0的数值（单位：vp），不支持百分比设置。

超出取值范围或设置非法值时按默认值处理。

scaleCount

number

否

是

设置环形进度条总刻度数。

默认值：120

取值范围：[2, min(width, height)*π/scaleWidth]，超出取值范围时，样式显示为环形无刻度进度条。

在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。

scaleWidth

Length

否

是

设置环形进度条刻度粗细（不支持百分比设置）。

默认值：2.0vp

取值范围：大于0的数值（单位：vp）。

刻度粗细大于进度条宽度时，使用系统默认粗细。

在scaleCount和scaleWidth都与默认值相等的情况下，设置组件宽度或高度小于77vp会显示为环形无刻度进度条。

EclipseStyleOptions¹⁰⁺

圆形样式选项。圆形样式的显示类似月圆月缺的进度展示效果，从月牙逐渐变化至满月。

继承自CommonProgressStyleOptions。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

ProgressStatus¹⁰⁺枚举说明

进度条的当前状态。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
LOADING	'LOADING'	加载中状态。开启检查更新动效，此时设置进度值不生效。
PROGRESSING	'PROGRESSING'	进度更新中。

事件

支持通用事件。

示例

[h2]示例1（设置进度条的类型）

该示例通过ProgressOptions的入参type，实现了设置进度条类型的功能。

// xxx.ets
@Entry
@Component
struct ProgressExample {
  build() {
    Column({ space: 15 }) {
      Text('Linear Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Progress({ value: 10, type: ProgressType.Linear }).width(200)
      Progress({ value: 20, total: 150, type: ProgressType.Linear }).color(Color.Grey).value(50).width(200)


      Text('Eclipse Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Row({ space: 40 }) {
        Progress({ value: 10, type: ProgressType.Eclipse }).width(100)
        Progress({ value: 20, total: 150, type: ProgressType.Eclipse }).color(Color.Grey).value(50).width(100)
      }

      Text('ScaleRing Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Row({ space: 40 }) {
        Progress({ value: 10, type: ProgressType.ScaleRing }).width(100)
        Progress({ value: 20, total: 150, type: ProgressType.ScaleRing })
          .color(Color.Grey).value(50).width(100)
          .style({ strokeWidth: 15, scaleCount: 15, scaleWidth: 5 })
      }

      // scaleCount和scaleWidth效果对比
      Row({ space: 40 }) {
        Progress({ value: 20, total: 150, type: ProgressType.ScaleRing })
          .color(Color.Grey).value(50).width(100)
          .style({ strokeWidth: 20, scaleCount: 20, scaleWidth: 5 })
        Progress({ value: 20, total: 150, type: ProgressType.ScaleRing })
          .color(Color.Grey).value(50).width(100)
          .style({ strokeWidth: 20, scaleCount: 30, scaleWidth: 3 })
      }

      Text('Ring Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Row({ space: 40 }) {
        Progress({ value: 10, type: ProgressType.Ring }).width(100)
        Progress({ value: 20, total: 150, type: ProgressType.Ring })
          .color(Color.Grey).value(50).width(100)
          .style({ strokeWidth: 20 })
      }

      Text('Capsule Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Row({ space: 40 }) {
        Progress({ value: 10, type: ProgressType.Capsule }).width(100).height(50)
        Progress({ value: 20, total: 150, type: ProgressType.Capsule })
          .color(Color.Grey)
          .value(50)
          .width(100)
          .height(50)
      }
    }.width('100%').margin({ top: 30 })
  }
}

[h2]示例2（设置环形进度条属性）

该示例通过style接口的strokeWidth和shadow属性，实现了环形进度条视觉属性设置功能。

// xxx.ets
@Entry
@Component
struct ProgressExample {
  private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 },
    { color: Color.Orange, offset: 1.0 }]);

  build() {
    Column({ space: 15 }) {
      Text('Gradient Color').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Progress({ value: 70, total: 100, type: ProgressType.Ring })
        .width(100).style({ strokeWidth: 20 })
        .color(this.gradientColor)

      Text('Shadow').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Progress({ value: 70, total: 100, type: ProgressType.Ring })
        .width(120).color(Color.Orange)
        .style({ strokeWidth: 20, shadow: true })
    }.width('100%').padding({ top: 5 })
  }
}

[h2]示例3（设置环形进度条动画）

该示例通过style接口的status和enableScanEffect属性，实现了环形进度条动效的开关功能。

// xxx.ets
@Entry
@Component
struct ProgressExample {
  build() {
    Column({ space: 15 }) {
      Text('Loading Effect').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Progress({ value: 0, total: 100, type: ProgressType.Ring })
        .width(100).color(Color.Blue)
        .style({ strokeWidth: 20, status: ProgressStatus.LOADING })

      Text('Scan Effect').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Progress({ value: 30, total: 100, type: ProgressType.Ring })
        .width(100).color(Color.Orange)
        .style({ strokeWidth: 20, enableScanEffect: true })
    }.width('100%').padding({ top: 5 })
  }
}

[h2]示例4（设置胶囊形进度条属性）

该示例通过style接口的borderColor、borderWidth、content、font、fontColor、enableScanEffect、showDefaultPercentage属性，实现胶囊形进度条的视觉属性设置。

// xxx.ets
@Entry
@Component
struct ProgressExample {
  build() {
    Column({ space: 15 }) {
      Row({ space: 40 }) {
        Progress({ value: 100, total: 100, type: ProgressType.Capsule }).width(100).height(50)
          .style({
            borderColor: Color.Blue,
            borderWidth: 1,
            content: 'Installing...',
            font: { size: 13, style: FontStyle.Normal },
            fontColor: Color.Gray,
            enableScanEffect: false,
            showDefaultPercentage: false
          })
      }
    }.width('100%').padding({ top: 5 })
  }
}

[h2]示例5（设置进度平滑动效）

该示例通过style接口的enableSmoothEffect属性，实现了进度平滑动效开关的功能。

// xxx.ets
@Entry
@Component
struct Index {
  @State value: number = 0;

  build() {
    Column({ space: 10 }) {
      Text('enableSmoothEffect: true')
        .fontSize(9)
        .fontColor(0xCCCCCC)
        .width('90%')
        .margin(5)
        .margin({ top: 20 })
      Progress({ value: this.value, total: 100, type: ProgressType.Linear })
        .style({ strokeWidth: 10, enableSmoothEffect: true })

      Text('enableSmoothEffect: false').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5)
      Progress({ value: this.value, total: 100, type: ProgressType.Linear })
        .style({ strokeWidth: 10, enableSmoothEffect: false })

      Button('value +10').onClick(() => {
        this.value += 10;
      })
        .width(75)
        .height(15)
        .fontSize(9)
    }
    .width('50%')
    .height('100%')
    .margin({ left: 20 })
  }
}

[h2]示例6（设置定制内容区）

该示例通过contentModifier接口，实现了自定义进度条的功能，自定义实现星形，其中总进度为3，且当前值可通过按钮进行增减，达到的进度使用自定义颜色填充。

// xxx.ets
class MyProgressModifier implements ContentModifier<ProgressConfiguration> {
  color: ResourceColor = Color.White;

  constructor(color: ResourceColor) {
    this.color = color;
  }

  applyContent(): WrappedBuilder<[ProgressConfiguration]> {
    return wrapBuilder(myProgress);
  }
}

@Builder
function myProgress(config: ProgressConfiguration) {

  Column({ space: 30 }) {
    Text('当前进度：' + config.value + '/' + config.total).fontSize(20)
    Row() {
      Flex({ justifyContent: FlexAlign.SpaceBetween }) {
        Path()
          .width('30%')
          .height('30%')
          .commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z')
          .fill(config.enabled && config.value >= 1 ? (config.contentModifier as MyProgressModifier).color :
          Color.White)
          .stroke(Color.Black)
          .strokeWidth(3)
        Path()
          .width('30%')
          .height('30%')
          .commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z')
          .fill(config.enabled && config.value >= 2 ? (config.contentModifier as MyProgressModifier).color :
          Color.White)
          .stroke(Color.Black)
          .strokeWidth(3)
        Path()
          .width('30%')
          .height('30%')
          .commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z')
          .fill(config.enabled && config.value >= 3 ? (config.contentModifier as MyProgressModifier).color :
          Color.White)
          .stroke(Color.Black)
          .strokeWidth(3)
      }.width('100%')
    }
  }.margin({ bottom: 100 })
}

@Entry
@Component
struct Index {
  @State currentValue: number = 0;
  modifier = new MyProgressModifier('rgb(39, 135, 217)');

  build() {
    Column() {
      Progress({ value: this.currentValue, total: 3, type: ProgressType.Ring }).contentModifier(this.modifier)
      Button('Progress++').onClick(() => {
        if (this.currentValue < 3) {
          this.currentValue += 1;
        }
      }).width('30%')
      Button('Progress--').onClick(() => {
        if (this.currentValue > 0) {
          this.currentValue -= 1;
        }
      }).width('30%').margin('10')
    }.width('100%').height('100%')
  }
}

[h2]示例7（设置隐私隐藏）

该示例通过privacySensitive属性，实现了隐私隐藏效果。效果展示需要卡片框架支持。

@Entry
@Component
struct ProgressExample {
  build() {
    Row() {
      Column({ space: 15 }) {
        Progress({ value: 33, total: 100, type: ProgressType.Capsule }).width(300).height(50)
          .color(Color.Blue)
          .style({
            borderWidth: 5,
            font: { size: 13, style: FontStyle.Normal },
            enableScanEffect: false,
            showDefaultPercentage: true
          })
          .privacySensitive(true)
        Progress({ value: 33, total: 100, type: ProgressType.Capsule }).width(300).height(50)
          .color(Color.Blue)
          .style({
            borderWidth: 5,
            content: 'Installing...',
            font: { size: 13, style: FontStyle.Normal },
            enableScanEffect: false,
          })
          .privacySensitive(true)
      }
    }
  }
}

[h2]示例8（设置Capsule进度条圆角半径）

该示例通过CapsuleStyleOptions的入参borderRadius，实现了Capsule类型进度条圆角半径设置。

从API version 18开始，新增borderRadius属性。

import { LengthMetrics } from '@kit.ArkUI';

@Entry
@Component
struct ProgressExample {
  build() {
    Column({ space: 15 }) {
      Text('Capsule Progress').fontSize(9).width('90%')
      Row({ space: 15 }) {
        Progress({ value: 30, total: 100, type: ProgressType.Capsule })
          .style({ content: '默认圆角', borderWidth: 5 })
          .width(100)
          .height(60)
      }

      Row({ space: 15 }) {
        Progress({ value: 30, total: 100, type: ProgressType.Capsule })
          .style({ content: '圆角为20vp', borderWidth: 5, borderRadius: LengthMetrics.vp(20) })
          .width(100)
          .height(60)
      }
    }
    .width('100%')
    .margin({ top: 30 })
  }
}

[h2]示例9（设置线性进度条和胶囊进度条属性）

从API version 23开始，该示例通过color属性中的LinearGradient，实现线性进度条和胶囊进度条渐变色的功能。

// xxx.ets
@Entry
@Component
struct ProgressExample {
  private linearGradientColor: LinearGradient = new LinearGradient([{ color: "#87BDF9", offset: 0.5 },
    { color: "#3662F0", offset: 1.0 }]);
  public capsuleGradientColor: LinearGradient = new LinearGradient([{ color: "#A5A5AF", offset: 0.5 },
    { color: "#67666C", offset: 1.0 }]);

  build() {
    Column({ space: 15 }) {
      Text('Linear：').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Progress({ value: 70, total: 100, type: ProgressType.Linear })
        .width(100).style({ strokeWidth: 20 })
        .color(this.linearGradientColor)

      Text('Capsule：').fontSize(9).fontColor(0xCCCCCC).width('90%')
      Progress({ value: 50, total: 100, type: ProgressType.Capsule })
        .width(120).style({ strokeWidth: 40 })
        .color(this.capsuleGradientColor)
    }.width('100%').padding({ top: 5 })
  }
}

目录

Progress

子组件

接口

ProgressOptions对象说明

ProgressType8+枚举说明

ProgressStyle枚举说明

ProgressStyleMap10+对象说明

属性

[h2]value

[h2]color

[h2]style8+

[h2]contentModifier12+

[h2]privacySensitive12+

ProgressConfiguration12+

CommonProgressStyleOptions10+

ScanEffectOptions10+

ProgressStyleOptions8+

CapsuleStyleOptions10+

RingStyleOptions10+

LinearStyleOptions10+

ScaleRingStyleOptions10+

EclipseStyleOptions10+

ProgressStatus10+枚举说明

事件

示例

[h2]示例1（设置进度条的类型）

[h2]示例2（设置环形进度条属性）

[h2]示例3（设置环形进度条动画）

[h2]示例4（设置胶囊形进度条属性）

[h2]示例5（设置进度平滑动效）

[h2]示例6（设置定制内容区）

[h2]示例7（设置隐私隐藏）

[h2]示例8（设置Capsule进度条圆角半径）

[h2]示例9（设置线性进度条和胶囊进度条属性）

ProgressType⁸⁺枚举说明

ProgressStyleMap¹⁰⁺对象说明

[h2]style⁸⁺

[h2]contentModifier¹²⁺

[h2]privacySensitive¹²⁺

ProgressConfiguration¹²⁺

CommonProgressStyleOptions¹⁰⁺

ScanEffectOptions¹⁰⁺

ProgressStyleOptions⁸⁺

CapsuleStyleOptions¹⁰⁺

RingStyleOptions¹⁰⁺

LinearStyleOptions¹⁰⁺

ScaleRingStyleOptions¹⁰⁺

EclipseStyleOptions¹⁰⁺

ProgressStatus¹⁰⁺枚举说明