输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
API参考应用框架ArkUI（方舟UI框架）ArkTS组件信息展示LoadingProgress

LoadingProgress

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
更新时间: 2026-09-01 03:59
本文导读
展开章节

LoadingProgress是用于显示加载进度条的组件，在数据加载过程中为用户提供视觉反馈，提升用户体验。该组件支持设置前景色、控制动画显示状态等特性，适用于需要在应用内展示加载进度的场景。

加载进度条的动效在组件不可见时停止，组件的可见状态基于onVisibleAreaChange处理，可见阈值ratios大于0即视为可见状态。

说明

  • 该组件从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

  • 该组件从API版本26.0.0开始支持WithTheme。

子组件

无

接口

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

LoadingProgress()

创建加载进度组件。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性

除支持通用属性外，还支持以下属性：

说明

组件应设置合理的宽高，当组件宽高设置过大时加载进度条的动效可能不符合预期效果。

color

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

color(value: ResourceColor)

设置加载进度条前景色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value ResourceColor 是

加载进度条的前景色。

默认值：

API version 10及以下：'#99666666'

API version 11及以上：'#ff666666'

enableLoading10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

enableLoading(value: boolean)

设置LoadingProgress动画是否显示。LoadingProgress动画不显示时，该组件依旧占位。通用属性Visibility.Hidden隐藏的是包括border、padding等整个组件范围，而enableLoading=false只隐藏LoadingProgress本身动画内容，不包括border等。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value boolean 是

LoadingProgress动画是否显示。

默认值：true，true表示显示LoadingProgress动画，false表示不显示LoadingProgress动画。

contentModifier12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

contentModifier(modifier: ContentModifier<LoadingProgressConfiguration>)

定制LoadingProgress内容区的方法。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
modifier ContentModifier<LoadingProgressConfiguration> 是

在LoadingProgress组件上，定制内容区的方法。

modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

支持通用事件。

LoadingProgressConfiguration12+对象说明

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

开发者需要自定义class实现ContentModifier接口。继承自CommonConfiguration。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
enableLoading boolean 否 否

LoadingProgress动画是否显示。

默认值：true，true表示显示LoadingProgress动画，false表示不显示LoadingProgress动画。

LoadingProgressStyle枚举说明

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

表示LoadingProgress的样式类型，不推荐使用。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 值 说明
Default 1 默认加载样式。API version 8及以后不支持设置。
Circular 2 环形加载样式。API version 8及以后不支持设置。
Orbital 3 彗星形加载样式。API version 8及以后默认为彗星形样式。

示例

示例1（设置颜色）

该示例通过color接口，实现了设置加载进度条颜色的功能。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct LoadingProgressExample {
  5.   build() {
  6.     Column({ space: 5 }) {
  7.       Text('Orbital LoadingProgress ').fontSize(9).fontColor(0xCCCCCC).width('90%')
  8.       LoadingProgress()
  9.         .color(Color.Blue)
  10.         .layoutWeight(1)
  11.     }.width('100%').margin({ top: 5 })
  12.   }
  13. }

示例2（设置定制内容区）

该示例通过contentModifier接口，实现了定制内容区的功能，并展示了如何基于LoadingProgressConfiguration的enableLoading属性切换自定义内容的显示效果。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { UIContext } from '@kit.ArkUI';
  3. 

  4. class MyLoadingProgressStyle implements ContentModifier<LoadingProgressConfiguration> {
  5.   enableLoading: boolean = false;
  6.   ctx: UIContext | undefined = undefined;
  7. 

  8.   constructor(enableLoading: boolean, ctx: UIContext) {
  9.     this.enableLoading = enableLoading;
  10.     this.ctx = ctx;
  11.   }
  12. 

  13.   applyContent(): WrappedBuilder<[LoadingProgressConfiguration]> {
  14.     return wrapBuilder(buildLoadingProgress);
  15.   }
  16. }
  17. 

  18. let arr: string[] = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'];
  19. 

  20. @Builder
  21. function buildLoadingProgress(config: LoadingProgressConfiguration) {
  22.   Column({ space: 8 }) {
  23.     Row() {
  24.       Column() {
  25.         Circle({
  26.           width: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? 100 : 80,
  27.           height: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? 100 : 80
  28.         })
  29.           .fill(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
  30.       }.width('50%')
  31. 

  32.       Column() {
  33.         Button('' + ((config.contentModifier as MyLoadingProgressStyle).enableLoading))
  34.           .onClick((event: ClickEvent) => {
  35.             let uiContext = (config.contentModifier as MyLoadingProgressStyle).ctx;
  36.             if (uiContext) {
  37.               uiContext.getPromptAction().showToast({
  38.                 message: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) + ''
  39.               });
  40.             }
  41.           })
  42.           .fontColor(Color.White)
  43.           .backgroundColor(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
  44.       }.width('50%')
  45. 

  46.     }
  47. 

  48.     Row() {
  49.       Column() {
  50.         Gauge({
  51.           value: (config.contentModifier as MyLoadingProgressStyle).enableLoading ? 50 : 30, min: 11, max: 100
  52.         }) {
  53.           Column() {
  54.             Text('60')
  55.               .maxFontSize('180sp')
  56.               .minFontSize('160.0vp')
  57.               .fontWeight(FontWeight.Medium)
  58.               .fontColor('#ff182431')
  59.               .width('40%')
  60.               .height('30%')
  61.               .textAlign(TextAlign.Center)
  62.               .margin({ top: '22.2%' })
  63.               .textOverflow({ overflow: TextOverflow.Ellipsis })
  64.               .maxLines(1)
  65.           }.width('100%').height('100%')
  66.         }
  67.         .colors(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
  68.         .width(200)
  69.         .strokeWidth(18)
  70.         .padding(5)
  71.         .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
  72.         .height(200)
  73.       }.width('100%')
  74. 

  75.     }
  76. 

  77.     Column() {
  78.       List({ space: 20, initialIndex: 0 }) {
  79.         ForEach(arr, (item: string) => {
  80.           ListItem() {
  81.             Text((config.contentModifier as MyLoadingProgressStyle).enableLoading ? '' + item : Number(item) * 2 + '')
  82.               .width('100%')
  83.               .height('100%')
  84.               .fontColor((config.contentModifier as MyLoadingProgressStyle).enableLoading ? Color.White : Color.Orange)
  85.               .fontSize((config.contentModifier as MyLoadingProgressStyle).enableLoading ? 16 : 20)
  86.               .textAlign(TextAlign.Center)
  87.               .backgroundColor((config.contentModifier as MyLoadingProgressStyle).enableLoading ? Color.Grey : 0x2577e3)
  88.           }
  89.           .height(110)
  90.           .border({
  91.             width: 2,
  92.             color: Color.White
  93.           })
  94.         }, (item: string) => item)
  95.       }
  96.       .height(200)
  97.       .width('100%')
  98.       .friction(0.6)
  99. 

  100.       .lanes({
  101.         minLength: (config.contentModifier as MyLoadingProgressStyle).enableLoading ? 40 : 80,
  102.         maxLength: (config.contentModifier as MyLoadingProgressStyle).enableLoading ? 40 : 80
  103.       })
  104.       .scrollBar(BarState.Off)
  105.     }
  106. 

  107.   }.width('100%').padding(10)
  108. }
  109. 

  110. 

  111. @Entry
  112. @Component
  113. struct LoadingProgressDemoExample {
  114.   @State loadingProgressList: (boolean | undefined | null)[] = [undefined, true, null, false];
  115.   @State loadingProgressIndex: number = 0;
  116.   scroller: Scroller = new Scroller();
  117. 

  118.   build() {
  119.     Column() {
  120.       Scroll(this.scroller) {
  121.         Column({ space: 5 }) {
  122.           Column() {
  123.             LoadingProgress()
  124.               .color('#106836')
  125.               .size({ width: '100%' })
  126.               .contentModifier(new MyLoadingProgressStyle(this.loadingProgressList[this.loadingProgressIndex], this.getUIContext()))
  127.           }.width('100%').backgroundColor(0xdcdcdc)
  128.         }.width('100%').margin({ top: 5 })
  129.       }.height('85%')
  130. 

  131.       Button('点击切换config.enableLoading').onClick(() => {
  132.         this.loadingProgressIndex = (this.loadingProgressIndex + 1) % this.loadingProgressList.length;
  133.         console.info('enableLoading:' + this.loadingProgressList[this.loadingProgressIndex]);
  134.       }).margin(20)
  135.     }
  136. 

  137.   }
  138. }

Gauge
Marquee
相关推荐
文档Progress
文档progress
文档进度条
文档页面加载Loading效果的实现
文档ProgressButton
文档组件内容填充方式
文档颜色渐变
文档文件打开加速状态感知（已废弃）
文档ProgressButtonV2
文档挂载卸载事件
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词