ant-design Progress 进度条组件设计解析：从行为模型到源码实现

ant-design Progress 进度条组件设计解析：从行为模型到源码实现

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design

Progress 是 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 gap="middle"> {/* 默认尺寸线形进度条，隐藏百分比文字，便于纯视觉展示 */} <Progress type="line" percent={50} showInfo={false} style={{ width: 320 }} /> {/* 小型线形进度条，适用于空间紧凑的场景 */} <Progress percent={50} showInfo={false} size="small" style={{ width: 100 }} /> </Flex> );

要点说明：

• type="line"是默认类型，type的可选值为line、circle、dashboard（源码见 progress.tsx 的ProgressTypes常量）；
• percent表示已完成百分比，默认值为0；
• showInfo={false}隐藏右侧百分比文字，当进度条宽度较窄、文字会挤压视觉时推荐使用；
• size="small"切换小型尺寸，size默认值为"default"（源码 progress.tsx）。

基础使用：用颜色表达任务状态

进度不仅包含“完成了多少”，还包含“当前处于什么状态”。设计文档的 status.tsx 用三种典型状态演示：

import React from 'react'; import { Flex, Progress } from 'antd'; const Demo = () => ( <Flex vertical gap="middle"> <Flex> <div style={{ width: 106 }}>任务进行中</div> <Progress type="line" percent={50} showInfo={false} style={{ width: 320 }} /> </Flex> <Flex> <div style={{ width: 106 }}>任务完成</div> <Progress type="line" percent={100} status="success" showInfo={false} style={{ width: 320 }} /> </Flex> <Flex> <div style={{ width: 106 }}>任务失败</div> <Progress type="line" percent={30} status="exception" 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 gap="middle"> {/* 默认展示百分比数字 */} <Progress type="line" percent={50} style={{ width: 320 }} /> {/* 用自定义文案替代百分比 */} <Progress percent={50} format={() => '加载中'} style={{ width: 320 }} /> {/* 成功状态：显示对勾图标 */} <Progress percent={100} status="success" style={{ width: 320 }} /> {/* 异常状态：显示叉号图标 */} <Progress percent={70} status="exception" style={{ width: 320 }} /> </Flex> );

其底层行为在 progress.tsx 的progressInfo中实现：

• format是内容的模板函数(percent, successPercent) => ReactNode，默认值为(percent) => percent + '%'；
• 当状态为success或exception时，若未自定义format，文本会被替换为状态图标——line 类型使用CheckCircleFilled/CloseCircleFilled，circle/dashboard 类型使用CheckOutlined/CloseOutlined；
• 一旦传入format，则始终优先渲染format的返回内容，图标逻辑被覆盖。

因此format是“描述注入”的入口：可以返回进度单位、任务名称、剩余时间等任意 ReactNode，从而让进度条成为信息密度更高的反馈载体。

样式变体：环形进度条（Circle）

环形进度条多用于需要强调百分比的场景，如 Dashboard 仪表盘展示。设计文档的 circle.tsx 演示了默认尺寸与小型尺寸下的三种状态：

import React from 'react'; import { Flex, Progress } from 'antd'; const Demo = () => ( <Flex gap="middle" align="center"> {/* 默认尺寸环形进度条 */} <Progress type="circle" percent={68} /> <Progress type="circle" percent={100} status="success" /> <Progress type="circle" percent={68} status="exception" /> {/* 小型环形进度条 */} <Progress type="circle" percent={68} size="small" /> <Progress type="circle" percent={100} status="success" size="small" /> <Progress type="circle" percent={68} status="exception" size="small" /> </Flex> );

环形类型还支持以下专属配置（详见 index.zh-CN.md 的 API 表格）：

• strokeWidth：环形线条宽度，单位是进度条画布宽度的百分比，默认6；
• strokeColor：线条颜色，传入对象时为渐变（key 为百分比断点，如{ '0%': '#108ee9', '100%': '#87d068' }）；
• steps（5.16.0+）：分段环形进度，可传number或{ count, gap }，传number时gap默认为2。

此外，type="dashboard"（仪表盘）与 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 gap="large"> <Flex gap="small" align="center"> <Progress size={16} type="circle" percent={68} trailColor={token.colorPrimaryBg} /> <div>进行中</div> </Flex> <Flex gap="small" align="center"> <Progress size={16} type="circle" percent={100} status="success" /> <div>已完成</div> </Flex> <Flex gap="small" align="center"> <Progress size={16} type="circle" percent={68} status="exception" trailColor={token.colorErrorBg} /> <div>错误/异常</div> </Flex> </Flex> ); };

关键点：

• size接受数字、数组[number | string, number]、对象{ width, height }或预设值"small"/"default"（5.3.0 起，对象形式 5.18.0 起）；
• 当 circle 类型的尺寸小于等于 20 时，源码会为其附加-inline-circle样式类（progress.tsx），用于内联场景的特殊排版；
• trailColor控制未完成分段的颜色，这里借助theme.useToken()读取主题令牌，让轨道色与语义色（colorPrimaryBg、colorErrorBg）保持一致，实现“浅色底 + 语义进度”的柔和视觉。

这种“微型环形 + 邻接文本”的组合常见于列表行、卡片详情、文件上传等需要一行内表达状态的界面。

源码实现深入：Progress 的渲染分派与无障碍支持

从源码结构看（progress.tsx），Progress 组件的核心是一套按类型分派的渲染逻辑：

1. type === 'line'且传入steps时，渲染 Steps 分段进度条；
2. type === 'line'未传steps时，渲染 Line，并透传percentPosition（数值位置）配置；
3. type === 'circle'或dashboard时，统一渲染 Circle，并传入计算好的progressStatus。

值得关注的设计细节：

• 百分比数值位置：percentPosition（5.18.0+）支持{ align: 'start' | 'center' | 'end', type: 'inner' | 'outer' }，默认{ align: 'end', type: 'outer' }，即数值显示在进度条右端外部；设为inner时数值置于条内，若自定义的strokeColor为亮色，还会附加-text-bright类保证文字可读性（progress.tsx）。
• 无障碍（a11y）：根节点设置了role="progressbar"、aria-valuenow、aria-valuemin={0}、aria-valuemax={100}（progress.tsx），并支持透传aria-label/aria-labelledby，保证了屏幕阅读器的可用性。
• 废弃属性兼容：successPercent建议改用success.percent，width建议改用size，success.progress建议改用success.percent；在非生产环境会输出 deprecation 警告，帮助开发者平滑迁移（progress.tsx）。

API 速查表

以下参数为各类型共用（默认值以 index.zh-CN.md 为准）：

分类型专属参数：

• type="line"：steps（总步数，number）、strokeColor数组渐变（4.21.0+）、percentPosition（5.18.0+，数值水平位置与内外位置）；
• type="circle"：strokeWidth（默认 6）、strokeColor断点渐变、steps（5.16.0+，number或{ count, gap }）；
• type="dashboard"：gapDegree（默认 75，取值 0~295）、gapPosition（默认bottom）、strokeWidth（默认 6）、steps（5.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