antd Progress 动态进度条实战用 React 状态驱动可交互的进度展示【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本文以 Ant DesignantdProgress组件的dynamic官方示例为核心讲解如何用 ReactuseState状态驱动进度条实时变化完整覆盖线型line与圆型circle两种形态的用法。文中不仅给出可直接运行的完整代码还结合本仓库中 Progress 源码、Line 实现、Circle 实现 及 demo 快照测试 剖析底层渲染与边界钳制原理帮助你从会用进阶到懂原理并能将其迁移到上传进度、任务执行、表单提交等真实业务场景。示例背景官方 Dynamic Demo 是什么在 antd 官方文档中Progress 组件提供了约 16 个示例见 Progress 组件文档其中 Dynamic动态展示示例对应的正是本文要讲解的 dynamic.tsx 及其 dynamic.md 说明。官方对该示例的中文描述只有一句话会动的进度条才是好进度条。英文为 A dynamic progress bar is better.——这句话点明了示例的核心意图Progress 并非只能静态展示一个固定百分比而是可以随着用户交互或数据变化实时刷新。该示例通过加号 / 减号两个按钮控制进度值让线型进度条与圆型进度圈同步变化是理解 antd 受控组件用法的经典入门案例。从组件目录结构看该示例被index.en-US.md与index.zh-CN.md通过code src./demo/dynamic.tsx的方式挂载到文档示例区并会被 demo 测试快照renders components/progress/demo/dynamic.tsx correctly自动渲染校验保证示例代码始终可用。完整代码与逐行拆解示例的完整代码位于 components/progress/demo/dynamic.tsx核心实现如下import React, { useState } from react; import { MinusOutlined, PlusOutlined } from ant-design/icons; import { Button, Flex, Progress } from antd; const App: React.FC () { const [percent, setPercent] useStatenumber(0); const increase () { setPercent((prevPercent) { const newPercent prevPercent 10; if (newPercent 100) { return 100; } return newPercent; }); }; const decline () { setPercent((prevPercent) { const newPercent prevPercent - 10; if (newPercent 0) { return 0; } return newPercent; }); }; return ( Flex vertical gapsmall Flex vertical gapsmall Progress percent{percent} typeline / Progress percent{percent} typecircle / /Flex Button.Group Button onClick{decline} icon{MinusOutlined /} / Button onClick{increase} icon{PlusOutlined /} / /Button.Group /Flex ); }; export default App;1. 状态管理唯一数据源const [percent, setPercent] useStatenumber(0);进度值percent是页面上唯一的数据源两个 Progress 组件共享同一个状态因此点击按钮后线型与圆型进度条会保持数值一致、同步动画。初始值为0对应 Progress 组件percent属性的默认值见 progress.tsx 源码 中percent 0的默认解构。2. 步进函数基于函数式更新的加减逻辑const increase () { setPercent((prevPercent) { const newPercent prevPercent 10; if (newPercent 100) { return 100; } return newPercent; }); }; const decline () { setPercent((prevPercent) { const newPercent prevPercent - 10; if (newPercent 0) { return 0; } return newPercent; }); };这里有两个值得注意的编码细节函数式更新setPercent(prev ...)回调接收上一次的状态值而非直接读取闭包中的percent。这在连续多次调用、或进度由定时器/异步任务驱动时能避免闭包过期问题是 React 官方推荐的写法。边界钳制clamp每次加 10超过 100 就固定为 100每次减 10小于 0 就固定为 0。这保证了传入percent的值永远在合法区间内。实际上即使你忘了做这个判断组件内部也有兜底——见下文源码级原理中对validProgress的分析。3. 布局与按钮组Flex vertical gapsmall ... Button.Group Button onClick{decline} icon{MinusOutlined /} / Button onClick{increase} icon{PlusOutlined /} / /Button.Group /FlexFlex是 antd 的弹性布局组件vertical让子元素纵向排列gapsmall控制间距Button.Group将两个图标按钮组合成连体按钮组按钮通过icon属性引入ant-design/icons的MinusOutlined减号与PlusOutlined加号点击分别触发decline与increase。两种形态line 与 circle 的渲染差异示例同时展示了 Progress 最常用的两种形态Progress percent{percent} typeline / Progress percent{percent} typecircle /形态type取值渲染方式默认尺寸线型进度条line默认值div CSS 宽度百分比见 Line.tsx高度 8pxsmall为 6px圆型进度圈circle基于rc-progress的 SVGcircle见 Circle.tsx120 × 120small为 60从 utils.ts 的getSize实现 可以确认线型默认高度size small ? 6 : 8且宽度为-1时外层自动撑满100%圆型默认尺寸size small ? 60 : 120内部文字字号由width * 0.15 6计算得出见 Circle.tsx所以圆越大中央百分比数字越大。源码级原理percent 是如何变成进度条的理解动态进度的底层逻辑需要看 Progress 的渲染链路progress.tsx入口分发→Line.tsx/Circle.tsx具体形态→utils.ts数值校验。1. 数值钳制validProgress在 utils.ts 中export function validProgress(progress?: number) { if (!progress || progress 0) { return 0; } if (progress 100) { return 100; } return progress; }无论你传入的percent是负数、NaN还是大于 100 的值最终渲染前都会被钳制到 0100 区间。线型进度条的宽度正是${validProgress(percent)}%见 Line.tsx圆型进度圈则通过getPercentage计算出实际角度数组见 utils.ts。这与示例中手动做边界判断的思路一致属于双保险。2. 状态自动判定percent ≥ 100 即 success在 progress.tsx 中const progressStatus React.useMemo(() { if (!ProgressStatuses.includes(status!) percentNumber 100) { return success; } return status || normal; }, [status, percentNumber]);当未显式指定status且进度达到 100 时组件会自动进入success状态线型进度条变为绿色圆型进度圈中央的数字会替换为对勾图标CheckCircleFilled/CheckOutlined见 progress.tsx。也就是说在 dynamic 示例中把进度加到 100 时你会看到状态自动变化——无需额外编码。3. 无障碍与可访问性roleprogressbar从 demo 快照 可以看到Progress 渲染出的 DOM 自带完整 ARIA 语义div aria-valuemax100 aria-valuemin0 aria-valuenow0 classant-progress ant-progress-status-normal ant-progress-line ... roleprogressbar 这来自 progress.tsx 中对容器元素roleprogressbar、aria-valuenow{percentNumber}、aria-valuemin{0}、aria-valuemax{100}的设置。percent每次变化aria-valuenow都会随之更新屏幕阅读器用户也能感知进度变化这是动态进度在无障碍层面的关键保障。4. 动画过渡圆型进度圈的 SVG 路径带有transition: stroke-dashoffset .3s ease ...见快照中style属性线型进度条同样依赖 CSS 过渡。因此当percent状态被按钮快速连续修改时进度条是平滑流动的而不是生硬跳变——这正是会动的进度条体验的来源。扩展实战把动态进度迁移到真实场景掌握了状态驱动的思路后你可以轻松扩展出多种真实场景的进度方案。场景一定时器驱动的进度如倒计时、任务轮询import React, { useEffect, useState } from react; import { Progress } from antd; const AutoProgress: React.FC () { const [percent, setPercent] useState(0); useEffect(() { const timer setInterval(() { setPercent((prev) (prev 100 ? 0 : prev 1)); }, 100); return () clearInterval(timer); }, []); return Progress percent{percent} /; };注意这里依然使用函数式更新setPercent((prev) ...)避免定时器闭包读到过期状态。场景二自定义文字格式format进度文案并不一定是百分比。参考 format 示例可以这样改造Progress percent{percent} format{(p) (p 100 ? Done : ${p} Days)} /format的函数签名是(percent?: number, successPercent?: number) ReactNode默认值为(percent) percent %见 index.en-US.md API 表格。场景三更多参数组合结合 Progress API 文档 与 ProgressProps 类型定义常用的动态场景参数如下参数说明类型默认值percent完成百分比动态进度的核心驱动值number0type形态line/circle/dashboardstringlineshowInfo是否显示进度数值与状态图标booleantruestatus状态success/exception/normal/active仅 linestring-strokeColor进度条颜色传对象可渲染渐变string | string[] | object-trailColor未填充部分的颜色string-strokeLinecap端点样式round/butt/squarestringroundsize尺寸数字 / 数组 / 对象 /small/defaultnumber | [number, number] | object | stringdefaultsuccess成功段配置{ percent, strokeColor }object-steps分步显示总数line 为 numbercircle 可为对象number | { count, gap }-例如模拟一个带失败状态的上传进度Progress percent{percent} status{percent 100 ? success : active} strokeColor{{ from: #108ee9, to: #87d068 }} /statusactive会为线型进度条附加流动动画条纹strokeColor传入{ from, to }对象时底层 handleGradient 会生成linear-gradient(to right, from, to)渐变背景。注意status是受控的一旦显式传入组件就不再依据percent 100自动切换状态。小结通过官方dynamic示例我们掌握了 antd Progress 动态进度的完整套路一个状态值 函数式更新 边界钳制 受控渲染。其底层由 progress.tsx 统一分发、Line.tsx 与 Circle.tsx 分别渲染、utils.ts 保证数值合法同时内置了 ARIA 无障碍语义与平滑过渡动画。把这套模式套用到上传、任务、轮询等任何过程可量化的业务中即可快速产出体验良好的进度反馈。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
