Ant Design Progress 仪表盘进度条（Dashboard）实战指南：type 与 gapDegree 完全解析

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组件在type="line"（线性进度条）和type="circle"（进度圈）之外，还提供了一种**仪表盘（dashboard）**形态：一个带缺口的半圆环进度指示器，非常适合用于展示完成率、评分、配额使用率等"接近达成目标"类场景。本指南以 dashboard 示例文档 为核心，系统讲解仪表盘进度条的接入方式、缺口角度（gapDegree）与缺口位置（gapPosition）的调节技巧，并结合仓库源码（progress.tsx、Circle.tsx、utils.ts）与测试用例（index.test.tsx）说明底层实现原理与边界行为，帮助你直接上手并深入调优。

一、快速上手：一条代码实现仪表盘

Ant Design 官方文档（dashboard.md）给出了最核心的结论：通过设置type="dashboard"，可以很方便地实现仪表盘样式的进度条；若想要修改缺口的角度，可以设置gapDegree为你想要的值。

对应的完整示例代码位于 components/progress/demo/dashboard.tsx：

import React from 'react'; import { Flex, Progress } from 'antd'; const App: React.FC = () => ( <Flex gap="small" wrap> <Progress type="dashboard" percent={75} /> <Progress type="dashboard" 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 组件文档 的type="dashboard"小节中，官方给出了该形态的全部专属参数：

属性	说明	类型	默认值
steps	步进数，传入对象时count指步数、gap指间隔；传入数字时gap默认为 2	number | { count: number, gap: number }	-
gapDegree	仪表盘进度条缺口角度	number（可取值 0 ~ 295）	75
gapPosition	仪表盘进度条缺口位置	top|bottom|left|right	bottom
strokeWidth	仪表盘进度条线的宽度，单位是进度条画布宽度的百分比	number	6

此外，仪表盘继承Progress的通用属性，其中与本形态最相关的是：

• percent：完成百分比，number，默认0；
• showInfo：是否显示进度数值或状态图标，boolean，默认true；
• format：内容的模板函数(percent, successPercent) => ReactNode，默认(percent) => percent + '%'；
• success：成功进度条配置{ percent, strokeColor }；
• status：success/exception/normal/active（active仅限 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.useMemo<RcProgressProps['gapDegree']>(() => { // Support gapDeg = 0 when type = 'dashboard' if (gapDegree || gapDegree === 0) { return gapDegree; } if (type === 'dashboard') { return 75; } return undefined; }, [gapDegree, type]);

这段代码有两个关键点：

1. 显式兼容gapDegree={0}：由于0是 falsy 值，若写成if (gapDegree)会把 0 忽略并回退到默认 75，因此这里特意追加了gapDegree === 0的判断，保证用户传入0时缺口真实闭合；
2. type === 'dashboard'时自动回退到 75：即不传gapDegree时默认缺口为 75°。

2.2gapPosition：控制缺口的朝向

与gapDegree配套的是gapPosition，它决定缺口开在圆环的哪个方位，取值top/bottom/left/right，默认bottom。在 Circle.tsx 中同样存在自动回退逻辑：

const gapPos = gapPosition || (type === 'dashboard' && 'bottom') || undefined;

即仪表盘形态下未显式指定时，缺口默认朝下（bottom），这也是最常见的"仪表盘开口朝下"视觉形态。调整gapPosition="top"后即可得到开口朝上的环形进度。

三、源码级解析：仪表盘是如何渲染出来的

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归一化为circle（progress.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) * 100（CIRCLE_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 }} type="dashboard" />); expect(...).toContain( 'Type "circle" and "dashboard" do not accept object as `size`, please use number or preset size instead.', ); });

3.4 无障碍与状态语义

无论何种类型，Progress根节点都会挂载role="progressbar"与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 type="dashboard" gapDegree={0} />); expect(wrapper.firstChild).toMatchSnapshot(); }); it('render dashboard 295 gapDegree', () => { const { container: wrapper } = render(<Progress type="dashboard" gapDegree={295} />); expect(wrapper.firstChild).toMatchSnapshot(); }); it('render dashboard 296 gapDegree', () => { const { container: wrapper } = render(<Progress type="dashboard" gapDegree={296} />); expect(wrapper.firstChild).toMatchSnapshot(); });

结合这些用例与文档中的取值范围说明（0 ~ 295），可以得到以下实践结论：

• gapDegree = 0：缺口闭合，等价于标准半圆环；
• gapDegree = 75：默认仪表盘开角，官方视觉规范推荐值；
• gapDegree = 295：可接受的最大缺口，此时仅剩约 65° 的弧线；
• gapDegree > 295：超出文档声明范围，行为不受官方保证。

此外，测试中还验证了仪表盘与success配置的联动（index.test.tsx#L118-L123）：

it('render successColor progress type="dashboard"', () => { const { container: wrapper } = render( <Progress percent={60} type="dashboard" success={{ percent: 30, strokeColor: '#ffffff' }} />, ); expect(wrapper.firstChild).toMatchSnapshot(); });

即在仪表盘中，success.percent会以绿色（默认#52c41a，见 utils.ts 的 getStrokeColor）先行绘制已完成部分，主进度色再叠加上去，用于表达"其中一部分已完成得更彻底"的细分进度语义。

五、实战扩展：常见组合用法

在掌握type="dashboard"、gapDegree、gapPosition三个核心点后，可结合实际需求做如下扩展：

5.1 自定义数值文本

<Progress type="dashboard" percent={75} format={(percent) => `${percent} / 100`} />

5.2 调整尺寸与线宽

<Progress type="dashboard" percent={75} size={160} strokeWidth={10} />

注意：size只能传数字或"small"/"default"（仪表盘不支持数组 / 对象形式）。

5.3 配合状态图标

<Progress type="dashboard" percent={100} /> {/* percent 达到 100 且未指定 status 时，自动呈现 success 状态 */}

5.4 缺口位置与角度组合

<Progress type="dashboard" percent={75} gapDegree={120} gapPosition="top" />

将缺口开在顶部、开角放大到 120°，即可得到"开口向上"的仪表盘变体。

六、小结

• 核心用法：在Progress上设置type="dashboard"即可获得仪表盘样式（官方示例说明）；
• 缺口控制：gapDegree控制缺口角度（默认75，范围0 ~ 295，源码在 Circle.tsx 中显式兼容0），gapPosition控制缺口方位（默认bottom）；
• 渲染本质：仪表盘与进度圈共用Circle渲染管线与progress-circle样式类（见 progress.tsx），差异仅由缺口参数体现；
• 默认尺寸：120 × 120（"small"为 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