• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Progress Indicator (Progress)
2
3
4The **\<Progress>** component is used to provide an indicator that shows the progress of an operation. For details, see [Progress](../reference/arkui-ts/ts-basic-components-progress.md).
5
6
7## Creating a Progress Indicator
8
9You can create a progress indicator by calling the following API:
10
11
12
13```ts
14Progress(options: {value: number, total?: number, type?: ProgressType})
15```
16
17
18In this API, **value** indicates the initial progress, **total** indicates the total progress, and **type** indicates the style of the progress indicator.
19
20
21
22```ts
23Progress({ value: 24, total: 100, type: ProgressType.Linear }) // Create a linear progress indicator whose total progress is 100 and initial progress is 24.
24```
25
26
27![create](figures/create.png)
28
29
30## Setting the Progress Indicator Style
31
32Progress indicators come in five styles. When creating a progress indicator, you can specify its style by setting the **ProgressType** parameter to any of the following: **ProgressType.Linear** (linear style), **ProgressType.Ring** (indeterminate ring style), **ProgressType.ScaleRing** (determinate ring style), **ProgressType.Eclipse** (eclipse style), and **ProgressType.Capsule** (capsule style).
33
34
35- Linear style (default style)
36
37  >**NOTE**
38  >
39  > Since API version 9, the progress indicator adaptively switches to the vertical layout if its height is greater than the width and remains the horizontal layout if the height is equal to the width.
40
41
42  ```ts
43  Progress({ value: 20, total: 100, type: ProgressType.Linear }).width(200).height(50)
44  Progress({ value: 20, total: 100, type: ProgressType.Linear }).width(50).height(200)
45  ```
46
47  ![en-us_image_0000001562700417](figures/en-us_image_0000001562700417.png)
48
49- Indeterminate ring style
50
51  ```ts
52  // The progress indicator in the indeterminate ring style on the left: Retain its default settings for the foreground color (blue gradient) and stroke width (2.0 vp).
53  Progress({ value: 40, total: 150, type: ProgressType.Ring }).width(100).height(100)
54  // The right progress indicator in the indeterminate ring style on the right.
55  Progress({ value: 40, total: 150, type: ProgressType.Ring }).width(100).height(100)
56      .color(Color.Grey)	// Set the foreground color to gray.
57      .style({ strokeWidth: 15})	// Set the stroke width to 15.0 vp.
58  ```
59
60  ![progress_ring](figures/progress_ring.png)
61
62- Determinate ring style
63
64  ```ts
65  Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).width(100).height(100)
66      .backgroundColor(Color.Black)
67      .style({ scaleCount: 20, scaleWidth: 5 })	// Set the total number of scales to 20 and the scale width to 5 vp.
68  Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).width(100).height(100)
69      .backgroundColor(Color.Black)
70      .style({ strokeWidth: 15, scaleCount: 20, scaleWidth: 5 })	// Set the stroke width to 15, the total number of scales to 20, and the scale width to 5 vp.
71  Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).width(100).height(100)
72      .backgroundColor(Color.Black)
73      .style({ strokeWidth: 15, scaleCount: 20, scaleWidth: 3 })	// Set the stroke width to 15, the total number of scales to 20, and the scale width to 3 vp.
74  ```
75
76  ![progress_scalering](figures/progress_scalering.png)
77
78- Eclipse style
79
80  ```ts
81  // The progress indicator in the eclipse style on the left: Retain its default settings for the foreground color (blue).
82  Progress({ value: 10, total: 150, type: ProgressType.Eclipse }).width(100).height(100)
83  // The progress indicator in the eclipse style on the right: Set its foreground color to gray.
84  Progress({ value: 20, total: 150, type: ProgressType.Eclipse }).color(Color.Grey).width(100).height(100)
85  ```
86
87  ![progress_circle](figures/progress_circle.png)
88
89- Capsule style
90  >**NOTE**
91  >
92  >-  At both ends, the progress indicator in the capsule style works in a same manner as that in the eclipse style.
93  >-  In the middle part of the capsule, the progress indicator works in a same manner as the linear style.
94  >
95  >-  If the height is greater than the width, the progress indicator adaptively switches to the vertical layout.
96
97
98  ```ts
99  Progress({ value: 10, total: 150, type: ProgressType.Capsule }).width(100).height(50)
100  Progress({ value: 20, total: 150, type: ProgressType.Capsule }).width(50).height(100).color(Color.Grey)
101  Progress({ value: 50, total: 150, type: ProgressType.Capsule }).width(50).height(100).color(Color.Blue).backgroundColor(Color.Black)
102  ```
103
104  ![progress_captule](figures/progress_captule.png)
105
106
107## Example Scenario
108
109In this example, the progress of the **\<Progress>** component is updated by clicking the button. After the button is clicked, the value of **progressValue** is incremented and passed to the **\<Progress>** component, which is then updated accordingly.
110
111```ts
112@Entry
113@Component
114struct ProgressCase1 {
115  @State progressValue: number = 0	// Set the initial progress of the progress indicator to 0.
116  build() {
117    Column() {
118      Column() {
119        Progress({value:0, total:100, type:ProgressType.Capsule}).width(200).height(50).value(this.progressValue)
120        Row().width('100%').height(5)
121        Button ("Progress + 5")
122          .onClick(()=>{
123            this.progressValue += 5
124            if (this.progressValue > 100){
125              this.progressValue = 0
126            }
127          })
128      }
129    }.width('100%').height('100%')
130  }
131}
132```
133
134
135![progress](figures/progress.gif)
136