文档管理中心
您当前浏览的HarmonyOS 5.0.0(API 12)文档归档不再维护,推荐您使用最新版本。详细请参考文档维护策略变更
API参考应用框架ArkUI(方舟UI框架)ArkTS组件信息展示Progress

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

属性

除支持通用属性外,还支持以下属性:

说明

该组件重写了通用属性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+ |

RingStyleOptions10+ | LinearStyleOptions10+ |

ScaleRingStyleOptions10+ | EclipseStyleOptions10+

组件的样式。

- 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+

继承自ScanEffectOptionsCommonProgressStyleOptions

元服务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+

继承自ScanEffectOptionsCommonProgressStyleOptions

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

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

展开
名称 类型 必填 说明
strokeWidth Length

设置进度条宽度(不支持百分比设置),宽度大于等于半径时,默认修改宽度至半径值的二分之一。

默认值:4.0vp

shadow boolean

进度条阴影开关。

默认值:false

status ProgressStatus10+

进度条状态,当设置为LOADING时会开启检查更新动效,此时设置进度值不生效。当从LOADING设置为PROGRESSING,检查更新动效会执行到终点再停止。

默认值: ProgressStatus.PROGRESSING

LinearStyleOptions10+

继承自ScanEffectOptionsCommonProgressStyleOptions

元服务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属性,实现了设置进度条类型的功能。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ProgressExample {
  5. build() {
  6. Column({ space: 15 }) {
  7. Text('Linear Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
  8. Progress({ value: 10, type: ProgressType.Linear }).width(200)
  9. Progress({ value: 20, total: 150, type: ProgressType.Linear }).color(Color.Grey).value(50).width(200)
  10. Text('Eclipse Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
  11. Row({ space: 40 }) {
  12. Progress({ value: 10, type: ProgressType.Eclipse }).width(100)
  13. Progress({ value: 20, total: 150, type: ProgressType.Eclipse }).color(Color.Grey).value(50).width(100)
  14. }
  15. Text('ScaleRing Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
  16. Row({ space: 40 }) {
  17. Progress({ value: 10, type: ProgressType.ScaleRing }).width(100)
  18. Progress({ value: 20, total: 150, type: ProgressType.ScaleRing })
  19. .color(Color.Grey).value(50).width(100)
  20. .style({ strokeWidth: 15, scaleCount: 15, scaleWidth: 5 })
  21. }
  22. // scaleCount和scaleWidth效果对比
  23. Row({ space: 40 }) {
  24. Progress({ value: 20, total: 150, type: ProgressType.ScaleRing })
  25. .color(Color.Grey).value(50).width(100)
  26. .style({ strokeWidth: 20, scaleCount: 20, scaleWidth: 5 })
  27. Progress({ value: 20, total: 150, type: ProgressType.ScaleRing })
  28. .color(Color.Grey).value(50).width(100)
  29. .style({ strokeWidth: 20, scaleCount: 30, scaleWidth: 3 })
  30. }
  31. Text('Ring Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
  32. Row({ space: 40 }) {
  33. Progress({ value: 10, type: ProgressType.Ring }).width(100)
  34. Progress({ value: 20, total: 150, type: ProgressType.Ring })
  35. .color(Color.Grey).value(50).width(100)
  36. .style({ strokeWidth: 20 })
  37. }
  38. Text('Capsule Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')
  39. Row({ space: 40 }) {
  40. Progress({ value: 10, type: ProgressType.Capsule }).width(100).height(50)
  41. Progress({ value: 20, total: 150, type: ProgressType.Capsule })
  42. .color(Color.Grey)
  43. .value(50)
  44. .width(100)
  45. .height(50)
  46. }
  47. }.width('100%').margin({ top: 30 })
  48. }
  49. }

示例2(设置环形进度条属性)

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

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ProgressExample {
  5. private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 },
  6. { color: Color.Orange, offset: 1.0 }])
  7. build() {
  8. Column({ space: 15 }) {
  9. Text('Gradient Color').fontSize(9).fontColor(0xCCCCCC).width('90%')
  10. Progress({ value: 70, total: 100, type: ProgressType.Ring })
  11. .width(100).style({ strokeWidth: 20 })
  12. .color(this.gradientColor)
  13. Text('Shadow').fontSize(9).fontColor(0xCCCCCC).width('90%')
  14. Progress({ value: 70, total: 100, type: ProgressType.Ring })
  15. .width(120).color(Color.Orange)
  16. .style({ strokeWidth: 20, shadow: true })
  17. }.width('100%').padding({ top: 5 })
  18. }
  19. }

示例3(设置环形进度条动画)

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

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ProgressExample {
  5. build() {
  6. Column({ space: 15 }) {
  7. Text('Loading Effect').fontSize(9).fontColor(0xCCCCCC).width('90%')
  8. Progress({ value: 0, total: 100, type: ProgressType.Ring })
  9. .width(100).color(Color.Blue)
  10. .style({ strokeWidth: 20, status: ProgressStatus.LOADING })
  11. Text('Scan Effect').fontSize(9).fontColor(0xCCCCCC).width('90%')
  12. Progress({ value: 30, total: 100, type: ProgressType.Ring })
  13. .width(100).color(Color.Orange)
  14. .style({ strokeWidth: 20, enableScanEffect: true })
  15. }.width('100%').padding({ top: 5 })
  16. }
  17. }

示例4(设置胶囊形进度条属性)

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

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ProgressExample {
  5. build() {
  6. Column({ space: 15 }) {
  7. Row({ space: 40 }) {
  8. Progress({ value: 100, total: 100, type: ProgressType.Capsule }).width(100).height(50)
  9. .style({
  10. borderColor: Color.Blue,
  11. borderWidth: 1,
  12. content: 'Installing...',
  13. font: { size: 13, style: FontStyle.Normal },
  14. fontColor: Color.Gray,
  15. enableScanEffect: false,
  16. showDefaultPercentage: false
  17. })
  18. }
  19. }.width('100%').padding({ top: 5 })
  20. }
  21. }

示例5(设置进度平滑动效)

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

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct Index {
  5. @State value: number = 0
  6. build() {
  7. Column({ space: 10 }) {
  8. Text('enableSmoothEffect: true')
  9. .fontSize(9)
  10. .fontColor(0xCCCCCC)
  11. .width('90%')
  12. .margin(5)
  13. .margin({ top: 20 })
  14. Progress({ value: this.value, total: 100, type: ProgressType.Linear })
  15. .style({ strokeWidth: 10, enableSmoothEffect: true })
  16. Text('enableSmoothEffect: false').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5)
  17. Progress({ value: this.value, total: 100, type: ProgressType.Linear })
  18. .style({ strokeWidth: 10, enableSmoothEffect: false })
  19. Button('value +10').onClick(() => {
  20. this.value += 10
  21. })
  22. .width(75)
  23. .height(15)
  24. .fontSize(9)
  25. }
  26. .width('50%')
  27. .height('100%')
  28. .margin({ left: 20 })
  29. }
  30. }

示例6(设置定制内容区)

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

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. class MyProgressModifier implements ContentModifier<ProgressConfiguration> {
  3. color: Color = Color.White
  4. constructor(color: Color) {
  5. this.color = color
  6. }
  7. applyContent(): WrappedBuilder<[ProgressConfiguration]> {
  8. return wrapBuilder(myProgress)
  9. }
  10. }
  11. @Builder
  12. function myProgress(config: ProgressConfiguration) {
  13. Column({ space: 30 }) {
  14. Text("当前进度:" + config.value + "/" + config.total).fontSize(20)
  15. Row() {
  16. Flex({ justifyContent: FlexAlign.SpaceBetween }) {
  17. Path()
  18. .width('30%')
  19. .height('30%')
  20. .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')
  21. .fill(config.enabled && config.value >= 1 ? (config.contentModifier as MyProgressModifier).color :
  22. Color.White)
  23. .stroke(Color.Black)
  24. .strokeWidth(3)
  25. Path()
  26. .width('30%')
  27. .height('30%')
  28. .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')
  29. .fill(config.enabled && config.value >= 2 ? (config.contentModifier as MyProgressModifier).color :
  30. Color.White)
  31. .stroke(Color.Black)
  32. .strokeWidth(3)
  33. Path()
  34. .width('30%')
  35. .height('30%')
  36. .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')
  37. .fill(config.enabled && config.value >= 3 ? (config.contentModifier as MyProgressModifier).color :
  38. Color.White)
  39. .stroke(Color.Black)
  40. .strokeWidth(3)
  41. }.width('100%')
  42. }
  43. }.margin({ bottom: 100 })
  44. }
  45. @Entry
  46. @Component
  47. struct Index {
  48. @State currentValue: number = 0
  49. modifier = new MyProgressModifier(Color.Red)
  50. @State myModifier: (MyProgressModifier | undefined) = this.modifier
  51. build() {
  52. Column() {
  53. Progress({ value: this.currentValue, total: 3, type: ProgressType.Ring }).contentModifier(this.modifier)
  54. Button('Progress++').onClick(() => {
  55. if (this.currentValue < 3) {
  56. this.currentValue += 1
  57. }
  58. }).width('30%')
  59. Button('addProgress--').onClick(() => {
  60. if (this.currentValue > 0) {
  61. this.currentValue -= 1
  62. }
  63. }).width('30%')
  64. }.width('100%').height('100%')
  65. }
  66. }

示例7(设置隐私隐藏)

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

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct ProgressExample {
  4. build() {
  5. Scroll() {
  6. Column({ space: 15 }) {
  7. Row() {
  8. Progress({ value: 50, total: 100, type: ProgressType.Capsule }).width(100).height(50)
  9. .style({
  10. borderColor: Color.Blue,
  11. borderWidth: 1,
  12. content: 'Installing...',
  13. font: { size: 13, style: FontStyle.Normal },
  14. fontColor: Color.Gray,
  15. enableScanEffect: false,
  16. showDefaultPercentage: true
  17. })
  18. .privacySensitive(true)
  19. }
  20. }
  21. }
  22. }
  23. }

在 API参考 中进行搜索
请输入您想要搜索的关键词