组件重命名

CircularProgress 在 v3 中已重命名为 ProgressCircle。

结构变化

在 v2 中，CircularProgress 是单个组件，通过 prop 进行配置：

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

export default function App() {
  return (
    <CircularProgress label="Loading..." value={60} />
  );
}

在 v3 中，ProgressCircle 改为复合组件模式：

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

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

主要变化

1. 组件结构

v2： 单一 CircularProgress 组件，SVG 在内部渲染
v3： 复合组件：ProgressCircle、ProgressCircle.Track（SVG 元素）、ProgressCircle.TrackCircle（背景圆环）、ProgressCircle.FillCircle（进度弧）

2. 颜色

v2： default、primary、secondary、success、warning、danger
v3： default、accent、success、warning、danger

3. Prop 变更

v2 prop	v3 对应项	说明
`value`	`value`	相同
`minValue`	`minValue`	相同
`maxValue`	`maxValue`	相同
`isIndeterminate`	`isIndeterminate`	默认值变化：v2 为 `true`，v3 为 `false`
`formatOptions`	`formatOptions`	相同
`size`	`size`	相同（`sm`、`md`、`lg`）
`color`	`color`	`primary` → `accent`，`secondary` 已移除
`label`	-	改用 `Label` 组件
`valueLabel`	-	改用 render prop 模式
`showValueLabel`	-	将值的内容直接放入 `ProgressCircle` 中
`strokeWidth`	-	直接设置在 `ProgressCircle.TrackCircle` 与 `ProgressCircle.FillCircle` 上
`isDisabled`	-	已移除
`disableAnimation`	-	已移除
`classNames`	-	改在各复合子组件上使用 `className`

迁移示例

基本环形进度

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

<CircularProgress aria-label="Loading..." value={60} />

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

<ProgressCircle aria-label="Loading..." value={60}>
  <ProgressCircle.Track>
    <ProgressCircle.TrackCircle />
    <ProgressCircle.FillCircle />
  </ProgressCircle.Track>
</ProgressCircle>

不确定状态

<CircularProgress aria-label="Loading..." />
{/* isIndeterminate defaults to true in v2 */}

<ProgressCircle isIndeterminate aria-label="Loading...">
  <ProgressCircle.Track>
    <ProgressCircle.TrackCircle />
    <ProgressCircle.FillCircle />
  </ProgressCircle.Track>
</ProgressCircle>
{/* isIndeterminate defaults to false in v3, must be explicit */}

带标签

<CircularProgress
  label="Loading..."
  value={70}
  showValueLabel
  size="lg"
/>

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

<div className="flex flex-col items-center gap-2">
  <ProgressCircle aria-label="Loading" value={70} size="lg">
    <ProgressCircle.Track>
      <ProgressCircle.TrackCircle />
      <ProgressCircle.FillCircle />
    </ProgressCircle.Track>
  </ProgressCircle>
  <Label>Loading...</Label>
</div>

自定义 SVG prop

<CircularProgress
  value={60}
  strokeWidth={6}
  aria-label="Loading"
/>

<ProgressCircle aria-label="Loading" value={60}>
  <ProgressCircle.Track>
    <ProgressCircle.TrackCircle strokeWidth={6} />
    <ProgressCircle.FillCircle strokeWidth={6} />
  </ProgressCircle.Track>
</ProgressCircle>

样式变更

v2：`classNames` prop

<CircularProgress
  classNames={{
    base: "custom-base",
    svg: "custom-svg",
    track: "custom-track",
    indicator: "custom-fill",
    label: "custom-label",
    value: "custom-value",
  }}
/>

v3：直接使用 `className` prop

<ProgressCircle className="custom-base" value={60}>
  <ProgressCircle.Track className="custom-svg">
    <ProgressCircle.TrackCircle className="custom-track" />
    <ProgressCircle.FillCircle className="custom-fill" />
  </ProgressCircle.Track>
</ProgressCircle>

组件结构

ProgressCircle (Root)
  └── ProgressCircle.Track (SVG element)
      ├── ProgressCircle.TrackCircle (background circle)
      └── ProgressCircle.FillCircle (progress arc)

总结

重命名：CircularProgress → ProgressCircle
组件结构：单组件 → 复合组件（ProgressCircle.Track、ProgressCircle.TrackCircle、ProgressCircle.FillCircle）
不确定状态默认值变化：isIndeterminate 在 v3 中默认为 false（v2 中为 true）
标签：label prop → Label 组件
SVG prop：原本在根上的 strokeWidth → 直接设置在 TrackCircle 与 FillCircle 上
颜色变化：primary → accent，secondary 已移除
移除的 prop：isDisabled、disableAnimation → 请改用 Tailwind CSS
移除 classNames：改在各复合子组件上使用 className

CircularProgress

本页目录