---
title: ProgressBar 进度条
description: 进度条用于展示某项操作随时间变化的确定或不确定进度。
links:
  rac: ProgressBar
  source: progress-bar/progress-bar.tsx
  styles: progress-bar.css
  storybook: Components/Feedback/ProgressBar
---

## 用法

```tsx
import { ProgressBar, Label } from '@heroui/react';
```

<ComponentPreview
  name="progress-bar-basic"
/>

## 组件结构

```tsx
import { ProgressBar, Label } from '@heroui/react';

export default () => (
  <ProgressBar value={60}>
    <Label>Loading</Label>
    <ProgressBar.Output />
    <ProgressBar.Track>
      <ProgressBar.Fill />
    </ProgressBar.Track>
  </ProgressBar>
);
```

## 示例

### 尺寸

<ComponentPreview
  name="progress-bar-sizes"
/>

### 颜色

<ComponentPreview
  name="progress-bar-colors"
/>

### 无可见标签

无需可见标签时，使用 `aria-label` 提供无障碍标签。

<ComponentPreview
  name="progress-bar-without-label"
/>

### 不确定进度

无法确定进度时使用 `isIndeterminate`。

<ComponentPreview
  name="progress-bar-indeterminate"
/>

### 自定义数值范围

使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与显示格式。

<ComponentPreview
  name="progress-bar-custom-value"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="progress-bar-custom-styles" />

### 全局 CSS

若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .progress-bar {
    @apply w-full gap-2;
  }

  .progress-bar__track {
    @apply h-3 rounded-full;
  }

  .progress-bar__fill {
    @apply rounded-full;
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

ProgressBar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-bar.css)）：

#### 基础与元素类 [!toc]

- `.progress-bar` - 基础容器（网格布局）
- `.progress-bar__output` - 数值文本展示
- `.progress-bar__track` - 轨道背景
- `.progress-bar__fill` - 轨道上已填充部分

#### 尺寸类 [!toc]

- `.progress-bar--sm` - 小尺寸变体（更细的轨道）
- `.progress-bar--md` - 中等尺寸变体（默认）
- `.progress-bar--lg` - 大尺寸变体（更粗的轨道）

#### 颜色类 [!toc]

- `.progress-bar--default` - 默认颜色变体
- `.progress-bar--accent` - 强调色变体
- `.progress-bar--success` - 成功色变体
- `.progress-bar--warning` - 警告色变体
- `.progress-bar--danger` - 危险色变体

## API 参考

### ProgressBar
继承自 [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)。

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `value` | `number` | `0` | 当前值 |
| `minValue` | `number` | `0` | 最小值 |
| `maxValue` | `number` | `100` | 最大值 |
| `isIndeterminate` | `boolean` | `false` | 是否为不确定进度 |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 进度轨道尺寸 |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | 填充条颜色 |
| `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | 数值展示的数字格式 |
| `valueLabel` | `ReactNode` | - | 自定义数值标签内容 |
| `children` | `ReactNode \| (values: ProgressBarRenderProps) => ReactNode` | - | 内容或渲染 prop |

### ProgressBarRenderProps

使用渲染 prop 模式时，会提供以下值：

| Prop | 类型 | 描述 |
|------|------|------|
| `percentage` | `number` | 进度百分比（0–100） |
| `valueText` | `string` | 格式化后的数值文本 |
| `isIndeterminate` | `boolean` | 是否为不确定进度 |

## 相关组件

<RelatedComponents component="progress-bar" />