CircularProgress

CircularProgress 从 HeroUI v2 到 v3（现在称为 ProgressCircle）的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 ProgressCircle 文档。本指南只关注从 HeroUI v2 的迁移。

正在寻找 Progress（线性）的迁移说明？请参阅 Progress 迁移指南。

组件重命名

CircularProgress 在 v3 中已重命名为 ProgressCircle。

结构变化

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

1import { CircularProgress } from "@lenso/ui";2
3export default function App() {4  return (5    <CircularProgress label="Loading..." value={60} />6  );7}

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

1import { ProgressCircle } from "@lenso/ui";2
3export default function App() {4  return (5    <ProgressCircle aria-label="Loading" value={60}>6      <ProgressCircle.Track>7        <ProgressCircle.TrackCircle />8        <ProgressCircle.FillCircle />9      </ProgressCircle.Track>10    </ProgressCircle>11  );12}

主要变化

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`

迁移示例

基本环形进度

1import { CircularProgress } from "@lenso/ui";2
3<CircularProgress aria-label="Loading..." value={60} />

不确定状态

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

带标签

1<CircularProgress2  label="Loading..."3  value={70}4  showValueLabel5  size="lg"6/>

自定义 SVG prop

1<CircularProgress2  value={60}3  strokeWidth={6}4  aria-label="Loading"5/>

样式变更

v2：`classNames` prop

1<CircularProgress2  classNames={{3    base: "custom-base",4    svg: "custom-svg",5    track: "custom-track",6    indicator: "custom-fill",7    label: "custom-label",8    value: "custom-value",9  }}10/>

v3：直接使用 `className` prop

1<ProgressCircle className="custom-base" value={60}>2  <ProgressCircle.Track className="custom-svg">3    <ProgressCircle.TrackCircle className="custom-track" />4    <ProgressCircle.FillCircle className="custom-fill" />5  </ProgressCircle.Track>6</ProgressCircle>

组件结构

1ProgressCircle (Root)2  └── ProgressCircle.Track (SVG element)3      ├── ProgressCircle.TrackCircle (background circle)4      └── 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