# 进度条

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/progress
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

展示操作的当前进度。


## 何时使用 {#when-to-use}

在操作需要较长时间才能完成时，为用户显示该操作的当前进度和状态。

- 当一个操作会打断当前界面，或者需要在后台运行，且耗时可能超过 2 秒时；
- 当需要显示一个操作完成的百分比时。

## 代码演示 {#examples}


- 进度条 · `line`
- 进度圈 · `circle`
- 小型进度条 · `line-mini`
- 响应式进度圈 · `circle-micro`
- 小型进度圈 · `circle-mini`
- 动态展示 · `dynamic`
- 自定义文字格式 · `format`
- 仪表盘 · `dashboard`
- 分段进度条 · `segment`
- 边缘形状 · `linecap`
- 自定义进度条渐变色 · `gradient-line`
- 步骤进度条 · `steps`
- 步骤进度圈 · `circle-steps`
- 尺寸 · `size`
- 改变进度数值位置 · `info-position`
- 自定义语义结构的样式和类 · `style-class`

## API

通用属性参考：[通用属性](#jguang-common-props)

各类型共用的属性。

| 属性 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - | 6.0.0 | 6.0.0 |
| format | 内容的模板函数 | function(percent, successPercent) | (percent) => percent + `%` | - | × |
| percent | 百分比 | number | 0 | - | × |
| railColor | 未完成的分段的颜色 | string | - | - | × |
| showInfo | 是否显示进度数值或状态图标 | boolean | true | - | × |
| status | 状态，可选：`success` `exception` `normal` `active`(仅限 line) | string | - | - | × |
| strokeColor | 进度条的色彩 | string | - | - | × |
| strokeLinecap | 进度条的样式 | `round` \| `butt` \| `square`，区别详见 [stroke-linecap](https://developer.mozilla.org/docs/Web/SVG/Attribute/stroke-linecap) | `round` | - | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - | 6.0.0 | 6.0.0 |
| success | 成功进度条相关配置 | { percent: number, strokeColor: string } | - | - | × |
| ~~trailColor~~ | 未完成的分段的颜色。已废弃，请使用 `railColor` | string | - | - | × |
| type | 类型，可选 `line` `circle` `dashboard` | string | `line` | - | × |
| size | 进度条的尺寸 | number \| \[number \| string, number] \| { width: number, height: number } \| "small" \| "medium" | "medium" | 5.3.0, Object: 5.18.0 | × |

### `type="line"`

| 属性 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| steps | 进度条总共步数 | number | - | - |
| rounding | 用于四舍五入数值的函数 | (step: number) => number | Math.round | 5.24.0 |
| strokeColor | 进度条的色彩，传入 object 时为渐变。当有 `steps` 时支持传入一个数组。 | string \| string[] \| { from: string; to: string; direction: string } | - | 4.21.0: `string[]` |
| percentPosition | 进度数值位置，传入对象，`align` 表示数值的水平位置，`type` 表示数值在进度条内部还是外部 | { align: string; type: string } | { align: \"end\", type: \"outer\" } | 5.18.0 |

### `type="circle"`

| 属性 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| steps | 进度条总共步数，传入 object 时，count 指步数，gap 指间隔大小。传 number 类型时，gap 默认为 2。 | number \| { count: number, gap: number } | - | 5.16.0 |
| strokeColor | 圆形进度条线的色彩，传入 object 时为渐变 | string \| { number%: string } | - | - |
| strokeWidth | 圆形进度条线的宽度，单位是进度条画布宽度的百分比 | number | 6 | - |

### `type="dashboard"`

| 属性 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| steps | 进度条总共步数，传入 object 时，count 指步数，gap 指间隔大小。传 number 类型时，gap 默认为 2。 | number \| { count: number, gap: number } | - | 5.16.0 |
| gapDegree | 仪表盘进度条缺口角度，可取值 0 ~ 295 | number | 75 | - |
| gapPlacement | 仪表盘进度条缺口位置 | `top` \| `bottom` \| `start` \| `end` | `bottom` | - |
| ~~gapPosition~~ | 仪表盘进度条缺口位置，请使用 `gapPlacement` 替换 | `top` \| `bottom` \| `left` \| `right` | `bottom` | - |
| strokeWidth | 仪表盘进度条线的宽度，单位是进度条画布宽度的百分比 | number | 6 | - |

## Semantic DOM

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，设置相对定位和基础容器样式 | — |
| `body` | 主体元素，设置进度条的布局和尺寸样式 | — |
| `rail` | 导轨元素，设置背景轨道的颜色和圆角样式，steps 模式下没有该元素 | — |
| `track` | 轨迹元素，设置进度填充部分的颜色和过渡动画样式 | — |
| `indicator` | 指示器元素，设置百分比文本或图标的位置和字体样式 | — |

语义说明来源: `vendor/components/progress/demo/_semantic.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

| 令牌 | 类型 | 原生说明 |
| --- | --- | --- |
| `defaultColor` | `string` | 进度条默认颜色 |
| `remainingColor` | `string` | 进度条剩余部分颜色 |
| `circleTextColor` | `string` | 圆形进度条文字颜色 |
| `lineBorderRadius` | `number` | 条状进度条圆角 |
| `circleTextFontSize` | `string` | 圆形进度条文本大小 |
| `circleIconFontSize` | `string` | 圆形进度条图标大小 |

声明来源: `vendor/components/progress/style/index.ts`

```ts
import type { CSSObject } from '@ant-design/cssinjs';

import { Keyframes } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

export interface ComponentToken {
  /**
   * @desc 进度条默认颜色
   * @descEN Default color of progress bar
   */
  defaultColor: string;
  /**
   * @desc 进度条剩余部分颜色
   * @descEN Color of remaining part of progress bar
   */
  remainingColor: string;
  /**
   * @desc 圆形进度条文字颜色
   * @descEN Text color of circular progress bar
   */
  circleTextColor: string;
  /**
   * @desc 条状进度条圆角
   * @descEN Border radius of line progress bar
   */
  lineBorderRadius: number;
  /**
   * @desc 圆形进度条文本大小
   * @descEN Text size of circular progress bar
   */
  circleTextFontSize: string;
  /**
   * @desc 圆形进度条图标大小
   * @descEN Icon size of circular progress bar
   */
  circleIconFontSize: string;
}

/**
 * @desc Progress 组件的 Token
 * @descEN Token for Progress component
 */
interface ProgressToken extends FullToken<'Progress'> {
  /**
   * @desc 进度步骤最小宽度
   * @descEN Minimum width of progress step
   */
  progressStepMinWidth: number | string;
  /**
   * @desc 进度步骤右间距
   * @descEN Right margin of progress step
   */
  progressStepMarginInlineEnd: number | string;
  /**
   * @desc 进度条动画持续时间
   * @descEN Duration of progress bar animation
   */
  progressActiveMotionDuration: string;
}
```


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/progress/Circle.tsx`
- `vendor/components/progress/Line.tsx`
- `vendor/components/progress/Steps.tsx`
- `vendor/components/progress/progress.tsx`
- `vendor/components/progress/style/index.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt