ant-design Progress 进度条组件设计解析从行为模型到源码实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designProgress 是 ant-design 反馈类组件中展示“任务进行程度”的核心组件。本篇以 components/progress/index.$tab-design.zh-CN.md 这一设计文档为主线结合组件源码与设计演示代码完整讲解 Progress 的行为定义、基础用法、状态表达、交互变体与样式变体并深入剖析其底层实现原理。读完本文你将掌握 Progress 在设计层与实现层的完整脉络能够针对不同业务场景任务进度、状态反馈、Dashboard 环形、内容级微型进度正确选型与配置。组件定义Progress 的本质是“了解任务的进度”设计文档开门见山地给出组件定义Progress 的本质是了解任务的进度。它不是单纯的数据展示而是帮助用户建立对长时间任务的心理预期——用户需要知道“任务完成到什么程度了”才能判断是否继续等待、是否需要介入。这一设计意图在 components/progress/design/behavior-pattern.tsx 中通过行为地图BehaviorMap被拆解为可落地的三层结构查看任务的完成程度mvp最小可用场景包含“了解任务进度”和“了解任务状态”两个基础用例查看进度相关描述extension扩展场景通过文字和图标补充进度之外的说明信息。也就是说Progress 的能力矩阵由“完成程度”数量维度与“任务状态”质量维度两条主线构成扩展能力则是“描述信息”的注入。这正是后续各 demo 的编排依据。基础使用用线形进度条了解任务进度最基础的使用方式是以线形展示“总进度”和“已完成进度”。设计文档的 progress.tsx 演示了两种线形形态import React from react; import { Flex, Progress } from antd; const Demo () ( Flex vertical gapmiddle {/* 默认尺寸线形进度条隐藏百分比文字便于纯视觉展示 */} Progress typeline percent{50} showInfo{false} style{{ width: 320 }} / {/* 小型线形进度条适用于空间紧凑的场景 */} Progress percent{50} showInfo{false} sizesmall style{{ width: 100 }} / /Flex );要点说明typeline是默认类型type的可选值为line、circle、dashboard源码见 progress.tsx 的ProgressTypes常量percent表示已完成百分比默认值为0showInfo{false}隐藏右侧百分比文字当进度条宽度较窄、文字会挤压视觉时推荐使用sizesmall切换小型尺寸size默认值为default源码 progress.tsx。基础使用用颜色表达任务状态进度不仅包含“完成了多少”还包含“当前处于什么状态”。设计文档的 status.tsx 用三种典型状态演示import React from react; import { Flex, Progress } from antd; const Demo () ( Flex vertical gapmiddle Flex div style{{ width: 106 }}任务进行中/div Progress typeline percent{50} showInfo{false} style{{ width: 320 }} / /Flex Flex div style{{ width: 106 }}任务完成/div Progress typeline percent{100} statussuccess showInfo{false} style{{ width: 320 }} / /Flex Flex div style{{ width: 106 }}任务失败/div Progress typeline percent{30} statusexception showInfo{false} style{{ width: 320 }} / /Flex /Flex );status的可选值为success、exception、normal、active仅限 line 类型对应源码 progress.tsx 的ProgressStatuses常量normal默认进行中状态蓝色进度条success任务完成绿色进度条exception任务失败/异常红色进度条active仅 line带流动动画的进行中状态。一个值得注意的源码细节是当未显式传入status且percent 100时组件会自动升级为success状态见 progress.tsx。这保证了“进度到 100% 就应表现为成功”这一直觉行为的正确性。交互变体通过文字和图标查看进度相关描述默认情况下进度条右侧会显示百分比数字。设计文档的 info.tsx 演示了如何用文字和图标承载更丰富的语义import React from react; import { Flex, Progress } from antd; const Demo () ( Flex vertical gapmiddle {/* 默认展示百分比数字 */} Progress typeline percent{50} style{{ width: 320 }} / {/* 用自定义文案替代百分比 */} Progress percent{50} format{() 加载中} style{{ width: 320 }} / {/* 成功状态显示对勾图标 */} Progress percent{100} statussuccess style{{ width: 320 }} / {/* 异常状态显示叉号图标 */} Progress percent{70} statusexception style{{ width: 320 }} / /Flex );其底层行为在 progress.tsx 的progressInfo中实现format是内容的模板函数(percent, successPercent) ReactNode默认值为(percent) percent %当状态为success或exception时若未自定义format文本会被替换为状态图标——line 类型使用CheckCircleFilled/CloseCircleFilledcircle/dashboard 类型使用CheckOutlined/CloseOutlined一旦传入format则始终优先渲染format的返回内容图标逻辑被覆盖。因此format是“描述注入”的入口可以返回进度单位、任务名称、剩余时间等任意 ReactNode从而让进度条成为信息密度更高的反馈载体。样式变体环形进度条Circle环形进度条多用于需要强调百分比的场景如 Dashboard 仪表盘展示。设计文档的 circle.tsx 演示了默认尺寸与小型尺寸下的三种状态import React from react; import { Flex, Progress } from antd; const Demo () ( Flex gapmiddle aligncenter {/* 默认尺寸环形进度条 */} Progress typecircle percent{68} / Progress typecircle percent{100} statussuccess / Progress typecircle percent{68} statusexception / {/* 小型环形进度条 */} Progress typecircle percent{68} sizesmall / Progress typecircle percent{100} statussuccess sizesmall / Progress typecircle percent{68} statusexception sizesmall / /Flex );环形类型还支持以下专属配置详见 index.zh-CN.md 的 API 表格strokeWidth环形线条宽度单位是进度条画布宽度的百分比默认6strokeColor线条颜色传入对象时为渐变key 为百分比断点如{ 0%: #108ee9, 100%: #87d068 }steps5.16.0分段环形进度可传number或{ count, gap }传number时gap默认为2。此外typedashboard仪表盘与 circle 共用同一套 Circle 渲染实现见 progress.tsx额外支持gapDegree缺口角度0~295默认 75与gapPosition缺口位置top/bottom/left/right默认bottom。样式变体内容级微型进度条“内容级进度条”适用于页面内容区、需要与文本内联排布的微型场景。设计文档的 content.tsx 展示了直径为 16px 的微型环形进度import React from react; import { Flex, Progress, theme } from antd; const Demo () { const { token } theme.useToken(); return ( Flex gaplarge Flex gapsmall aligncenter Progress size{16} typecircle percent{68} trailColor{token.colorPrimaryBg} / div进行中/div /Flex Flex gapsmall aligncenter Progress size{16} typecircle percent{100} statussuccess / div已完成/div /Flex Flex gapsmall aligncenter Progress size{16} typecircle percent{68} statusexception trailColor{token.colorErrorBg} / div错误/异常/div /Flex /Flex ); };关键点size接受数字、数组[number | string, number]、对象{ width, height }或预设值small/default5.3.0 起对象形式 5.18.0 起当 circle 类型的尺寸小于等于 20 时源码会为其附加-inline-circle样式类progress.tsx用于内联场景的特殊排版trailColor控制未完成分段的颜色这里借助theme.useToken()读取主题令牌让轨道色与语义色colorPrimaryBg、colorErrorBg保持一致实现“浅色底 语义进度”的柔和视觉。这种“微型环形 邻接文本”的组合常见于列表行、卡片详情、文件上传等需要一行内表达状态的界面。源码实现深入Progress 的渲染分派与无障碍支持从源码结构看progress.tsxProgress 组件的核心是一套按类型分派的渲染逻辑type line且传入steps时渲染 Steps 分段进度条type line未传steps时渲染 Line并透传percentPosition数值位置配置type circle或dashboard时统一渲染 Circle并传入计算好的progressStatus。值得关注的设计细节百分比数值位置percentPosition5.18.0支持{ align: start | center | end, type: inner | outer }默认{ align: end, type: outer }即数值显示在进度条右端外部设为inner时数值置于条内若自定义的strokeColor为亮色还会附加-text-bright类保证文字可读性progress.tsx。无障碍a11y根节点设置了roleprogressbar、aria-valuenow、aria-valuemin{0}、aria-valuemax{100}progress.tsx并支持透传aria-label/aria-labelledby保证了屏幕阅读器的可用性。废弃属性兼容successPercent建议改用success.percentwidth建议改用sizesuccess.progress建议改用success.percent在非生产环境会输出 deprecation 警告帮助开发者平滑迁移progress.tsx。API 速查表以下参数为各类型共用默认值以 index.zh-CN.md 为准属性说明类型默认值percent百分比number0format内容的模板函数(percent, successPercent) ReactNode(percent) percent %showInfo是否显示进度数值或状态图标booleantruestatus状态success/exception/normal/active仅 linestring-strokeColor进度条颜色line 传对象时为渐变circle 传对象时按百分比断点渐变string/string[]/ 对象-strokeLinecap线条端帽样式round/butt/squarestringroundsuccess成功进度条配置{ percent, strokeColor }对象-trailColor未完成分段的颜色string-type类型line/circle/dashboardstringlinesize尺寸number/[number\|string, number]/{ width, height }/small/default-default分类型专属参数typelinesteps总步数number、strokeColor数组渐变4.21.0、percentPosition5.18.0数值水平位置与内外位置typecirclestrokeWidth默认 6、strokeColor断点渐变、steps5.16.0number或{ count, gap }typedashboardgapDegree默认 75取值 0~295、gapPosition默认bottom、strokeWidth默认 6、steps5.16.0。组件的主题变量Design Token可通过 style/index.ts 与文档页的ComponentTokenTable查看用于在 ConfigProvider 中统一定制进度条配色与尺寸。总结ant-design 的 Progress 组件围绕“了解任务的进度”这一核心定义构建了从“完成程度percent”到“任务状态status”、再到“描述信息format/图标”的完整反馈体系在形态上覆盖 line、circle、dashboard 与 steps 四种载体并通过size、percentPosition、strokeColor、trailColor等参数适配从 Dashboard 大屏到内容级微型内联的各类场景。结合 progress.tsx 的源码可见其实现始终以“正确的状态推断、克制的信息渲染、完整的无障碍支持”为准则。更完整的配置与代码演示可继续阅读 components/progress/index.zh-CN.md 及 components/progress/demo 下的 16 个可直接运行的示例。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考