往期鸿蒙5.0全套实战文章必看:(文中附带全栈鸿蒙5.0学习资料)
Progress
进度条组件,用于显示内容加载或操作处理等进度。
说明
该组件从API version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
子组件
无
接口
Progress(options: ProgressOptions)
创建进度条组件。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | ProgressOptions | 是 | 按进度条类型不同,设置不同属性的进度条组件参数。 |
ProgressOptions<Type>对象说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
value | number | 是 | 指定当前进度值。设置小于0的数值时置为0,设置大于total的数值时置为total。 默认值:0 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
total | number | 否 | 指定进度总长。设置小于等于0的数值时置为100。 默认值:100 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
type8+ | ProgressType | 否 | 指定进度条类型。 默认值:ProgressType.Linear 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
style(deprecated) | ProgressStyle | 否 | 指定进度条样式。 该参数从API version8开始废弃,建议使用type替代。 默认值:ProgressStyle.Linear |
ProgressType8+枚举说明
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 描述 |
---|---|
Linear | 线性样式。从API version9开始,高度大于宽度的时候自适应垂直显示。 |
Ring | 环形无刻度样式,环形圆环逐渐显示至完全填充效果。 |
Eclipse | 圆形样式,显示类似月圆月缺的进度展示效果,从月牙逐渐变化至满月。 |
ScaleRing | 环形有刻度样式,显示类似时钟刻度形式的进度展示效果。从API version9开始,刻度外圈出现重叠的时候自动转换为环形无刻度进度条。 |
Capsule | 胶囊样式,头尾两端圆弧处的进度展示效果与Eclipse相同;中段处的进度展示效果与Linear相同。高度大于宽度的时候自适应垂直显示。 |
ProgressStyle枚举说明
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 描述 |
---|---|
Linear | 线性样式。 |
Ring8+ | 环形无刻度样式,环形圆环逐渐显示至完全填充效果。 |
Eclipse | 圆形样式,显示类似月圆月缺的进度展示效果,从月牙逐渐变化至满月。 |
ScaleRing8+ | 环形有刻度样式,显示类似时钟刻度形式的进度展示效果。 |
Capsule8+ | 胶囊样式,头尾两端圆弧处的进度展示效果与Eclipse相同;中段处的进度展示效果与Linear相同。高度大于宽度的时候自适应垂直显示。 |
ProgressStyleMap说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 |
---|---|
ProgressType.Linear | LinearStyleOptions10+ | ProgressStyleOptions8+ |
ProgressType.Ring | RingStyleOptions10+ | ProgressStyleOptions8+ |
ProgressType.Eclipse | EclipseStyleOptions10+ | ProgressStyleOptions8+ |
ProgressType.ScaleRing | ScaleRingStyleOptions10+ | ProgressStyleOptions8+ |
ProgressType.Capsule | CapsuleStyleOptions10+ | ProgressStyleOptions8+ |
属性
除支持通用属性外,还支持以下属性:
说明
该组件重写了通用属性backgroundColor,直接添加在Progress组件上,生效进度条的底色。如需设置整个Progress组件的背景色,需要在外层容器上添加backgroundColor,容器再包裹Progress组件。
value
value(value: number)
设置当前进度值。设置小于0的数值时置为0,设置大于total的数值时置为total。非法数值不生效。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | number | 是 | 当前进度值。 默认值:0 |
color
color(value: ResourceColor | LinearGradient)
设置进度条前景色。
从API version 10开始支持利用LinearGradient设置Ring样式的渐变色。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用,暂不支持LinearGradient。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | ResourceColor | LinearGradient10+ | 是 | 进度条前景色。 默认值: - Capsule: API version 9及以下:'#ff007dff' API version 10:'#33006cde' API version 11及以上:'#33007dff' - Ring: API version 9及以下:'#ff007dff' API version 10及以上:起始端:'#ff86c1ff',结束端:'#ff254ff7' - 其他样式:'#ff007dff' |
style8+
style(value: ProgressStyleOptions | CapsuleStyleOptions | RingStyleOptions | LinearStyleOptions | ScaleRingStyleOptions | EclipseStyleOptions)
设置组件的样式。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | ProgressStyleOptions8+ | CapsuleStyleOptions10+ | | 是 | 组件的样式。 - CapsuleStyleOptions:设置Capsule的样式。 - RingStyleOptions:设置Ring的样式。 - LinearStyleOptions:设置Linear的样式。 - ScaleRingStyleOptions:设置ScaleRing的样式。 - EclipseStyleOptions:设置Eclipse的样式。 - ProgressStyleOptions:仅可设置各类型进度条的基本样式。 ProgressStyleOptions,暂不支持其它的参数类型。 |
contentModifier12+
contentModifier(modifier:ContentModifier<ProgressConfiguration>)
定制progress内容区的方法。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
modifier | ContentModifier<ProgressConfiguration> | 是 | 在progress组件上,定制内容区的方法。 modifier: 内容修改器,开发者需要自定义class实现ContentModifier接口。 |
privacySensitive12+
privacySensitive(isPrivacySensitiveMode: Optional<boolean>)
设置隐私敏感。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
isPrivacySensitiveMode | [Optional<boolean>] | 是 | 设置隐私敏感,隐私模式下进度清零,文字将被遮罩。 说明: 设置null则不敏感。 |
ProgressConfiguration12+
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
value | number | 是 | 当前进度值。 |
total | number | 是 | 进度总长。 |
CommonProgressStyleOptions10+
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
enableSmoothEffect | boolean | 否 | 进度平滑动效的开关。开启平滑动效后设置进度,进度会从当前值渐变至设定值,否则进度从当前值突变至设定值。 默认值:true |
ScanEffectOptions10+
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
enableScanEffect | boolean | 否 | 扫光效果的开关。 默认值:false |
ProgressStyleOptions8+
继承自CommonProgressStyleOptions。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
strokeWidth | Length | 否 | 设置进度条宽度(不支持百分比设置)。 默认值:4.0vp |
scaleCount | number | 否 | 设置环形进度条总刻度数。 默认值:120 |
scaleWidth | Length | 否 | 设置环形进度条刻度粗细(不支持百分比设置),刻度粗细大于进度条宽度时,为系统默认粗细。 默认值:2.0vp |
CapsuleStyleOptions10+
继承自ScanEffectOptions,CommonProgressStyleOptions。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
borderColor | ResourceColor | 否 | 内描边颜色。 默认值: API version 10:'#33006cde' API version 11及以上:'#33007dff' |
borderWidth | Length | 否 | 内描边宽度(不支持百分比设置)。 默认值:1vp |
content | string | 否 | 文本内容,应用可自定义。 |
font | Font | 否 | 文本样式。 默认值: - 文本大小(不支持百分比设置):12fp 其他文本参数跟随text组件的主题值。 |
fontColor | ResourceColor | 否 | 文本颜色。 默认值:'#ff182431' |
showDefaultPercentage | boolean | 否 | 显示百分比文本的开关,开启后会在进度条上显示当前进度的百分比。设置了content属性时该属性不生效。 默认值:false |
RingStyleOptions10+
继承自ScanEffectOptions,CommonProgressStyleOptions。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
strokeWidth | Length | 否 | 设置进度条宽度(不支持百分比设置),宽度大于等于半径时,默认修改宽度至半径值的二分之一。 默认值:4.0vp |
shadow | boolean | 否 | 进度条阴影开关。 默认值:false |
status | ProgressStatus10+ | 否 | 进度条状态,当设置为LOADING时会开启检查更新动效,此时设置进度值不生效。当从LOADING设置为PROGRESSING,检查更新动效会执行到终点再停止。 默认值: ProgressStatus.PROGRESSING |
LinearStyleOptions10+
继承自ScanEffectOptions,CommonProgressStyleOptions。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
strokeWidth | Length | 否 | 设置进度条宽度(不支持百分比设置)。 默认值:4.0vp |
strokeRadius | PX | VP | LPX | Resource | 否 | 设置线性进度条圆角半径。 取值范围[0, strokeWidth / 2]。默认值:strokeWidth / 2。 |
ScaleRingStyleOptions10+
继承自CommonProgressStyleOptions。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
strokeWidth | Length | 否 | 设置进度条宽度(不支持百分比设置)。 默认值:4.0vp |
scaleCount | number | 否 | 设置环形进度条总刻度数。 默认值:120 |
scaleWidth | Length | 否 | 设置环形进度条刻度粗细(不支持百分比设置),刻度粗细大于进度条宽度时,为系统默认粗细。 默认值:2.0vp |
EclipseStyleOptions10+
继承自CommonProgressStyleOptions。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
ProgressStatus10+枚举说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 描述 |
---|---|
LOADING | 加载中。 |
PROGRESSING | 进度更新中。 |
事件
支持通用事件。
示例
示例1(设置进度条的类型)
该示例通过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 })
}
}
示例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 })
}
}
示例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 })
}
}
示例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 })
}
}
示例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 })
}
}
示例6(设置定制内容区)
该示例通过contentModifier接口,实现了自定义进度条的功能,自定义实现星形,其中总进度为3,且当前值可通过按钮进行增减,达到的进度被填充自定义颜色。
// xxx.ets
class MyProgressModifier implements ContentModifier<ProgressConfiguration> {
color: Color = Color.White
constructor(color: Color) {
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(Color.Red)
@State myModifier: (MyProgressModifier | undefined) = this.modifier
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('addProgress--').onClick(() => {
if (this.currentValue > 0) {
this.currentValue -= 1
}
}).width('30%')
}.width('100%').height('100%')
}
}
示例7(设置隐私隐藏)
该示例通过privacySensitive接口,实现了隐私隐藏效果,效果展示需要卡片框架支持。
@Entry
@Component
struct ProgressExample {
build() {
Scroll() {
Column({ space: 15 }) {
Row() {
Progress({ value: 50, 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: true
})
.privacySensitive(true)
}
}
}
}
}