> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/progress.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Progress 进度条

展示任务的完成程度。


## 基础用法

通过 `percent` 传入完成百分比，并用 `aria-label` 标识具体任务。


45%

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/basic.tsx"
import { Progress } from '@ifhover/leaf-ui';

export function ProgressBasic() {
  return <Progress percent={45} aria-label="上传进度" />;
}
```

展开代码


## 示例

### 进度状态

达到 `100` 时自动显示成功状态。任务失败时设置 `status="error"`。


进行中

45%

已完成

失败

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/states.tsx"
import { Flex, Progress, Space, Text } from '@ifhover/leaf-ui';

export function ProgressStates() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm">
        <Text tone="muted">进行中</Text>
        <Progress percent={45} aria-label="进行中的任务" />
      </Flex>
      <Flex direction="column" gap="sm">
        <Text tone="muted">已完成</Text>
        <Progress percent={100} aria-label="已完成的任务" />
      </Flex>
      <Flex direction="column" gap="sm">
        <Text tone="muted">失败</Text>
        <Progress percent={70} status="error" aria-label="失败的任务" />
      </Flex>
    </Space>
  );
}
```

展开代码

### 不确定进度

无法计算总进度时使用 `indeterminate`，此时不显示或提供数值百分比。


indeterminate.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/indeterminate.tsx"
import { Progress } from '@ifhover/leaf-ui';

export function ProgressIndeterminate() {
  return <Progress indeterminate aria-label="正在处理文件" />;
}
```

展开代码

### 圆形进度

通过 `type="circle"` 展示圆形进度，`percent` 表示完成比例。


45%

circles.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/circles.tsx"
import { Progress } from '@ifhover/leaf-ui';

export function ProgressCircles() {
  return <Progress type="circle" percent={45} aria-label="上传进度" />;
}
```

展开代码

[](#)
### 更新进度

进度由应用更新，组件不会自行推进。设置 `active={false}` 可关闭线形进度的流光。


45%

减少增加

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/controlled.tsx"
import { Button, Flex, Progress, Space } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ProgressControlled() {
  const [percent, setPercent] = useState(45);

  return (
    <Space direction="vertical" align="stretch">
      <Progress percent={percent} aria-label="上传进度" />
      <Flex gap="md" align="center" wrap>
        <Button
          variant="outline"
          disabled={percent === 0}
          onClick={() => setPercent((current) => Math.max(0, current - 10))}
        >
          减少
        </Button>
        <Button
          disabled={percent === 100}
          onClick={() => setPercent((current) => Math.min(100, current + 10))}
        >
          增加
        </Button>
      </Flex>
    </Space>
  );
}
```

展开代码

### 分步进度

通过 `steps` 将进度划分为固定数量的步骤，`percent` 仍使用完成百分比。


60%

steps.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/steps.tsx"
import { Progress } from '@ifhover/leaf-ui';

export function ProgressSteps() {
  return <Progress percent={60} steps={10} aria-label="检查进度" />;
}
```

展开代码

### 分段进度

`segments` 的百分比以完整进度条为基准；同时将 `percent` 设置为各段完成量的总和，用于总体读数。


75%

segments.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/segments.tsx"
import { Progress } from '@ifhover/leaf-ui';

export function ProgressSegments() {
  return (
    <Progress
      percent={75}
      aria-label="文件处理进度"
      segments={[
        { key: 'processed', percent: 35, color: '#1e964f' },
        { key: 'uploaded', percent: 40, color: '#1d9bf0' },
      ]}
    />
  );
}
```

展开代码

### 仪表盘

为圆形进度设置 `dashboard`，以仪表盘形式展示完成比例。


65%

dashboard.tsx

复制代码

```tsx lineNumbers file="../../src/examples/progress/dashboard.tsx"
import { Progress } from '@ifhover/leaf-ui';

export function ProgressDashboard() {
  return <Progress type="circle" dashboard percent={65} aria-label="容量使用率" />;
}
```

展开代码


## API

### Progress API

配置进度比例、状态和显示形式。

| 属性               | 类型                                                   | 默认值        | 说明                                          |
| ---------------- | ---------------------------------------------------- | ---------- | ------------------------------------------- |
| `percent`        | `number`                                             | `0`        | 完成百分比，范围 0–100                              |
| `type`           | `'line' \| 'circle'`                                 | `'line'`   | 直线或圆形进度                                     |
| `status`         | `'normal' \| 'success' \| 'error'`                   | `'normal'` | 进度状态；非不确定进度达到 100% 时，normal 自动显示为 success。  |
| `showInfo`       | `boolean`                                            | `true`     | 展示百分比或状态图标                                  |
| `format`         | `(percent: number) => ReactNode`                     | —          | 自定义进度文字                                     |
| `strokeWidth`    | `number`                                             | —          | 进度线宽；直线为像素，圆形为视图单位                          |
| `color`          | `string`                                             | —          | 自定义进度颜色                                     |
| `size`           | `number`                                             | `100`      | 圆形宽高，单位像素                                   |
| `indeterminate`  | `boolean`                                            | `false`    | 总进度未知时展示加载动画，不显示百分比                         |
| `active`         | `boolean`                                            | `false`    | 未完成的线形进度是否显示流光；设为 true 开启，完成、错误或不确定进度时自动停止。 |
| `trailColor`     | `string`                                             | —          | 底轨颜色                                        |
| `segments`       | `readonly `[`ProgressSegment`](#progresssegment)`[]` | —          | 按比例和颜色显示多个分段。                               |
| `steps`          | `number`                                             | —          | 离散的进度段数。                                    |
| `dashboard`      | `boolean`                                            | `false`    | 显示仪表盘式进度。                                   |
| `successPercent` | `number`                                             | —          | 已经成功完成的进度部分。                                |

### ProgressSegment

描述一段进度的比例与颜色。

| 属性        | 类型       | 默认值 | 说明        |
| --------- | -------- | --- | --------- |
| `key`     | `string` | —   | 稳定且唯一的标识。 |
| `percent` | `number` | 必填  | 完成百分比。    |
| `color`   | `string` | —   | 颜色或语义色。   |
