1# Progress 2 3The **\<Progress>** component represents a progress indicator that displays the progress of content loading or an operation. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12Not supported 13 14 15## APIs 16 17Progress(options: {value: number, total?: number, type?: ProgressType}) 18 19Creates a progress indicator. 20 21Since API version 9, this API is supported in ArkTS widgets. 22 23**Parameters** 24 25| Name | Type | Mandatory | Description | 26| -------------------------- | ----------------------------------- | ---- | ---------------------------------------- | 27| value | number | Yes | Current progress. If the value is less than 0, the value **0** is used. If the value is greater than that of **total**, the value of **total** is used.<br>Since API version 9, this API is supported in ArkTS widgets.| 28| total | number | No | Total progress.<br>Default value: **100**<br>Since API version 9, this API is supported in ArkTS widgets.| 29| type<sup>8+</sup> | [ProgressType](#progresstype) | No | Style of the progress indicator.<br>Default value: **ProgressType.Linear**<br>Since API version 9, this API is supported in ArkTS widgets.| 30| style<sup>(deprecated)</sup> | [ProgressStyle](#progressstyle) | No | Style of the progress indicator.<br>This parameter is deprecated since API version 8. You are advised to use **type** instead.<br>Default value: **ProgressStyle.Linear**| 31 32## ProgressType 33 34Since API version 9, this API is supported in ArkTS widgets. 35 36| Name | Description | 37| ---------------------- | ---------------------------------------- | 38| Linear | Linear style. Since API version 9, the progress indicator adaptively switches to vertical layout if the height is greater than the width. | 39| Ring<sup>8+</sup> | Indeterminate ring style. The ring fills up as the progress increases. | 40| Eclipse<sup>8+</sup> | Eclipse style, which visualizes the progress in a way similar to the moon waxing from new to full. | 41| ScaleRing<sup>8+</sup> | Determinate ring style, which is similar to the clock scale. Since API version 9, when the outer circles of scales overlap, the progress indicator is automatically converted to the **Ring** style.| 42| Capsule<sup>8+</sup> | Capsule style. At both ends, the progress indicator works in a same manner as the eclipse style. In the middle part of the capsule, the progress indicator works in a same manner as the linear style. If the height is greater than the width, the progress indicator adaptively switches to vertical layout.| 43 44## ProgressStyle 45 46Since API version 9, this API is supported in ArkTS widgets. 47 48| Name | Description | 49| --------- | ---------------------------------------- | 50| Linear | Linear style. | 51| Ring | Indeterminate ring style. The ring fills up as the progress increases. | 52| Eclipse | Eclipse style, which visualizes the progress in a way similar to the moon waxing from new to full. | 53| ScaleRing | Determinate ring style, which is similar to the clock scale. | 54| Capsule | Capsule style. At both ends, the progress indicator works in a same manner as the eclipse style. In the middle part of the capsule, the progress indicator works in a same manner as the linear style. If the height is greater than the width, the progress indicator adaptively switches to vertical layout.| 55 56## Attributes 57 58In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 59 60| Name | Type | Description | 61| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 62| value | number | Current progress. If the value is less than 0, the value **0** is used. If the value is greater than that of **total**, the value of **total** is used. Invalid values do not take effect.<br>Since API version 9, this API is supported in ArkTS widgets.| 63| color | [ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient<sup>10+</sup>](ts-basic-components-datapanel.md#lineargradient10) | Background color of the progress indicator.<br>Since API version 10, this attribute can be set to **LinearGradient** for the **Ring** style.<br>Default value (API version 9): **'\#ff007dff'**<br>Default value (API version 10):<br>- Capsule: **'\#33006cde'**<br>- Ring: starting point: **'\#ff3b61f7'**, ending point: **'\#ff6591bf'**<br>- Other styles: **'\#ff007dff'**<br>Since API version 9, this API is supported in ArkTS widgets, except that **LinearGradient** is not supported.| 64| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | Background color of the progress indicator.<br>Default value (API version 9): **'\#19182431'**<br>Default value (API version 10):<br>- Capsule: **'\#33ffffff'**<br>- Ring: **'\#08182431'**<br>- Other styles: **'\#19182431'**<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>The settings of the universal attribute [backgroundColor](./ts-universal-attributes-background.md) applies to the progress indicator instead of the entire **\<Progress>** component.| 65| style<sup>8+</sup> | [ProgressStyleOptions](#progressstyleoptions) \| [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) | Component style.<br>Since API version 10, the following types are supported:<br>- **CapsuleStyleOptions**: capsule style.<br>- **RingStyleOptions**: ring style.<br>- **LinearStyleOptions**: linear style.<br>- **ScaleRingStyleOptions**: determinate ring style.<br>- **EclipseStyleOptions**: eclipse style.<br>- **ProgressStyleOptions**: basic style.<br>Since API version 9, this API is supported in ArkTS widgets, but only the **ProgressStyleOptions** type is available.| 66 67## ProgressStyleOptions 68| Name | Type | Mandatory| Description | 69| ------------ | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 70| strokeWidth | [Length](ts-types.md#length) | No | Stroke width of the progress indicator. It cannot be set in percentage.<br>Default value: **4.0vp** | 71| scaleCount | number | No | Number of divisions on the ring-style process indicator.<br>Default value: **120** | 72| scaleWidth | [Length](ts-types.md#length) | No | Scale width of the ring-style progress bar. It cannot be set in percentage. If it is greater than the value of **strokeWidth**, the default scale width is used.<br>Default value: **2.0vp**| 73| enableSmoothEffect<sup>10+</sup> | boolean | No| Whether to enable the smooth effect. When this effect is enabled, the progress change to the set value takes place gradually. Otherwise, it takes place immediately.<br>Default value: **true**| 74 75## CapsuleStyleOptions<sup>10+</sup> 76| Name | Type| Mandatory| Description| 77| ------------- | ------- | ---- | -------- | 78| borderColor | [ResourceColor](ts-types.md#resourcecolor) | No| Border color.<br>Default value: **'\#33006cde'**| 79| borderWidth | [Length](ts-types.md#length) | No| Border width. It cannot be set in percentage.<br>Default value: **1vp**| 80| content | string | No| Text content, which can be customized .| 81| font | [Font](ts-types.md#font) | No| Text style.<br>Default value:<br>- Font size (cannot be set in percentage): **12fp**<br>- Other attributes: following the settings of the **\<Text>** component.| 82| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No| Font color.<br>Default value: **'\#ff182431'**| 83| enableScanEffect | boolean | No| Whether to enable the scan effect.<br>Default value: **false**| 84| showDefaultPercentage | boolean | No| Whether to show the percentage of the current progress. This attribute does not take effect when the **content** attribute is set.<br>Default value: **false**| 85| enableSmoothEffect | boolean | No| Whether to enable the smooth effect. When this effect is enabled, the progress change to the set value takes place gradually. Otherwise, it takes place immediately.<br>Default value: **true**| 86 87## RingStyleOptions<sup>10+</sup> 88| Name | Type | Mandatory| Description | 89| ------------- | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 90| strokeWidth | [Length](ts-types.md#length) | No | Stroke width of the progress indicator. It cannot be set in percentage. A value greater than or equal to the radius evaluates to half of the radius.<br>Default value: **4.0vp**| 91| shadow | boolean | No | Whether to enable the shadow effect.<br>Default value: **false** | 92| status | [ProgressStatus<sup>10+</sup>](#progressstatus10) | No| Status of the progress indicator. When this parameter is set to **LOADING**, the check update animation is played, and the **value** settings do not take effect. When the value changes from **LOADING** to **PROGRESSING**, the check update animation stops when it has reached the end state.<br>Default value: **ProgressStatus.PROGRESSING**| 93| enableScanEffect | boolean | No| Whether to enable the scan effect.<br>Default value: **false**| 94| enableSmoothEffect | boolean | No| Whether to enable the smooth effect. When this effect is enabled, the progress change to the set value takes place gradually. Otherwise, it takes place immediately.<br>Default value: **true**| 95 96## LinearStyleOptions<sup>10+</sup> 97| Name | Type | Mandatory| Description | 98| ------------- | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 99| strokeWidth | [Length](ts-types.md#length) | No | Stroke width of the progress indicator. It cannot be set in percentage.<br>Default value: **4.0vp**| 100| strokeRadius | [PX](ts-types.md#px10) \| [VP](ts-types.md#vp10) \| [LPX](ts-types.md#lpx10) \| [Resource](ts-types.md#resource)| No | Rounded corner radius of the progress indicator.<br>Value range: [0, strokeWidth/2] Default value: **strokeWidth/2**| 101| enableScanEffect | boolean | No| Whether to enable the scan effect.<br>Default value: **false**| 102| enableSmoothEffect | boolean | No| Whether to enable the smooth effect. When this effect is enabled, the progress change to the set value takes place gradually. Otherwise, it takes place immediately.<br>Default value: **true**| 103 104## ScaleRingStyleOptions<sup>10+</sup> 105| Name | Type | Mandatory| Description | 106| ------------ | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 107| strokeWidth | [Length](ts-types.md#length) | No | Stroke width of the progress indicator. It cannot be set in percentage.<br>Default value: **4.0vp** | 108| scaleCount | number | No | Number of divisions on the ring-style process indicator.<br>Default value: **120** | 109| scaleWidth | [Length](ts-types.md#length) | No | Scale width of the ring-style progress bar. It cannot be set in percentage. If it is greater than the value of **strokeWidth**, the default scale width is used.<br>Default value: **2.0vp**| 110| enableSmoothEffect | boolean | No| Whether to enable the smooth effect. When this effect is enabled, the progress change to the set value takes place gradually. Otherwise, it takes place immediately.<br>Default value: **true**| 111 112## EclipseStyleOptions<sup>10+</sup> 113| Name | Type | Mandatory| Description | 114| ------------ | ---------------------------- | ---- | ------------------------------------------------------------------------------------------ | 115| enableSmoothEffect | boolean | No| Whether to enable the smooth effect. When this effect is enabled, the progress change to the set value takes place gradually. Otherwise, it takes place immediately.<br>Default value: **true**| 116 117## ProgressStatus<sup>10+</sup> 118| Name | Description | 119| ----------------------- | ---------------- | 120| LOADING | Loading.| 121| PROGRESSING | The progress is being updated.| 122 123## Events 124 125The [universal events](ts-universal-events-click.md) are supported. 126 127## Example 128### Example 1 129This example shows the effect of the basic attributes for different types of progress indicators. 130```ts 131// xxx.ets 132@Entry 133@Component 134struct ProgressExample { 135 build() { 136 Column({ space: 15 }) { 137 Text('Linear Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 138 Progress({ value: 10, type: ProgressType.Linear }).width(200) 139 Progress({ value: 20, total: 150, type: ProgressType.Linear }).color(Color.Grey).value(50).width(200) 140 141 142 Text('Eclipse Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 143 Row({ space: 40 }) { 144 Progress({ value: 10, type: ProgressType.Eclipse }).width(100) 145 Progress({ value: 20, total: 150, type: ProgressType.Eclipse }).color(Color.Grey).value(50).width(100) 146 } 147 148 Text('ScaleRing Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 149 Row({ space: 40 }) { 150 Progress({ value: 10, type: ProgressType.ScaleRing }).width(100) 151 Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }) 152 .color(Color.Grey).value(50).width(100) 153 .style({ strokeWidth: 15, scaleCount: 15, scaleWidth: 5 }) 154 } 155 156 // scaleCount vs. scaleWidth 157 Row({ space: 40 }) { 158 Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }) 159 .color(Color.Grey).value(50).width(100) 160 .style({ strokeWidth: 20, scaleCount: 20, scaleWidth: 5 }) 161 Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }) 162 .color(Color.Grey).value(50).width(100) 163 .style({ strokeWidth: 20, scaleCount: 30, scaleWidth: 3 }) 164 } 165 166 Text('Ring Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 167 Row({ space: 40 }) { 168 Progress({ value: 10, type: ProgressType.Ring }).width(100) 169 Progress({ value: 20, total: 150, type: ProgressType.Ring }) 170 .color(Color.Grey).value(50).width(100) 171 .style({ strokeWidth: 20 }) 172 } 173 174 Text('Capsule Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') 175 Row({ space: 40 }) { 176 Progress({ value: 10, type: ProgressType.Capsule }).width(100).height(50) 177 Progress({ value: 20, total: 150, type: ProgressType.Capsule }) 178 .color(Color.Grey) 179 .value(50) 180 .width(100) 181 .height(50) 182 } 183 }.width('100%').margin({ top: 30 }) 184 } 185} 186``` 187 188 189 190### Example 2 191This example shows the effect of visual attributes of the ring style progress indicator. 192```ts 193@Entry 194@Component 195struct ProgressExample { 196 private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 }, 197 { color: Color.Orange, offset: 1.0 }]) 198 build() { 199 Column({ space: 15 }) { 200 Text('Gradient Color').fontSize(9).fontColor(0xCCCCCC).width('90%') 201 Progress({ value: 70, total: 100, type: ProgressType.Ring }) 202 .width(100).style({ strokeWidth: 20 }) 203 .color(this.gradientColor) 204 205 Text('Shadow').fontSize(9).fontColor(0xCCCCCC).width('90%') 206 Progress({ value: 70, total: 100, type: ProgressType.Ring }) 207 .width(120).color(Color.Orange) 208 .style({ strokeWidth: 20, shadow: true }) 209 }.width('100%').padding({ top: 5 }) 210 } 211} 212``` 213 214 215### Example 3 216This example shows the animation effect of the ring style progress indicator. 217```ts 218@Entry 219@Component 220struct ProgressExample { 221 private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 }, 222 { color: Color.Orange, offset: 1.0 }]) 223 build() { 224 Column({ space: 15 }) { 225 Text('Loading Effect').fontSize(9).fontColor(0xCCCCCC).width('90%') 226 Progress({ value: 0, total: 100, type: ProgressType.Ring }) 227 .width(100).color(Color.Blue) 228 .style({ strokeWidth: 20, status: ProgressStatus.LOADING }) 229 230 Text('Scan Effect').fontSize(9).fontColor(0xCCCCCC).width('90%') 231 Progress({ value: 30, total: 100, type: ProgressType.Ring }) 232 .width(100).color(Color.Orange) 233 .style({ strokeWidth: 20, enableScanEffect: true }) 234 }.width('100%').padding({ top: 5 }) 235 } 236} 237``` 238 239 240### Example 4 241This example shows the effect of visual attributes of the capsule style progress indicator. 242```ts 243@Entry 244@Component 245struct ProgressExample { 246 247 build() { 248 Column({ space: 15 }) { 249 Row({ space: 40 }) { 250 Progress({ value: 100, total: 100,type: ProgressType.Capsule }).width(100).height(50) 251 .style({borderColor: Color.Blue, borderWidth: 1, content: 'Installing...', 252 font: {size: 13, style: FontStyle.Normal}, fontColor: Color.Gray, 253 enableScanEffect: false, showDefaultPercentage: false}) 254 } 255 }.width('100%').padding({ top: 5 }) 256 } 257} 258``` 259 260 261### Example 5 262This example shows the smooth effect. 263```ts 264@Entry 265@Component 266struct Index { 267 @State value: number = 0 268 269 build() { 270 Column({space: 10}) { 271 Text('enableSmoothEffect: true').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5) 272 .margin({top: 20}) 273 Progress({value: this.value, total: 100, type:ProgressType.Linear}) 274 .style({strokeWidth: 10, enableSmoothEffect: true}) 275 276 Text('enableSmoothEffect: false').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5) 277 Progress({value: this.value, total: 100, type:ProgressType.Linear}) 278 .style({strokeWidth: 10, enableSmoothEffect: false}) 279 280 Button('value +10').onClick(() => { 281 this.value += 10 282 }) 283 .width(75) 284 .height(15) 285 .fontSize(9) 286 } 287 .width('50%') 288 .height('100%') 289 .margin({left:20}) 290 } 291} 292 293``` 294 295
