1# Progress 2 3进度条组件，用于显示内容加载或操作处理等进度。 4 5> **说明：** 6> 7> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12无 13 14 15## 接口 16 17Progress(options: ProgressOptions\<Type\>) 18 19创建进度组件，用于显示内容加载或操作处理进度。 20 21从API version 9开始，该接口支持在ArkTS卡片中使用。 22 23**参数:** 24 25| 参数名 | 参数类型 | 必填 | 参数描述 | 26| -------- | -------- | -------- | -------- | 27| options | ProgressOptions\<Type\> | 是 | 进度条组件参数。 | 28 29## ProgressOptions\<Type\>对象说明 30 31| 参数名 | 参数类型 | 必填 | 参数描述 | 32| -------------------------- | ----------------------------------- | ---- | ---------------------------------------- | 33| value | number | 是 | 指定当前进度值。设置小于0的数值时置为0，设置大于total的数值时置为total。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 34| total | number | 否 | 指定进度总长。<br/>默认值：100<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 35| type<sup>8+</sup> | [ProgressType](#progresstype8枚举说明) | 否 | 指定进度条类型。<br/>默认值：ProgressType.Linear<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 36| style<sup>(deprecated)</sup> | [ProgressStyle](#progressstyle枚举说明) | 否 | 指定进度条样式。<br/>该参数从API version8开始废弃，建议使用type替代。<br/>默认值：ProgressStyle.Linear | 37 38## ProgressType<sup>8+</sup>枚举说明 39 40从API version 9开始，该接口支持在ArkTS卡片中使用。 41 42| 名称 | 描述 | 43| ---------------------- | ---------------------------------------- | 44| Linear | 线性样式。从API version9开始，高度大于宽度的时候自适应垂直显示。 | 45| Ring | 环形无刻度样式，环形圆环逐渐显示至完全填充效果。 | 46| Eclipse | 圆形样式，显示类似月圆月缺的进度展示效果，从月牙逐渐变化至满月。 | 47| ScaleRing | 环形有刻度样式，显示类似时钟刻度形式的进度展示效果。从API version9开始，刻度外圈出现重叠的时候自动转换为环形无刻度进度条。 | 48| Capsule | 胶囊样式，头尾两端圆弧处的进度展示效果与Eclipse相同；中段处的进度展示效果与Linear相同。高度大于宽度的时候自适应垂直显示。 | 49 50## ProgressStyle枚举说明 51 52从API version 9开始，该接口支持在ArkTS卡片中使用。 53 54| 名称 | 描述 | 55| --------- | ---------------------------------------- | 56| Linear | 线性样式。 | 57| Ring<sup>8+</sup> | 环形无刻度样式，环形圆环逐渐显示至完全填充效果。 | 58| Eclipse | 圆形样式，显示类似月圆月缺的进度展示效果，从月牙逐渐变化至满月。 | 59| ScaleRing<sup>8+</sup> | 环形有刻度样式，显示类似时钟刻度形式的进度展示效果。 | 60| Capsule<sup>8+</sup> | 胶囊样式，头尾两端圆弧处的进度展示效果与Eclipse相同；中段处的进度展示效果与Linear相同。高度大于宽度的时候自适应垂直显示。 | 61 62## 属性 63 64除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 65 66| 名称 | 参数类型 | 描述 | 67| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 68| value | number | 设置当前进度值。设置小于0的数值时置为0，设置大于total的数值时置为total。非法数值不生效。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 69| color | [ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient<sup>10+</sup>](ts-basic-components-datapanel.md#lineargradient10对象说明) | 设置进度条前景色。<br/>从API version 10开始支持利用LinearGradient设置Ring样式的渐变色。<br/>默认值：<br/>- Capsule：<br/> API version 9及以下：'\#ff007dff'<br/> API version 10：'\#33006cde'<br/> API version 11及以上：'\#33007dff'<br/>- Ring：<br/> API version 9及以下：'\#ff007dff'<br/> API version 10及以上：起始端：'\#ff86c1ff'，结束端：'\#ff254ff7'<br/>- 其他样式：'\#ff007dff'<br/>从API version 9开始，该接口支持在ArkTS卡片中使用，暂不支持LinearGradient。 | 70| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 设置进度条底色。<br/>默认值：<br/>- Capsule：<br/> API version 9及以下：'\#19182431'<br/> API version 10及以上：'\#33ffffff'<br/>- Ring：<br/> API version 9及以下：'\#19182431'<br/> API version 10：'\#08182431'<br/> API version 11及以上：'\#0c182431'<br/>- 其他样式：'\#19182431'<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：** <br/>当设置[通用属性backgroundColor](./ts-universal-attributes-background.md)时，生效的是进度条的底色，而不是整个Progress组件的背景色。 | 71| style<sup>8+</sup> | [ProgressStyleOptions<sup>8+</sup>](#progressstyleoptions8) \| [CapsuleStyleOptions<sup>10+</sup>](#capsulestyleoptions10) \| [RingStyleOptions<sup>10+</sup>](#ringstyleoptions10) \| [LinearStyleOptions<sup>10+</sup>](#linearstyleoptions10) \| [ScaleRingStyleOptions<sup>10+</sup>](#scaleringstyleoptions10) \| [EclipseStyleOptions<sup>10+</sup>](#eclipsestyleoptions10) | 定义组件的样式。<br/>从API version 10开始支持以下类型：<br/>- CapsuleStyleOptions：设置Capsule的样式。<br/>- RingStyleOptions：设置Ring的样式。<br/>- LinearStyleOptions：设置Linear的样式。<br/>- ScaleRingStyleOptions：设置ScaleRing的样式。<br/>- EclipseStyleOptions：设置Eclipse的样式。<br/>- ProgressStyleOptions：仅可设置各类型进度条的基本样式。<br/>从API version 9开始，该接口支持在ArkTS卡片中设置ProgressStyleOptions，暂不支持其它的参数类型。 | 72 73## ProgressStyleOptions<sup>8+</sup> 74| 名称 | 参数类型 | 必填 | 描述 | 75| ------------ | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 76| strokeWidth | [Length](ts-types.md#length) | 否 | 设置进度条宽度（不支持百分比设置）。<br/>默认值：4.0vp | 77| scaleCount | number | 否 | 设置环形进度条总刻度数。<br/>默认值：120 | 78| scaleWidth | [Length](ts-types.md#length) | 否 | 设置环形进度条刻度粗细（不支持百分比设置），刻度粗细大于进度条宽度时，为系统默认粗细。<br/>默认值：2.0vp | 79| enableSmoothEffect<sup>10+</sup> | boolean | 否 | 进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。<br/>默认值：true | 80 81## CapsuleStyleOptions<sup>10+</sup> 82| 名称 | 参数类型 | 必填 | 描述 | 83| ------------- | ------- | ---- | -------- | 84| borderColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 内描边颜色。<br/>默认值：<br/>API version 10：'\#33006cde'<br/>API version 11及以上：'\#33007dff' | 85| borderWidth | [Length](ts-types.md#length) | 否 | 内描边宽度（不支持百分比设置）。<br/>默认值：1vp | 86| content | string | 否 | 文本内容，应用可自定义。 | 87| font | [Font](ts-types.md#font) | 否 | 文本样式。<br/>默认值：<br/>- 文本大小（不支持百分比设置）：12fp <br/>其他文本参数跟随text组件的主题值。| 88| fontColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 文本颜色。<br/>默认值：'\#ff182431' | 89| enableScanEffect | boolean | 否 | 扫光效果的开关。<br/>默认值：false | 90| showDefaultPercentage | boolean | 否 | 显示百分比文本的开关，开启后会在进度条上显示当前进度的百分比。设置了content属性时该属性不生效。<br/>默认值：false | 91| enableSmoothEffect | boolean | 否 | 进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。<br/>默认值：true | 92 93## RingStyleOptions<sup>10+</sup> 94| 名称 | 参数类型 | 必填 | 描述 | 95| ------------- | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 96| strokeWidth | [Length](ts-types.md#length) | 否 | 设置进度条宽度（不支持百分比设置），宽度大于等于半径时，默认修改宽度至半径值的二分之一。<br/>默认值：4.0vp | 97| shadow | boolean | 否 | 进度条阴影开关。<br/>默认值：false | 98| status | [ProgressStatus<sup>10+</sup>](#progressstatus10枚举说明) | 否 | 进度条状态，当设置为LOADING时会开启检查更新动效，此时设置进度值不生效。当从LOADING设置为PROGRESSING，检查更新动效会执行到终点再停止。<br/>默认值： ProgressStatus.PROGRESSING | 99| enableScanEffect | boolean | 否 | 进度条扫光效果的开关。<br/>默认值： false | 100| enableSmoothEffect | boolean | 否 | 进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。<br/>默认值：true | 101 102## LinearStyleOptions<sup>10+</sup> 103| 名称 | 参数类型 | 必填 | 描述 | 104| ------------- | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 105| strokeWidth | [Length](ts-types.md#length) | 否 | 设置进度条宽度（不支持百分比设置）。<br/>默认值：4.0vp | 106| strokeRadius | [PX](ts-types.md#px10) \| [VP](ts-types.md#vp10) \| [LPX](ts-types.md#lpx10) \| [Resource](ts-types.md#resource)| 否 | 设置线性进度条圆角半径。<br/>取值范围[0, strokeWidth / 2]。默认值：strokeWidth / 2。 | 107| enableScanEffect | boolean | 否 | 进度条扫光效果的开关。<br/>默认值： false | 108| enableSmoothEffect | boolean | 否 | 进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。<br/>默认值：true | 109 110## ScaleRingStyleOptions<sup>10+</sup> 111| 名称 | 参数类型 | 必填 | 描述 | 112| ------------ | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 113| strokeWidth | [Length](ts-types.md#length) | 否 | 设置进度条宽度（不支持百分比设置）。<br/>默认值：4.0vp | 114| scaleCount | number | 否 | 设置环形进度条总刻度数。<br/>默认值：120 | 115| scaleWidth | [Length](ts-types.md#length) | 否 | 设置环形进度条刻度粗细（不支持百分比设置），刻度粗细大于进度条宽度时，为系统默认粗细。<br/>默认值：2.0vp | 116| enableSmoothEffect | boolean | 否 | 进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。<br/>默认值：true | 117 118## EclipseStyleOptions<sup>10+</sup> 119| 名称 | 参数类型 | 必填 | 描述 | 120| ------------ | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 121| enableSmoothEffect | boolean | 否 | 进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。<br/>默认值：true | 122 123## ProgressStatus<sup>10+</sup>枚举说明 124| 名称 | 描述 | 125| ----------------------- | ---------------- | 126| LOADING | 加载中。 | 127| PROGRESSING | 进度更新中。 | 128 129## 事件 130 131支持[通用事件](ts-universal-events-click.md)。 132 133## 示例 134 135### 示例1 136 137各进度条基础属性效果。 138 139```ts 140// xxx.ets 141@Entry 142@Component 143struct ProgressExample { 144 build() { 145 Column({ space: 15 }) { 146 Text('Linear Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 147 Progress({ value: 10, type: ProgressType.Linear }).width(200) 148 Progress({ value: 20, total: 150, type: ProgressType.Linear }).color(Color.Grey).value(50).width(200) 149 150 151 Text('Eclipse Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 152 Row({ space: 40 }) { 153 Progress({ value: 10, type: ProgressType.Eclipse }).width(100) 154 Progress({ value: 20, total: 150, type: ProgressType.Eclipse }).color(Color.Grey).value(50).width(100) 155 } 156 157 Text('ScaleRing Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 158 Row({ space: 40 }) { 159 Progress({ value: 10, type: ProgressType.ScaleRing }).width(100) 160 Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }) 161 .color(Color.Grey).value(50).width(100) 162 .style({ strokeWidth: 15, scaleCount: 15, scaleWidth: 5 }) 163 } 164 165 // scaleCount和scaleWidth效果对比 166 Row({ space: 40 }) { 167 Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }) 168 .color(Color.Grey).value(50).width(100) 169 .style({ strokeWidth: 20, scaleCount: 20, scaleWidth: 5 }) 170 Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }) 171 .color(Color.Grey).value(50).width(100) 172 .style({ strokeWidth: 20, scaleCount: 30, scaleWidth: 3 }) 173 } 174 175 Text('Ring Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 176 Row({ space: 40 }) { 177 Progress({ value: 10, type: ProgressType.Ring }).width(100) 178 Progress({ value: 20, total: 150, type: ProgressType.Ring }) 179 .color(Color.Grey).value(50).width(100) 180 .style({ strokeWidth: 20 }) 181 } 182 183 Text('Capsule Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 184 Row({ space: 40 }) { 185 Progress({ value: 10, type: ProgressType.Capsule }).width(100).height(50) 186 Progress({ value: 20, total: 150, type: ProgressType.Capsule }) 187 .color(Color.Grey) 188 .value(50) 189 .width(100) 190 .height(50) 191 } 192 }.width('100%').margin({ top: 30 }) 193 } 194} 195``` 196 197 198 199### 示例2 200 201环形进度条视觉属性。 202 203```ts 204// xxx.ets 205@Entry 206@Component 207struct ProgressExample { 208 private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 }, 209 { color: Color.Orange, offset: 1.0 }]) 210 build() { 211 Column({ space: 15 }) { 212 Text('Gradient Color').fontSize(9).fontColor(0xCCCCCC).width('90%') 213 Progress({ value: 70, total: 100, type: ProgressType.Ring }) 214 .width(100).style({ strokeWidth: 20 }) 215 .color(this.gradientColor) 216 217 Text('Shadow').fontSize(9).fontColor(0xCCCCCC).width('90%') 218 Progress({ value: 70, total: 100, type: ProgressType.Ring }) 219 .width(120).color(Color.Orange) 220 .style({ strokeWidth: 20, shadow: true }) 221 }.width('100%').padding({ top: 5 }) 222 } 223} 224``` 225 226 227### 示例3 228 229环形进度条动效。 230 231```ts 232// xxx.ets 233@Entry 234@Component 235struct ProgressExample { 236 private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 }, 237 { color: Color.Orange, offset: 1.0 }]) 238 build() { 239 Column({ space: 15 }) { 240 Text('Loading Effect').fontSize(9).fontColor(0xCCCCCC).width('90%') 241 Progress({ value: 0, total: 100, type: ProgressType.Ring }) 242 .width(100).color(Color.Blue) 243 .style({ strokeWidth: 20, status: ProgressStatus.LOADING }) 244 245 Text('Scan Effect').fontSize(9).fontColor(0xCCCCCC).width('90%') 246 Progress({ value: 30, total: 100, type: ProgressType.Ring }) 247 .width(100).color(Color.Orange) 248 .style({ strokeWidth: 20, enableScanEffect: true }) 249 }.width('100%').padding({ top: 5 }) 250 } 251} 252``` 253 254 255### 示例4 256 257胶囊形进度条视觉属性。 258 259```ts 260// xxx.ets 261@Entry 262@Component 263struct ProgressExample { 264 265 build() { 266 Column({ space: 15 }) { 267 Row({ space: 40 }) { 268 Progress({ value: 100, total: 100,type: ProgressType.Capsule }).width(100).height(50) 269 .style({borderColor: Color.Blue, borderWidth: 1, content: 'Installing...', 270 font: {size: 13, style: FontStyle.Normal}, fontColor: Color.Gray, 271 enableScanEffect: false, showDefaultPercentage: false}) 272 } 273 }.width('100%').padding({ top: 5 }) 274 } 275} 276``` 277 278 279### 示例5 280 281进度平滑动效。 282 283```ts 284// xxx.ets 285@Entry 286@Component 287struct Index { 288 @State value: number = 0 289 290 build() { 291 Column({space: 10}) { 292 Text('enableSmoothEffect: true').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5) 293 .margin({top: 20}) 294 Progress({value: this.value, total: 100, type:ProgressType.Linear}) 295 .style({strokeWidth: 10, enableSmoothEffect: true}) 296 297 Text('enableSmoothEffect: false').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5) 298 Progress({value: this.value, total: 100, type:ProgressType.Linear}) 299 .style({strokeWidth: 10, enableSmoothEffect: false}) 300 301 Button('value +10').onClick(() => { 302 this.value += 10 303 }) 304 .width(75) 305 .height(15) 306 .fontSize(9) 307 } 308 .width('50%') 309 .height('100%') 310 .margin({left:20}) 311 } 312} 313 314``` 315 316
