一、引言进度条是移动端 UI 中最通用的信息展示组件之一。无论是系统监控仪表盘上的 CPU 使用率、文件下载的传输进度、任务完成的百分比、还是存储空间的占用情况进度条都能以直观的图形方式将抽象的数字转化为可视的比例关系。一个设计良好的进度条不仅展示进度本身还通过颜色传递语义红色危险、绿色正常通过动画吸引注意力实时更新时平滑过渡通过多样化样式适配不同场景。在传统开发中实现不同样式的进度条需要组合 Canvas 绘图、CSS 动画、数学计算等技术环形进度条尤其复杂——需要计算圆弧路径、极坐标映射、绘制起点和终点。而 HarmonyOS 提供了Progress组件——一个内置四种进度条类型的一体化组件通过声明式 API 即可实现从简单线性条到复杂刻度环的所有样式。本文通过一个系统性能监控仪表盘Demo 深入讲解 Progress 组件的核心用法四种类型各自适用什么场景如何实现颜色阈值语义如何用 setInterval 模拟实时数据更新以及 Progress 组件与其他组件的组合模式。阅读完本文你将能够区分 Linear/Ring/Capsule/ScaleRing 四种类型的适用场景掌握value/total/type三个核心参数实现基于阈值的颜色语义正常→警告→危险使用setIntervalState实现实时进度动画构建系统监控仪表盘的整体方案二、Progress 组件 API 总览2.1 构造函数Progress(options:ProgressOptions)interfaceProgressOptions{value:number;// 当前进度值total:number;// 进度总量上限type?:ProgressType;// 进度条类型style?:ProgressStyle;// 进度条样式API 10可设置描边宽度等}参数类型默认值说明valuenumber必填当前值范围 [0, total]totalnumber必填最大值分母进度 value / totaltypeProgressTypeLinear四种类型之一styleProgressStyle-样式配置如strokeWidth环形/刻度环描边宽度2.2 ProgressType 四种类型enumProgressType{Linear,// 线性进度条——从左到右的横条Ring,// 环形进度条——圆环从顶部顺时针填充Capsule,// 胶囊进度条——圆角横条进度值在条内居中显示ScaleRing// 刻度环形进度条——圆环带刻度线}类型外观典型场景Linear水平横条左到右填充进度百分比、下载进度、电量条Ring圆环弧线顶部顺时针仪表盘指标、完成率、目标进度Capsule圆角横条内含文字存储空间、容量展示、评分分布ScaleRing圆环 外围刻度线速度表、转速表、精细化仪表2.3 链式方法// 当前值可动态更新.value(value:number):ProgressAttribute// 进度颜色.color(value:ResourceColor):ProgressAttribute// 通用宽度/高度.width(value:Length):ProgressAttribute.height(value:Length):ProgressAttribute// 通用圆角Linear/Capsule 生效.borderRadius(value:Length):ProgressAttribute方法说明.value(number)动态设置进度值配合State变量实现实时更新.color(ResourceColor)进度填充色支持基于阈值动态切换绿→橙→红.width(Length)组件宽度。Linear/Capsule 为条长度Ring/ScaleRing 为圆直径.height(Length)组件高度。Linear/Capsule 为条粗细Ring/ScaleRing 与 width 相同.borderRadius(Length)圆角半径Linear 类型常用 0-4 的圆角2.4 Progress vs 自建进度条方案特性Progress 组件自建方案线性进度ProgressType.Linear一行搞定Row 百分比计算 CSS 宽高环形进度ProgressType.Ring一行搞定Canvas 圆弧计算 极坐标映射刻度环形ProgressType.ScaleRing一行搞定Canvas 复杂刻度算法胶囊进度ProgressType.Capsule一行搞定Row borderRadius 文字居中颜色语义.color()动态切换手动切换 条件逻辑动画平滑度内置 Transition需手动 animateToProgress 组件适合所有标准进度展示场景。只有在需要高度定制的进度视觉效果如圆角方形节点、渐变色彩填充、自定义刻度形状时才考虑自建方案。三、Demo 设计系统性能监控3.1 功能概述Demo 是一个系统性能监控仪表盘模拟服务器或设备监控面板CPU 使用率 — Linear线性进度条展示 CPU 占用百分比带百分比数值和颜色状态标签内存使用 — Ring环形进度条展示内存使用量GB120vp 直径磁盘空间 — Capsule胶囊进度条展示存储占用内含文字 剩余空间运行进程 — ScaleRing刻度环展示进程数量140vp 直径颜色阈值三项指标根据实际值自动变色——正常蓝色、警告橙色、危险红色模拟监控点击开始监控按钮启动 setInterval1.5 秒间隔四个指标随机变化模拟实时数据3.2 交互点#交互说明1开始/停止监控setInterval 模拟实时数据流四种进度条同步变化2颜色阈值变化数值跨越 60%/85% 阈值时颜色实时切换蓝→橙→红3四种类型对比Linear/Ring/Capsule/ScaleRing 同时展示直观对比差异4状态标签每个进度条旁显示正常/警告/危险标签和数值四、完整代码实现4.1 状态变量StatecpuValue:number0;StatememoryValue:number0;StatestorageValue:number0;StaterunningValue:number0;StateisRunning:booleanfalse;privatetimerId:number-1;关键说明四个State数值变量分别对应 CPU0-100、内存0-16384 MB 16 GB、磁盘0-256 GB、进程数0-120isRunning控制按钮文字和 setInterval 的启停timerId保存 setInterval 返回的定时器 ID用于clearInterval停止定时器4.2 颜色阈值逻辑getProgressColor(value:number,max:number):string{constpctvalue/max;if(pct0.85)return#FF4D4F;if(pct0.6)return#FF9800;return#1677FF;}getColorLabel(value:number,max:number):string{constpctvalue/max;if(pct0.85)return危险;if(pct0.6)return警告;return正常;}颜色映射逻辑value / max计算百分比然后按阈值分级 60%蓝色#1677FF “正常”——系统运行健康60% ~ 85%橙色#FF9800 “警告”——需要注意负载较高≥ 85%红色#FF4D4F “危险”——接近极限有风险这个颜色方案遵循通用的交通灯语义让用户无需阅读数字就能快速判断系统状态。颜色同时作用于 Progress 组件的填充色和旁边的状态标签。4.3 模拟数据更新startMonitor(){this.isRunningtrue;this.timerIdsetInterval((){this.cpuValueMath.floor(Math.random()*100);this.memoryValueMath.floor(Math.random()*16384);this.storageValueMath.floor(Math.random()*256);this.runningValueMath.floor(Math.random()*120);},1500);}stopMonitor(){this.isRunningfalse;clearInterval(this.timerId);}aboutToDisappear(){if(this.isRunning){clearInterval(this.timerId);}}关键细节setInterval每 1.5 秒执行一次模拟监控数据轮询。间隔不宜太短高频更新增加渲染负担也不宜太长失去实时感1-2 秒是仪表盘的合理区间Math.random()生成的是均匀分布的随机数真实监控数据通常是平滑变化的。Demo 使用随机值是为了演示颜色变化的动态效果实际应用中应从ohos.systemCapability等系统 API 获取真实数据aboutToDisappear()是组件的生命周期回调在页面即将销毁时调用。这里用于清理定时器防止页面销毁后定时器仍在运行导致内存泄漏4.4 Linear 线性进度条 — CPU 使用率Progress({value:this.cpuValue,total:100,type:ProgressType.Linear}).value(this.cpuValue).color(this.getProgressColor(this.cpuValue,100)).height(8).borderRadius(4)配置要点total: 100意味着value就是百分比直接等于 CPU 占用率.height(8).borderRadius(4)8vp 高度的进度条配上 4vp 圆角形成圆润的横条。高度不宜太小看不清也不宜太大显得笨重6-10vp 是常用范围.color()动态绑定颜色随着 CPU 值变化实时切换Linear 类型的进度条适合横排展示单项指标旁边放数值和标签形成信息密度合适的行。4.5 Ring 环形进度条 — 内存使用Progress({value:this.memoryValue,total:16384,type:ProgressType.Ring}).value(this.memoryValue).color(this.getProgressColor(this.memoryValue,16384)).width(120).height(120)配置要点total: 16384表示 16 GB16384 MBvalue为当前使用的 MB 数.width(120).height(120)环形进度条的宽度和高度相等形成正圆。120vp 是仪表盘的常用尺寸——不大不小配合下方文字形成视觉平衡Ring 类型的进度条从顶部12 点钟方向开始顺时针填充。如果 valuetotal/250%圆环从顶部顺时针画半圈到底部Ring 适合展示单个指标的核心数值视觉上比 Linear 更突出、更具仪表感。配合下方大号数值文字形成图形 数据的双重展示。4.6 Capsule 胶囊进度条 — 磁盘空间Progress({value:this.storageValue,total:256,type:ProgressType.Capsule}).value(this.storageValue).color(this.getProgressColor(this.storageValue,256)).width(100%).height(32).borderRadius(16)配置要点total: 256表示 256 GB 总空间value为已用空间.height(32).borderRadius(16)32vp 高度 16vp 圆角 完美胶囊形圆角半径 高度的一半.width(100%)撑满容器适合作全宽展示Capsule 类型与 Linear 不同Linear 是细长的横条Capsule 是较粗的圆角横条且在条内居中显示文字如 “45/256”。它更像一个统计标签而非进度指示器适合存储空间、容量展示等场景。4.7 ScaleRing 刻度环形进度条 — 运行进程Progress({value:this.runningValue,total:120,type:ProgressType.ScaleRing}).value(this.runningValue).color(this.getProgressColor(this.runningValue,120)).width(140).height(140)配置要点ScaleRing 在 Ring 的基础上添加了外围刻度线——每个刻度代表一个单位让用户更精确地判断进度.width(140).height(140)比 Ring 略大140 vs 120因为刻度线需要额外空间ScaleRing 适合需要精确读取数值的场景如速度表、转速表刻度线使用户无需依赖文字就能大致判断百分比4.8 控制按钮if(this.isRunning){Button(⏸ 停止监控).fontSize(16).fontColor(#FFFFFF).backgroundColor(#FF4D4F).borderRadius(22).height(44).layoutWeight(1).onClick((){this.stopMonitor();})}else{Button(▶ 开始监控).fontSize(16).fontColor(#FFFFFF).backgroundColor(#1677FF).borderRadius(22).height(44).layoutWeight(1).onClick((){this.startMonitor();})}按钮通过isRunning切换显示——正在监控时显示红色停止监控未监控时显示蓝色开始监控。这个二元切换的设计避免了同时出现两个按钮造成的混淆。五、关键技术点详解5.1 value total 的进度计算Progress 组件内部通过value / total计算进度百分比。边界情况value 0进度为空不填充如 Linear 条完全空白、Ring 完全空心value total进度为满完全填充如 Ring 的圆弧闭合为完整圆value total进度截断为 100%不会超出value 0进度截断为 0%不会反向填充注意value和total是整数类型。如果需要小数精度如 3.5/10可以在业务层乘以 10 使用如 35/100 35%。5.2 .value() 方法的双重身份.value()方法既是构造函数参数也是链式方法但两者有细微区别// 方式 1构造函数中传 value初始值Progress({value:50,total:100,type:ProgressType.Linear})// 方式 2链式方法 .value()动态更新Progress({total:100,type:ProgressType.Linear}).value(this.cpuValue)// 通过 State 变量动态更新构造函数中的value是初始值链式方法.value()用于将State变量绑定到组件。当State变量变化时Progress 组件自动重新渲染并平滑过渡到新值。5.3 Progress 动画的平滑过渡Progress 组件在State变量变化时会自动触发过渡动画——不是生硬的跳变而是约 300ms 的平滑过渡。这意味着用setInterval更新的进度条不会出现抖动值的每次变化都以流畅的动画呈现。如果不需要动画如首次加载时从 0 跳到 50 不希望有过渡可以将.animation({ duration: 0 })作用于 Progress 组件来禁用动画。5.4 Ring 环形进度条的描边宽度控制Ring 和 ScaleRing 类型通过ProgressStyle控制描边宽度Progress({value:this.memoryValue,total:16384,type:ProgressType.Ring,style:{strokeWidth:12}// 描边宽度 12vp})strokeWidth默认值约 8-10vp。值越大弧线越粗值越小弧线越细Ring 和 ScaleRing 的描边是沿着圆弧路径绘制的所以描边宽度影响的是弧线的粗细而非圆的半径Capsule 和 Linear 类型不支持strokeWidth5.5 四种类型的语义选择选择哪种 Progress 类型取决于你想传达的信息场景推荐类型原因CPU/内存百分比Linear节省空间适合行内展示核心仪表指标Ring视觉突出仪表感强存储空间/容量Capsule内含文字信息密度高速度/转速/精度指标ScaleRing刻度线辅助精读多指标面板Linear Ring 混用区分主次指标六、运行效果6.1 初始状态页面顶部标题栏 系统监控下方组件介绍卡片然后是蓝色开始监控按钮。四个指标区域CPU-Linear、内存-Ring、磁盘-Capsule、进程-ScaleRing初始值均为 0进度条均显示为空状态。6.2 开始监控点击开始监控→ 按钮变为红色停止监控。四种进度条每 1.5 秒同步更新一次数值随机变化。6.3 颜色阈值效果CPU 值为 45% → Linear 进度条蓝色标签正常蓝色。内存值为 78%约 12.8 GB→ Ring 进度条橙色标签警告橙色。磁盘值为 92%约 235 GB→ Capsule 进度条红色标签危险红色。三个指标的不同颜色让系统状态一目了然。6.4 停止监控点击停止监控→ 按钮恢复蓝色开始监控进度条数值定格在当前值颜色基于当前数值保持不变。七、最佳实践与注意事项7.1 何时使用 Progress系统监控CPU、内存、磁盘、网络的实时使用率任务进度文件上传/下载、数据导入/导出、安装进度目标完成度每日步数达标、预算使用比例、学习进度容量展示存储空间已用/总量、云盘配额使用情况7.2 设计颜色方案// 推荐的三级颜色方案constCOLOR_SAFE#1677FF;// 蓝——正常范围constCOLOR_WARN#FF9800;// 橙——需要注意constCOLOR_DANGER#FF4D4F;// 红——立即关注不要使用黄色作为进度色对比度不足白色文字看不清。蓝色→橙色→红色是最通用的选择在各种背景下都足够醒目。7.3 常见问题Q: Progress 可以显示百分比文字吗A: 组件本身不提供文字显示功能Capsule 除外它内置显示 “value/total” 。需要在 Progress 旁边或下方使用 Text 组件手动显示百分比。Q: 如何实现下载进度条的双色效果已下载一侧、未下载一侧A: Progress 只支持单色.color()不支持多段颜色。如需多色方案可以用两个重叠的 Progress 或自定义 Row 实现。Q: ScaleRing 的刻度数量可以自定义吗A: 目前刻度数量由total值自动计算。如需特定刻度数量可以调整total来控制刻度密度total 越大刻度越密。Q: Ring 可以改成从底部或左侧开始填充吗A: 不可以。Ring 和 ScaleRing 的填充起点固定为 12 点钟方向顶部顺时针填充。无法自定义起点角度。如需特殊起点需要使用 Canvas 自定义绘制。7.4 性能注意事项setInterval中的State更新会触发组件树重新渲染。本 Demo 中四个指标分别独立更新每次只重新渲染对应的 Progress 组件ArkUI 的差异化更新机制如果同时更新大量 Progress 实例如列表中上百个建议使用LazyForEach懒加载渲染页面销毁时必须clearInterval清理定时器否则会造成内存泄漏八、拓展思考8.1 从模拟数据到真实数据Demo 使用Math.random()模拟监控数据。在真实应用中可以通过以下 API 获取系统数据import{systemDateTime}fromkit.BasicServicesKit;import{batteryInfo}fromkit.BasicServicesKit;import{deviceInfo}fromkit.BasicServicesKit;// 或通过 Native API 调用获取 CPU/内存信息8.2 多指标数据看板单个 Progress 是基础组件多个 Progress 组合则形成仪表盘。更完整的仪表盘可以包括数据对比当前值 vs 历史均值通过两个 Progress 或一个 Progress 一条参考线展示趋势指示Progress 旁边加箭头表示环比涨跌报警联动当 Progress 进入红色阈值时触发通知或弹窗8.3 与其他组件的配合Progress Text标准模式——进度条 百分比数字 标签文字Progress GaugeGauge 展示核心指标弧线仪表Progress 展示辅助指标横条Progress List多个 Progress 在列表中展示多项指标每行一个 LinearProgress CustomDialog弹窗中的下载进度条九、总结本文通过一个系统性能监控仪表盘的实战 Demo深入讲解了 HarmonyOS Progress 进度条组件的四种类型及其核心用法四种类型Linear线性、Ring环形、Capsule胶囊、ScaleRing刻度环各自适用不同的展示场景进度计算value / total决定填充比例State驱动动态更新颜色语义基于阈值的三级颜色映射蓝→橙→红强化信息传达效率实时模拟setIntervalState实现动态数据更新自动动画过渡生命周期管理aboutToDisappear清理定时器防止内存泄漏Progress 是 ArkUI 进度展示的标准解决方案。从系统监控到文件下载从任务进度到容量展示Progress 以其丰富的类型选择和简洁的声明式 API帮助开发者用最小代码实现最直观的进度可视化。希望本文能帮助你在实际项目中高效运用 Progress 组件。相关文章鸿蒙新特性-Rating星级评分组件详解 — 星级评分组件鸿蒙新特性-Gauge仪表盘组件详解 — 圆弧仪表盘即将发布本文基于 HarmonyOS NEXT API 24 编写代码经 DevEco Studio 6.1.1 编译验证通过。