1# LoadingProgress
2
3用于显示加载动效的组件。
4
5加载动效在组件不可见时停止，组件的可见状态基于[onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange)处理，可见阈值ratios大于0即视为可见状态。
6
7>  **说明：**
8>
9> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
10
11
12## 子组件
13
14无
15
16
17## 接口
18
19LoadingProgress()
20
21创建加载进展组件。
22
23**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
24
25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
26
27**系统能力：** SystemCapability.ArkUI.ArkUI.Full
28
29## 属性
30
31除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
32
33### color
34
35color(value: ResourceColor)
36
37设置加载进度条前景色。
38
39**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
40
41**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
42
43**系统能力：** SystemCapability.ArkUI.ArkUI.Full
44
45**参数：**
46
47| 参数名 | 类型                                       | 必填 | 说明                                                         |
48| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ |
49| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 加载进度条的前景色。<br/>默认值：<br/>API version 10及以下：'#99666666'<br/>API version 11及以上：'#ff666666' |
50
51### enableLoading<sup>10+</sup>
52
53enableLoading(value: boolean)
54
55设置LoadingProgress动画显示或者不显示。LoadingProgress动画不显示时，该组件依旧占位。通用属性[Visibility.Hidden](ts-universal-attributes-visibility.md#visibility)隐藏的是包括[border](ts-universal-attributes-border.md#border)、[padding](ts-universal-attributes-size.md#padding)等整个组件范围，而enableLoading=false只隐藏LoadingProgress本身动画内容，不包括border等。
56
57
58**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
59
60**系统能力：** SystemCapability.ArkUI.ArkUI.Full
61
62**参数：**
63
64| 参数名 | 类型    | 必填 | 说明                                           |
65| ------ | ------- | ---- | ---------------------------------------------- |
66| value  | boolean | 是   | LoadingProgress动画是否显示。<br/>默认值：true |
67
68### contentModifier<sup>12+</sup>
69
70contentModifier(modifier: ContentModifier\<LoadingProgressConfiguration>)
71
72定制LoadingProgress内容区的方法。
73
74**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
75
76**系统能力：** SystemCapability.ArkUI.ArkUI.Full
77
78**参数：**
79
80| 参数名 | 类型                                          | 必填 | 说明                                             |
81| ------ | --------------------------------------------- | ---- | ------------------------------------------------ |
82| modifier  | [ContentModifier\<LoadingProgressConfiguration>](#loadingprogressconfiguration12对象说明) | 是   | 在LoadingProgress组件上，定制内容区的方法。<br/>modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 |
83
84## 事件
85
86支持[通用事件](ts-universal-events-click.md)。
87
88## LoadingProgressConfiguration<sup>12+</sup>对象说明
89
90开发者需要自定义class实现ContentModifier接口。
91
92**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
93
94**系统能力：** SystemCapability.ArkUI.ArkUI.Full
95
96| 名称  | 类型    |    只读    |    可选    |  说明              |
97| ------ | ------ | ------ |-------------------------------- |-------------------------------- |
98| enableLoading | boolean | 否 | 否 |LoadingProgress动画是否显示。<br/>默认值：true |
99
100## LoadingProgressStyle<sup>(deprecated)</sup>枚举说明
101
102从API version 8开始废弃。
103
104**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
105
106**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
107
108**系统能力：** SystemCapability.ArkUI.ArkUI.Full
109
110| 名称                     | 说明                                     |
111| ---------------------- | ---------------------------------------- |
112| Default       | 默认加载样式。API version 8及以后不支持设置。            |
113| Circular      | 环形加载样式。API version 8及以后不支持设置。            |
114| Orbital       | 彗星形加载样式。API version 8及以后默认为彗星形样式。         |
115
116## 示例
117
118### 示例1（设置颜色）
119
120该示例通过color接口，实现了设置加载动效颜色的功能。
121
122```ts
123// xxx.ets
124@Entry
125@Component
126struct LoadingProgressExample {
127  build() {
128    Column({ space: 5 }) {
129      Text('Orbital LoadingProgress ').fontSize(9).fontColor(0xCCCCCC).width('90%')
130      LoadingProgress()
131        .color(Color.Blue)
132        .layoutWeight(1)
133    }.width('100%').margin({ top: 5 })
134  }
135}
136```
137
138![LoadingProgress](figures/LoadingProgress.gif)
139
140### 示例2（设置定制内容区）
141
142该示例通过contentModifier接口，实现了定制内容区的功能，并通过enableLoading接口实现了通过按钮切换是否显示LoadingProgress的效果。
143
144```ts
145// xxx.ets
146import { promptAction } from '@kit.ArkUI'
147
148class MyLoadingProgressStyle implements ContentModifier<LoadingProgressConfiguration> {
149  enableLoading: boolean = false
150
151  constructor(enableLoading: boolean) {
152    this.enableLoading = enableLoading
153  }
154
155  applyContent(): WrappedBuilder<[LoadingProgressConfiguration]> {
156    return wrapBuilder(buildLoadingProgress)
157  }
158}
159
160let arr1: string[] =
161  ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"]
162let arr2: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]
163
164@Builder
165function buildLoadingProgress(config: LoadingProgressConfiguration) {
166  Column({ space: 8 }) {
167    Row() {
168      Column() {
169        Circle({
170          width: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? 100 : 80,
171          height: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? 100 : 80
172        })
173          .fill(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
174      }.width('50%')
175
176      Column() {
177        Button('' + ((config.contentModifier as MyLoadingProgressStyle).enableLoading))
178          .onClick((event: ClickEvent) => {
179            promptAction.showToast({
180              message: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) + ''
181            })
182          })
183          .fontColor(Color.White)
184          .backgroundColor(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
185      }.width('50%')
186
187    }
188
189    Row() {
190      Column() {
191        Gauge({
192          value: (config.contentModifier as MyLoadingProgressStyle).enableLoading ? 50 : 30, min: 11, max: 100
193        }) {
194          Column() {
195            Text('60')
196              .maxFontSize("180sp")
197              .minFontSize("160.0vp")
198              .fontWeight(FontWeight.Medium)
199              .fontColor("#ff182431")
200              .width('40%')
201              .height('30%')
202              .textAlign(TextAlign.Center)
203              .margin({ top: '22.2%' })
204              .textOverflow({ overflow: TextOverflow.Ellipsis })
205              .maxLines(1)
206          }.width('100%').height('100%')
207        }
208        .colors(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
209        .width(200)
210        .strokeWidth(18)
211        .padding(5)
212        .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
213        .height(200)
214      }.width('100%')
215
216    }
217
218    Column() {
219      List({ space: 20, initialIndex: 0 }) {
220        ForEach(arr2, (item: string) => {
221          ListItem() {
222            Text((config.contentModifier as MyLoadingProgressStyle).enableLoading ? '' + item : Number(item) * 2 + '')
223              .width('100%')
224              .height('100%')
225              .fontColor((config.contentModifier as MyLoadingProgressStyle).enableLoading ? Color.White : Color.Orange)
226              .fontSize((config.contentModifier as MyLoadingProgressStyle).enableLoading ? 16 : 20)
227              .textAlign(TextAlign.Center)
228              .backgroundColor((config.contentModifier as MyLoadingProgressStyle).enableLoading ? Color.Grey : 0x2577e3)
229          }
230          .height(110)
231          .border({
232            width: 2,
233            color: Color.White
234          })
235        }, (item: string) => item)
236      }
237      .height(200)
238      .width('100%')
239      .friction(0.6)
240
241      .lanes({
242        minLength: (config.contentModifier as MyLoadingProgressStyle).enableLoading ? 40 : 80,
243        maxLength: (config.contentModifier as MyLoadingProgressStyle).enableLoading ? 40 : 80
244      })
245      .scrollBar(BarState.Off)
246    }
247
248  }.width("100%").padding(10)
249}
250
251
252@Entry
253@Component
254struct LoadingProgressDemoExample {
255  @State loadingProgressList: (boolean | undefined | null)[] = [undefined, true, null, false]
256  @State widthList: (number | string)[] = ['110%', 220, '40%', 80]
257  @State loadingProgressIndex: number = 0
258  @State clickFlag: number = 0
259  scroller: Scroller = new Scroller()
260
261  build() {
262    Column() {
263      Scroll(this.scroller) {
264        Column({ space: 5 }) {
265          Column() {
266            LoadingProgress()
267              .color('#106836')
268              .size({ width: '100%' })
269              .contentModifier(new MyLoadingProgressStyle(this.loadingProgressList[this.loadingProgressIndex]))
270          }.width('100%').backgroundColor(0xdcdcdc)
271        }.width('100%').margin({ top: 5 })
272      }.height('85%')
273
274      Button('点击切换config.enableloading').onClick(() => {
275        this.clickFlag++
276        this.loadingProgressIndex = (this.loadingProgressIndex + 1) % this.loadingProgressList.length
277        console.log('enableLoading:' + this.loadingProgressList[this.loadingProgressIndex])
278      }).margin(20)
279    }
280
281  }
282}
283```
284![LoadingProgress_builder](figures/LoadingProgress_builder.gif)