ant-design Progress 分段进度实战：用 success 属性细化进度的多层语义

ant-design Progress 分段进度实战用 success 属性细化进度的多层语义【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design本篇指南基于 ant-design 的Progress分段进度示例segment demo展开讲解如何通过percent与success两个属性在同一个进度条中同时表达“进行中”与“已完成”两类语义并适用于 line、circle、dashboard 三种形态。读完本文你将掌握该 demo 的完整代码用法、success属性的类型定义与解析逻辑以及从Line.tsx、Circle.tsx源码层面理解分段渲染的实现原理。示例定位为什么需要分段进度官方示例文档 components/progress/demo/segment.md 对这一用法的描述只有一句话但信息密度很高中文说明分段展示进度可以用于细化进度语义。英文说明Show several parts of progress with different status.“细化进度语义”是核心诉求很多业务场景中一个任务并不是单一维度的 0~100%而是同时存在多个子进度。例如一个部署流程有 10 个阶段其中 3 个已完成、3 个正在执行、4 个待执行。此时单靠一个percent无法表达“完成”与“进行中”的边界而Progress的success属性正是为此设计的percent表示总体进度success.percent表示其中已完成的分段两者叠加后轨道上会呈现出一段成功色绿色 一段进行色主题色的视觉效果。完整示例代码以下是 components/progress/demo/segment.tsx 的完整实现它用同一个数据组合percent{60}success{{ percent: 30 }}演示了三种形态import React from react; import { Flex, Progress, Tooltip } from antd; const App: React.FC () ( Flex gapsmall vertical Tooltip title3 done / 3 in progress / 4 to do Progress percent{60} success{{ percent: 30 }} / /Tooltip Flex gapsmall wrap Tooltip title3 done / 3 in progress / 4 to do Progress percent{60} success{{ percent: 30 }} typecircle / /Tooltip Tooltip title3 done / 3 in progress / 4 to do Progress percent{60} success{{ percent: 30 }} typedashboard / /Tooltip /Flex /Flex ); export default App;代码要点第一个Progress未指定type默认渲染为line线性进度条在 progress.tsx 中type line是解构默认值后两个分别通过typecircle与typedashboard渲染环形与仪表盘形态证明分段语义对三种形态通用每个进度条外层包了一个Tooltip把数字比例翻译成了人类可读的语义3 done / 3 in progress / 4 to do。进度条本身只显示60%这样的单一文本Tooltip 是补充“分段语义”的一种低成本做法。success 属性的定义与参数说明success的类型在 progress.tsx 中定义为export interface SuccessProps { percent?: number; strokeColor?: string; }结合组件 API 文档见 components/progress/index.zh-CN.md 的属性表与分段进度直接相关的参数如下参数说明类型默认值percent当前进度会被截断到 0~100 区间number0success成功进度条相关配置{ percent: number, strokeColor: string }-format内容模板函数可拿到两个入参(percent, successPercent) ReactNode(percent) percent %其中值得注意的三个行为细节format的第二个入参就是successPercent。在 progress.tsx 中indicator 文本通过textFormatter(validProgress(percent), validProgress(successPercent))生成因此你可以自定义文本把两段进度都写出来Progress percent{60} success{{ percent: 30 }} format{(percent, successPercent) ${successPercent}% done / ${percent}% total} /success.strokeColor可单独控制成功段颜色。在 index.test.tsx 中有对应的验证用例Progress percent{60} success{{ percent: 30, strokeColor: #ffffff }} /三种 type 均各有一个用例说明该配置对 line / circle / dashboard 都生效。数值会被夹取clamp到合法区间。utils.ts 中的validProgress会将小于 0 的值归零、大于 100 的值截断为 100因此传入异常数据时不会导致轨道溢出布局。源码剖析一段 success 是如何叠进轨道的百分比解析getPercentage 的双返回值分段的核心换算在 utils.tsexport const getPercentage ({ percent, success }: ProgressProps) { const realSuccessPercent validProgress(getSuccessPercent({ success })); return [realSuccessPercent, validProgress(validProgress(percent) - realSuccessPercent)]; };返回一个二元组[successPercent, percent - successPercent]。也就是说当percent{60} success{{ percent: 30 }}时组件实际按「成功段 30% 进行段 30%」来绘制——进行段的宽度是总进度减去成功段后的剩余部分而不是直接取percent。这保证了成功段不会在进行段之下重复渲染。线性形态双 track 绝对定位叠加Line.tsx 中轨道区域渲染了两条 trackPercent track宽度为validProgress(percent)%颜色取strokeColor支持字符串与渐变对象Success track仅当successPercent ! undefined时渲染宽度为validProgress(successPercent)%带有额外的${prefixCls}-track-success类名颜色取success.strokeColor。两条 track 均为绝对定位样式见 style/index.ts[${componentCls}-track]: { position: absolute }起点相同success track 渲染在 percent track 之后。由于成功段30%总包含在进行段60%之内从视觉上就形成了「绿 0~30% → 主题色 30%~60% → 灰色 60%~100%」的三段式效果。环形形态把两段百分比交给底层 SVG 组件环形与仪表盘形态走 Circle.tsx 的实现思路与线性不同通过getPercentage(props)拿到[successPercent, restPercent]后直接percent{percentArray}传入底层的rc-component/progress的RCCircleCircle.tsx描边颜色同样是一个二元组getStrokeColor返回[successColor || presetPrimaryColors.green, strokeColor]utils.ts默认成功段为绿色green与主题无关可通过success.strokeColor覆盖。因此环形形态下的“分段”本质上是 SVG 描边中一段绿色弧 一段主题色弧仪表盘typedashboard只是在此之上叠加了默认gapDegree 75的缺口见 Circle.tsx。无障碍与状态判定successPercent 会“接管”进度语义有两处容易忽略的逻辑都优先参考successPercentaria-valuenow。在 progress.tsx 中percentNumber的取值为若传入了success则以success.percent为准否则回退到percent。外层div以roleprogressbar暴露给辅助技术progress.tsx。也就是说从屏幕阅读器视角看这个分段进度条报告的是“已完成”的比例。success 状态判定。progress.tsx 中当未显式指定status且percentNumber 100时组件自动置为success状态indicator 显示对勾图标。因为percentNumber优先取successPercent所以是成功段达到 100%才触发 success 状态而非总进度。以上行为的正确性由 components/progress/tests/index.test.tsx 中的测试用例固化// percent100 但 success.percent50 → 不应出现 success 状态 Progress percent{100} success{{ percent: 50 }} / expect(wrapper.querySelectorAll(.ant-progress-status-success)).toHaveLength(0); // success.percent100 → 应出现 success 状态 rerender(Progress percent{50} success{{ percent: 100 }} /); expect(wrapper.querySelectorAll(.ant-progress-status-success)).toHaveLength(1);负数success.percent如success{{ percent: -20 }}也有专门的渲染测试配合validProgress的夹取逻辑保证不产生负宽度的 track。实战建议语义翻译交给 format 或 Tooltipdemo 用Tooltip把30/60/100翻译成 “3 done / 3 in progress / 4 to do”。如果你希望文字常驻显示优先使用format的第二个入参successPercent而不是在外部套 Tooltip这样可以保持line形态下文本跟随轨道对齐的能力percentPosition。注意 success 对状态与 ARIA 的接管如果你的业务里percent恒为 100 而success.percent表示完成比例那么 success 状态的出现时机由success.percent决定且aria-valuenow报告的是success.percent。成功段颜色默认绿色环形形态下默认值来自presetPrimaryColors.green与全局主题色解耦需要与主题统一时用success.strokeColor显式指定。三种形态共用同一套数据模型line 靠双 track 叠加circle / dashboard 靠双颜色描边弧但percent与success.percent的语义完全一致切换type无需改动数据层。参考文件示例说明文档components/progress/demo/segment.md示例代码components/progress/demo/segment.tsx组件主实现components/progress/progress.tsx百分比工具函数components/progress/utils.ts线性渲染components/progress/Line.tsx环形渲染components/progress/Circle.tsx样式实现components/progress/style/index.ts测试用例components/progress/tests/index.test.tsx组件 API 文档components/progress/index.zh-CN.md【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考