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