unnamed-ui
基础

Progress

进度条组件，用于展示操作进度，支持线性和圆形两种样式

线性进度条

30%

圆形进度条

30%
"use client";

import { Progress } from "@/components/composed/progress/progress";

export function ProgressDemo() {
  return (
    <div className="space-y-6 w-full">
      <div className="space-y-2">
        <h3 className="text-sm font-medium text-[var(--Text-text-primary)]">
          线性进度条
        </h3>
        <Progress percent={30} />
        <Progress percent={50} status="success" />
        <Progress percent={70} status="exception" />
        <Progress percent={100} />
      </div>

      <div className="space-y-2">
        <h3 className="text-sm font-medium text-[var(--Text-text-primary)]">
          圆形进度条
        </h3>
        <div className="flex gap-4 flex-wrap">
          <Progress type="circle" percent={30} />
          <Progress type="circle" percent={50} status="success" />
          <Progress type="circle" percent={70} status="exception" />
          <Progress type="circle" percent={100} />
        </div>
      </div>
    </div>
  );
}

Progress 进度条组件用于展示操作的当前进度，支持线性和圆形两种样式，适用于文件上传、任务处理、数据加载等场景。

概述

  • 多种类型：支持线性（line）和圆形（circle）两种进度条类型
  • 状态展示：支持正常、成功、异常三种状态
  • 自定义样式：支持自定义颜色、渐变色、线宽等
  • 步进模式：线性进度条支持步进显示
  • 灵活配置：支持自定义文字格式、位置等
  • 类型安全：完整的 TypeScript 类型定义

快速开始

import { Progress } from "@/registry/wuhan/composed/progress/progress";

export function Example() {
  return (
    <div className="space-y-4">
      {/* 线性进度条 */}
      <Progress percent={50} />
      
      {/* 圆形进度条 */}
      <Progress type="circle" percent={75} />
    </div>
  );
}

特性

  • 线性进度条：适合展示水平进度，支持步进、渐变等高级特性
  • 圆形进度条：适合展示百分比进度，节省空间
  • 状态管理：自动根据状态显示不同颜色
  • 自定义格式：支持自定义进度文字的格式和内容
  • 响应式：自适应容器宽度

安装

pnpm dlx shadcn@latest add "http://localhost:3000/r/wuhan/progress.json"

代码演示

基础用法

最基础的线性进度条。

30%
"use client";

import { Progress } from "@/components/composed/progress/progress";

export function ProgressDefault() {
  return (
    <div className="space-y-6 w-full">
      <Progress percent={30} />
    </div>
  );
}

综合演示

展示线性和圆形进度条的不同状态。

线性进度条

30%

圆形进度条

30%
"use client";

import { Progress } from "@/components/composed/progress/progress";

export function ProgressDemo() {
  return (
    <div className="space-y-6 w-full">
      <div className="space-y-2">
        <h3 className="text-sm font-medium text-[var(--Text-text-primary)]">
          线性进度条
        </h3>
        <Progress percent={30} />
        <Progress percent={50} status="success" />
        <Progress percent={70} status="exception" />
        <Progress percent={100} />
      </div>

      <div className="space-y-2">
        <h3 className="text-sm font-medium text-[var(--Text-text-primary)]">
          圆形进度条
        </h3>
        <div className="flex gap-4 flex-wrap">
          <Progress type="circle" percent={30} />
          <Progress type="circle" percent={50} status="success" />
          <Progress type="circle" percent={70} status="exception" />
          <Progress type="circle" percent={100} />
        </div>
      </div>
    </div>
  );
}

线性进度条

线性进度条的各种配置。

基础线性进度条

30%

不同状态

30%

自定义颜色

50%
70%

渐变色

60%

隐藏进度文字

自定义宽度

50%
50%
50%
"use client";

import { Progress } from "@/components/composed/progress/progress";

export function ProgressLineDemo() {
  return (
    <div className="space-y-6 w-full">
      <div>
        <h3 className="mb-3 text-sm font-medium">基础线性进度条</h3>
        <Progress percent={30} />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同状态</h3>
        <div className="space-y-3">
          <Progress percent={30} status="normal" />
          <Progress percent={50} status="success" />
          <Progress percent={70} status="exception" />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义颜色</h3>
        <div className="space-y-3">
          <Progress percent={50} strokeColor="#52c41a" />
          <Progress percent={70} strokeColor="#1890ff" />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">渐变色</h3>
        <Progress
          percent={60}
          strokeColor={{ from: "#108ee9", to: "#87d068" }}
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">隐藏进度文字</h3>
        <Progress percent={50} showInfo={false} />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义宽度</h3>
        <div className="space-y-3">
          <Progress percent={50} strokeWidth={4} />
          <Progress percent={50} strokeWidth={12} />
          <Progress percent={50} strokeWidth={20} />
        </div>
      </div>
    </div>
  );
}

圆形进度条

圆形进度条的各种配置。

基础圆形进度条

75%

不同状态

30%

自定义颜色

75%
75%
75%

渐变色

90%

不同尺寸

75%
75%
75%

自定义线宽

75%
75%
75%

隐藏进度文字

"use client";

import { Progress } from "@/components/composed/progress/progress";

export function ProgressCircleDemo() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="mb-3 text-sm font-medium">基础圆形进度条</h3>
        <Progress type="circle" percent={75} />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同状态</h3>
        <div className="flex gap-4 flex-wrap">
          <Progress type="circle" percent={30} status="normal" />
          <Progress type="circle" percent={50} status="success" />
          <Progress type="circle" percent={70} status="exception" />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义颜色</h3>
        <div className="flex gap-4 flex-wrap">
          <Progress type="circle" percent={75} strokeColor="#52c41a" />
          <Progress type="circle" percent={75} strokeColor="#1890ff" />
          <Progress type="circle" percent={75} strokeColor="#eb2f96" />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">渐变色</h3>
        <Progress
          type="circle"
          percent={90}
          strokeColor={{
            "0%": "#108ee9",
            "100%": "#87d068",
          }}
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同尺寸</h3>
        <div className="flex gap-4 items-center flex-wrap">
          <Progress type="circle" percent={75} width={80} />
          <Progress type="circle" percent={75} width={120} />
          <Progress type="circle" percent={75} width={160} />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义线宽</h3>
        <div className="flex gap-4 flex-wrap">
          <Progress type="circle" percent={75} strokeWidth={4} />
          <Progress type="circle" percent={75} strokeWidth={8} />
          <Progress type="circle" percent={75} strokeWidth={12} />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">隐藏进度文字</h3>
        <Progress type="circle" percent={75} showInfo={false} />
      </div>
    </div>
  );
}

步进进度条

线性进度条的步进模式。

步进进度条

50%

不同步数

60%
60%
60%

彩色步进

60%
"use client";

import { Progress } from "@/components/composed/progress/progress";

export function ProgressStepsDemo() {
  return (
    <div className="space-y-6 w-full">
      <div>
        <h3 className="mb-3 text-sm font-medium">步进进度条</h3>
        <Progress percent={50} steps={5} />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同步数</h3>
        <div className="space-y-3">
          <Progress percent={60} steps={3} />
          <Progress percent={60} steps={5} />
          <Progress percent={60} steps={10} />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">彩色步进</h3>
        <Progress
          percent={60}
          steps={5}
          strokeColor={["#1890ff", "#52c41a", "#faad14", "#f5222d", "#722ed1"]}
        />
      </div>
    </div>
  );
}

自定义格式

自定义进度文字的格式。

自定义文字格式

75 Days

自定义内容

70% 已完成

圆形进度条自定义格式

75天
"use client";

import { Progress } from "@/components/composed/progress/progress";

export function ProgressFormatDemo() {
  return (
    <div className="space-y-6 w-full">
      <div>
        <h3 className="mb-3 text-sm font-medium">自定义文字格式</h3>
        <Progress percent={75} format={(percent) => `${percent} Days`} />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义内容</h3>
        <div className="space-y-3">
          <Progress percent={100} format={() => "Done"} status="success" />
          <Progress percent={70} format={(percent) => `${percent}% 已完成`} />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">圆形进度条自定义格式</h3>
        <div className="flex gap-4 flex-wrap">
          <Progress
            type="circle"
            percent={75}
            format={(percent) => `${percent}天`}
          />
          <Progress
            type="circle"
            percent={100}
            format={() => "✓"}
            status="success"
          />
        </div>
      </div>
    </div>
  );
}

动态进度

动态改变进度的示例。

动态进度条

0%

动态圆形进度条

0%
"use client";

import { useState } from "react";
import { Progress } from "@/components/composed/progress/progress";
import { Button } from "@/components/composed/block-button/block-button";

export function ProgressDynamicDemo() {
  const [percent, setPercent] = useState(0);

  const increase = () => {
    setPercent((prev) => Math.min(prev + 10, 100));
  };

  const decrease = () => {
    setPercent((prev) => Math.max(prev - 10, 0));
  };

  return (
    <div className="space-y-6 w-full">
      <div>
        <h3 className="mb-3 text-sm font-medium">动态进度条</h3>
        <div className="space-y-4">
          <Progress percent={percent} />
          <div className="flex gap-2">
            <Button onClick={decrease}>减少</Button>
            <Button onClick={increase}>增加</Button>
          </div>
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">动态圆形进度条</h3>
        <div className="space-y-4">
          <Progress type="circle" percent={percent} />
          <div className="flex gap-2">
            <Button onClick={decrease}>减少</Button>
            <Button onClick={increase}>增加</Button>
          </div>
        </div>
      </div>
    </div>
  );
}

API

Progress

进度条组件，通过 type 属性区分线性和圆形两种类型。

通用属性

属性说明类型默认值
type进度条类型"line" | "circle""line"
percent进度百分比 (0-100)number0
status状态"normal" | "success" | "exception""normal"
showInfo是否显示进度文字booleantrue
format自定义文字格式(percent?: number) => ReactNode(percent) => percent + "%"
className自定义类名string-

type="line"

线性进度条特有属性。

属性说明类型默认值
strokeColor进度条的色彩，传入 object 时为渐变。当有 steps 时支持传入一个数组string | string[] | { from: string; to: string; direction?: string }-
trailColor轨道颜色string"var(--Container-bg-container-placeholder)"
strokeWidth进度条线的宽度，单位 pxnumber8
steps进度条总共步数number-
percentPosition进度数值位置，align 表示数值的水平位置，type 表示数值在进度条内部还是外部{ align: "start" | "center" | "end"; type: "inner" | "outer" }{ align: "end", type: "outer" }

type="circle"

圆形进度条特有属性。

属性说明类型默认值
strokeColor圆形进度条线的色彩，传入 object 时为渐变string | { [key: string]: string }-
trailColor轨道颜色string"var(--Container-bg-neutral-light)"
strokeWidth圆形进度条线的宽度，单位是进度条画布宽度的百分比number6
width圆形进度条的画布宽度，单位 pxnumber120

ProgressStatus

状态类型定义。

type ProgressStatus = "normal" | "success" | "exception";

状态对应颜色

StatusColor
normalvar(--Text-text-brand)
successvar(--Text-text-success)
exceptionvar(--Text-text-error)

使用场景

1. 文件上传

<Progress 
  percent={uploadProgress} 
  format={(percent) => `已上传 ${percent}%`}
/>

2. 任务处理

<Progress 
  type="circle" 
  percent={taskProgress}
  status={taskProgress === 100 ? "success" : "normal"}
/>

3. 数据加载

<Progress 
  percent={loadProgress}
  strokeColor={{ from: "#108ee9", to: "#87d068" }}
/>

4. 步骤进度

<Progress 
  percent={currentStep / totalSteps * 100}
  steps={totalSteps}
/>

最佳实践

  1. 类型选择：

    • 使用线性进度条展示长时间任务或多步骤流程
    • 使用圆形进度条展示百分比或节省空间的场景

  2. 状态管理：

    • 在 100% 时使用 success 状态
    • 在出错时使用 exception 状态
    • 进行中使用 normal 状态

  3. 颜色使用：

    • 保持与设计系统的颜色一致性
    • 渐变色适合展示连续变化的进度
    • 多色步进适合展示不同阶段

  4. 文字格式：

    • 默认显示百分比
    • 根据场景自定义格式（如：已完成 50/100）
    • 重要信息可以完全自定义内容

注意事项

  • percent 值会自动限制在 0-100 范围内
  • 圆形进度条的 strokeWidth 是相对于 width 的百分比
  • 线性进度条的 strokeWidth 是绝对像素值
  • 步进模式下，每个步骤的激活状态基于当前进度
  • 渐变色在步进模式下仅对线性进度条有效

原语组件

Progress 组件基于以下原语组件构建：

  • ProgressLinePrimitive - 线性进度条原语
  • ProgressCirclePrimitive - 圆形进度条原语

原语组件提供了基础的样式和结构，可以在需要更灵活的定制时直接使用。

扩展示例

带标签的进度条

<div className="space-y-2">
  <div className="flex justify-between">
    <span className="text-sm text-[var(--Text-text-secondary)]">上传进度</span>
    <span className="text-sm text-[var(--Text-text-primary)]">75%</span>
  </div>
  <Progress percent={75} showInfo={false} />
</div>

多色步进进度条

<Progress 
  percent={60} 
  steps={5}
  strokeColor={[
    "#1890ff",
    "#52c41a",
    "#faad14",
    "#f5222d",
    "#722ed1"
  ]}
/>

仪表盘风格

<Progress 
  type="circle"
  percent={75}
  width={200}
  strokeWidth={8}
  strokeColor={{
    "0%": "#108ee9",
    "100%": "#87d068",
  }}
  format={(percent) => (
    <div className="text-center">
      <div className="text-2xl font-bold">{percent}%</div>
      <div className="text-sm text-[var(--Text-text-secondary)]">完成度</div>
    </div>
  )}
/>

Status Tag

Status tag component for displaying various status indicators

Tooltip

Tooltip component for displaying contextual information on hover or focus

On this page

概述快速开始特性安装代码演示基础用法综合演示线性进度条圆形进度条步进进度条自定义格式动态进度APIProgress通用属性type="line"type="circle"ProgressStatus状态对应颜色使用场景1. 文件上传2. 任务处理3. 数据加载4. 步骤进度最佳实践注意事项原语组件扩展示例带标签的进度条多色步进进度条仪表盘风格