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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/progress.md.

Progress 进度条

展示任务的完成程度。

基础用法

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

45%
basic.tsx
import { Progress } from '@ifhover/leaf-ui';

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

示例

进度状态

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

进行中
45%
已完成
失败
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
import { Progress } from '@ifhover/leaf-ui';

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

圆形进度

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

45%
circles.tsx
import { Progress } from '@ifhover/leaf-ui';

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

更新进度

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

45%
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
import { Progress } from '@ifhover/leaf-ui';

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

分段进度

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

75%
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
import { Progress } from '@ifhover/leaf-ui';

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

API

Progress API

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

属性类型默认值说明
percentnumber0完成百分比,范围 0–100
type'line' | 'circle''line'直线或圆形进度
status'normal' | 'success' | 'error''normal'进度状态;非不确定进度达到 100% 时,normal 自动显示为 success。
showInfobooleantrue展示百分比或状态图标
format(percent: number) => ReactNode—自定义进度文字
strokeWidthnumber—进度线宽;直线为像素,圆形为视图单位
colorstring—自定义进度颜色
sizenumber100圆形宽高,单位像素
indeterminatebooleanfalse总进度未知时展示加载动画,不显示百分比
activebooleanfalse未完成的线形进度是否显示流光;设为 true 开启,完成、错误或不确定进度时自动停止。
trailColorstring—底轨颜色
segmentsreadonly ProgressSegment[]—按比例和颜色显示多个分段。
stepsnumber—离散的进度段数。
dashboardbooleanfalse显示仪表盘式进度。
successPercentnumber—已经成功完成的进度部分。

ProgressSegment

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

属性类型默认值说明
keystring—稳定且唯一的标识。
percentnumber必填完成百分比。
colorstring—颜色或语义色。