Ant Design Progress 仪表盘进度条Dashboard实战指南type 与 gapDegree 完全解析【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读Ant Design 的Progress组件在typeline线性进度条和typecircle进度圈之外还提供了一种**仪表盘dashboard**形态一个带缺口的半圆环进度指示器非常适合用于展示完成率、评分、配额使用率等接近达成目标类场景。本指南以 dashboard 示例文档 为核心系统讲解仪表盘进度条的接入方式、缺口角度gapDegree与缺口位置gapPosition的调节技巧并结合仓库源码progress.tsx、Circle.tsx、utils.ts与测试用例index.test.tsx说明底层实现原理与边界行为帮助你直接上手并深入调优。一、快速上手一条代码实现仪表盘Ant Design 官方文档dashboard.md给出了最核心的结论通过设置typedashboard可以很方便地实现仪表盘样式的进度条若想要修改缺口的角度可以设置gapDegree为你想要的值。对应的完整示例代码位于 components/progress/demo/dashboard.tsximport React from react; import { Flex, Progress } from antd; const App: React.FC () ( Flex gapsmall wrap Progress typedashboard percent{75} / Progress typedashboard percent{75} gapDegree{30} / /Flex ); export default App;该示例同时渲染了两个仪表盘第一个使用默认缺口75°第二个通过gapDegree{30}将缺口缩小为 30°形成几乎闭合的半环。可以看到仪表盘形态下你甚至不需要设置width或size——默认即以 120 × 120 的画布呈现见下文源码分析。这段示例同样被纳入了快照测试体系在 components/progress/tests/snapshots/demo.test.ts.snap 中存在renders components/progress/demo/dashboard.tsx correctly的快照保证示例在每次回归测试中渲染结果稳定。二、仪表盘专属 API 与默认值在 Progress 组件文档 的typedashboard小节中官方给出了该形态的全部专属参数属性说明类型默认值steps步进数传入对象时count指步数、gap指间隔传入数字时gap默认为 2number | { count: number, gap: number }-gapDegree仪表盘进度条缺口角度number可取值 0 ~ 29575gapPosition仪表盘进度条缺口位置top|bottom|left|rightbottomstrokeWidth仪表盘进度条线的宽度单位是进度条画布宽度的百分比number6此外仪表盘继承Progress的通用属性其中与本形态最相关的是percent完成百分比number默认0showInfo是否显示进度数值或状态图标boolean默认trueformat内容的模板函数(percent, successPercent) ReactNode默认(percent) percent %success成功进度条配置{ percent, strokeColor }statussuccess/exception/normal/activeactive仅限 line 类型size尺寸number | [number|string, number] | { width, height } | small | default默认default。2.1 理解gapDegree缺口角度如何作用于半环gapDegree的含义是半圆缺口的角度以度为单位数值越大缺口越宽、圆环覆盖的弧度越小。默认值75是 Ant Design 视觉规范中仪表盘的经典开角设为0时缺口完全闭合呈现标准半圆最大可到295。值得注意的是在 Circle.tsx 中有专门为gapDegree 0设计的逻辑const realGapDegree React.useMemoRcProgressProps[gapDegree](() { // Support gapDeg 0 when type dashboard if (gapDegree || gapDegree 0) { return gapDegree; } if (type dashboard) { return 75; } return undefined; }, [gapDegree, type]);这段代码有两个关键点显式兼容gapDegree{0}由于0是 falsy 值若写成if (gapDegree)会把 0 忽略并回退到默认 75因此这里特意追加了gapDegree 0的判断保证用户传入0时缺口真实闭合type dashboard时自动回退到 75即不传gapDegree时默认缺口为 75°。2.2gapPosition控制缺口的朝向与gapDegree配套的是gapPosition它决定缺口开在圆环的哪个方位取值top/bottom/left/right默认bottom。在 Circle.tsx 中同样存在自动回退逻辑const gapPos gapPosition || (type dashboard bottom) || undefined;即仪表盘形态下未显式指定时缺口默认朝下bottom这也是最常见的仪表盘开口朝下视觉形态。调整gapPositiontop后即可得到开口朝上的环形进度。三、源码级解析仪表盘是如何渲染出来的3.1 类型分发dashboard 与 circle 共用渲染管线在 progress.tsx 中Progress支持三种类型export const ProgressTypes [line, circle, dashboard] as const;当type为circle或dashboard时二者共用同一个渲染分支progress.tsx#L212-L223} else if (type circle || type dashboard) { progress ( Circle {...props} strokeColor{strokeColorNotArray} prefixCls{prefixCls} progressStatus{progressStatus} {progressInfo} /Circle ); }同时样式类名将dashboard归一化为circleprogress.tsx#L229{ [${prefixCls}-${(type dashboard circle) || type}]: type ! line },也就是说从渲染管线到样式体系仪表盘都被视为带缺口的进度圈二者的差异完全由gapDegree/gapPosition这两个参数体现。3.2 尺寸与线宽getSize 的默认值推导仪表盘画布的默认尺寸由 utils.ts 的 getSize 决定} else if (type circle || type dashboard) { if (typeof size string || typeof size undefined) { [width, height] size small ? [60, 60] : [120, 120]; } else if (typeof size number) { [width, height] [size, size]; } else if (Array.isArray(size)) { width (size[0] ?? size[1] ?? 120) as number; height (size[0] ?? size[1] ?? 120) as number; } }不传size或传default画布为120 × 120传small画布为60 × 60传数字等比例缩放到size × size。线宽strokeWidth默认值为6占画布宽度的百分比且在 Circle.tsx 中还有最小线宽保护逻辑let { strokeWidth } props; if (strokeWidth undefined) { strokeWidth Math.max(getMinPercent(width), 6); }其中getMinPercent (width) (3 / width) * 100CIRCLE_MIN_STROKE_WIDTH 3即画布较小时线宽也不会低于能看清的 3% 下限。3.3 仪表盘不允许数组 / 对象形式的 size由于圆形与仪表盘必须保持正方形画布progress.tsx 在开发环境下会针对circle/dashboard形态给出告警不允许传入数组或对象形式的size如size{[60, 20]}或size{{ width: 60, height: 20 }}只支持数字或预设字符串尺寸。该行为在 index.test.tsx 中有对应断言例如it(should warnning if pass object into size in type dashboard, () { render(Progress size{{ width: 60, height: 20 }} typedashboard /); expect(...).toContain( Type circle and dashboard do not accept object as size, please use number or preset size instead., ); });3.4 无障碍与状态语义无论何种类型Progress根节点都会挂载roleprogressbar与aria-valuenow/aria-valuemin{0}/aria-valuemax{100}progress.tsx#L251-L254仪表盘同样受益。当percent 100且未显式指定status时组件会自动切换为success状态展示对勾图标与成功色progress.tsx#L108-L113。四、边界行为与测试验证官方测试文件 components/progress/tests/index.test.tsx 覆盖了仪表盘的关键边界是理解参数取值范围的可靠依据it(render dashboard zero gapDegree, () { const { container: wrapper } render(Progress typedashboard gapDegree{0} /); expect(wrapper.firstChild).toMatchSnapshot(); }); it(render dashboard 295 gapDegree, () { const { container: wrapper } render(Progress typedashboard gapDegree{295} /); expect(wrapper.firstChild).toMatchSnapshot(); }); it(render dashboard 296 gapDegree, () { const { container: wrapper } render(Progress typedashboard gapDegree{296} /); expect(wrapper.firstChild).toMatchSnapshot(); });结合这些用例与文档中的取值范围说明0 ~ 295可以得到以下实践结论gapDegree 0缺口闭合等价于标准半圆环gapDegree 75默认仪表盘开角官方视觉规范推荐值gapDegree 295可接受的最大缺口此时仅剩约 65° 的弧线gapDegree 295超出文档声明范围行为不受官方保证。此外测试中还验证了仪表盘与success配置的联动index.test.tsx#L118-L123it(render successColor progress typedashboard, () { const { container: wrapper } render( Progress percent{60} typedashboard success{{ percent: 30, strokeColor: #ffffff }} /, ); expect(wrapper.firstChild).toMatchSnapshot(); });即在仪表盘中success.percent会以绿色默认#52c41a见 utils.ts 的 getStrokeColor先行绘制已完成部分主进度色再叠加上去用于表达其中一部分已完成得更彻底的细分进度语义。五、实战扩展常见组合用法在掌握typedashboard、gapDegree、gapPosition三个核心点后可结合实际需求做如下扩展5.1 自定义数值文本Progress typedashboard percent{75} format{(percent) ${percent} / 100} /5.2 调整尺寸与线宽Progress typedashboard percent{75} size{160} strokeWidth{10} /注意size只能传数字或small/default仪表盘不支持数组 / 对象形式。5.3 配合状态图标Progress typedashboard percent{100} / {/* percent 达到 100 且未指定 status 时自动呈现 success 状态 */}5.4 缺口位置与角度组合Progress typedashboard percent{75} gapDegree{120} gapPositiontop /将缺口开在顶部、开角放大到 120°即可得到开口向上的仪表盘变体。六、小结核心用法在Progress上设置typedashboard即可获得仪表盘样式官方示例说明缺口控制gapDegree控制缺口角度默认75范围0 ~ 295源码在 Circle.tsx 中显式兼容0gapPosition控制缺口方位默认bottom渲染本质仪表盘与进度圈共用Circle渲染管线与progress-circle样式类见 progress.tsx差异仅由缺口参数体现默认尺寸120 × 120small为 60 × 60线宽默认 6画布宽度百分比由 utils.ts 的getSize推导边界验证gapDegree的0/295/296与success组合、size非法形态告警均有对应测试用例index.test.tsx可作为参数取值范围的权威依据。掌握了以上内容你就可以在项目中快速接入仪表盘进度并通过gapDegree与gapPosition精确塑造环形的开合形态适配不同场景的视觉与信息表达需求。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考