引入

import { ProgressCircle } from '@heroui/react';

用法

import {ProgressCircle} from "@heroui/react";

export function Basic() {
  return (
    <ProgressCircle aria-label="加载中" value={60}>

组件结构

import { ProgressCircle } from '@heroui/react';

export default () => (
  <ProgressCircle aria-label="Loading" value={60}>
    <ProgressCircle.Track>
      <ProgressCircle.TrackCircle />
      <ProgressCircle.FillCircle />
    </ProgressCircle.Track>
  </ProgressCircle>
);

尺寸

import {ProgressCircle} from "@heroui/react";

const SIZE_LABELS = {
  lg: "大",
  md: "中",

颜色

import {ProgressCircle} from "@heroui/react";

const colors = ["default", "accent", "success", "warning", "danger"] as const;

const COLOR_LABELS: Record<(typeof colors)[number], string> = {

不确定进度

在无法确定具体进度时，使用 isIndeterminate。

import {ProgressCircle} from "@heroui/react";

export function Indeterminate() {
  return (
    <ProgressCircle isIndeterminate aria-label="加载中">

带标签

已完成 75%

import {Label, ProgressCircle} from "@heroui/react";

export function WithLabel() {
  return (
    <div className="flex items-center gap-3">

自定义 SVG 属性

由于每个部分都是可组合组件，你可以直接覆盖 strokeWidth、r、cx、cy、viewBox 等 SVG 属性。

import {ProgressCircle} from "@heroui/react";

export function CustomSvg() {
  return (
    <div className="flex items-end gap-6">

样式

传入 Tailwind CSS 类

你可以分别自定义 ProgressCircle 的各个部分：

import { ProgressCircle } from '@heroui/react';

function CustomProgressCircle() {
  return (
    <ProgressCircle aria-label="Loading" value={60}>
      <ProgressCircle.Track>
        <ProgressCircle.TrackCircle />
        <ProgressCircle.FillCircle className="stroke-purple-500" />
      </ProgressCircle.Track>
    </ProgressCircle>
  );
}

自定义组件类

若要自定义 ProgressCircle 组件类，可以使用 @layer components 指令。
了解更多.

@layer components {
  .progress-circle {
    @apply inline-flex;
  }

  .progress-circle__track {
    @apply size-12;
  }

  .progress-circle__fill-circle {
    stroke: purple;
  }
}

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

ProgressCircle 组件使用以下 CSS 类（查看源码样式）：

基础与元素类

.progress-circle - 基础容器
.progress-circle__track - SVG 元素
.progress-circle__track-circle - 背景圆环
.progress-circle__fill-circle - 进度弧

尺寸类

.progress-circle--sm - 小尺寸
.progress-circle--md - 中等尺寸（默认）
.progress-circle--lg - 大尺寸

颜色类

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

API 参考

ProgressCircle Props

继承自 React Aria ProgressBar。

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'}`	数值展示格式
`children`	`ReactNode \| (values: ProgressBarRenderProps) => ReactNode`	-	内容或渲染 prop

ProgressBarRenderProps

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

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

ProgressCircle 环形进度条

引入

用法