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

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

# Progress 进度条

展示任务的完成程度。

## 交互进度


45%

减少增加

basic.tsx

复制代码

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

import { useState } from 'react';

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

展开代码

## 进度状态


静态进度

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>静态进度</Text>
        <Progress percent={45} active={false} />
      </Flex>
      <Flex direction="column" gap="sm">
        <Text>任务失败</Text>
        <Progress percent={70} status="error" />
      </Flex>
      <Flex direction="column" gap="sm">
        <Text>任务完成</Text>
        <Progress percent={100} />
      </Flex>
      <Flex direction="column" gap="sm">
        <Text>进度暂时无法估计</Text>
        <Progress indeterminate />
      </Flex>
    </Space>
  );
}
```

展开代码

## 圆形进度


进行中

45%

已完成

失败

circles.tsx

复制代码

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

export function ProgressCircles() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>进行中</Text>
        <Progress percent={45} type="circle" size={80} />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>已完成</Text>
        <Progress percent={100} type="circle" size={80} />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>失败</Text>
        <Progress percent={60} type="circle" status="error" size={80} />
      </Flex>
    </Flex>
  );
}
```

展开代码

## 分段与仪表盘


分段任务

75%

分步进度

60%

仪表盘

65%

capabilities.tsx

复制代码

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

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm" align="center">
        <Text>{'分段任务'}</Text>
        <Progress
          percent={75}
          segments={[
            { key: 'a', percent: 35, color: '#20834a' },
            { key: 'b', percent: 40, color: '#1677ff' },
          ]}
        />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        <Text>{'分步进度'}</Text>
        <Progress percent={60} steps={10} />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        <Text>{'仪表盘'}</Text>
        <Progress type="circle" dashboard percent={65} successPercent={30} />
      </Flex>
    </Space>
  );
}
```

展开代码

未完成的线形进度默认在已填充部分展示流光。设置 `active={false}` 可展示静态进度；完成、错误、不确定进度和分步进度不展示流光。动效遵循系统与 ConfigProvider 的偏好。

## Progress API

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

## 类型

定义组件属性或组装列表时可导入相关类型。

```ts
import type { ProgressProps } from '@ifhover/leaf-ui';
```

## 使用说明

达到 100% 时自动使用成功状态。aria-label 可描述具体任务，如“上传进度”；进度本身也会提供给辅助技术。

## ProgressSegment

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