Circular Progress

Circular Progress 组件展示了一个进程的持续时间或不确定的等待时间。

介绍

圆形进度指示器，通常被称为 spinner，是操作或任务进度的可视化表示。

Circular Progress 组件默认为 indeterminate 状态，表示不确定的等待时长。使用 determinate 模式来指示给定操作需要多长时间。

基础

import CircularProgress from '@mui/joy/CircularProgress';

Circular Progress 组件为用户提供正在进行中的进程状态更新，例如加载应用、提交表单或保存更新。

自定义

变体

Circular Progress 组件支持 Joy UI 的四种全局变体：solid (默认), soft, outlined, 和 plain。

<CircularProgress variant="solid" />
<CircularProgress variant="soft" />
<CircularProgress variant="outlined" />
<CircularProgress variant="plain" />

<CircularProgress variant="solid" />
<CircularProgress variant="soft" />
<CircularProgress variant="outlined" />
<CircularProgress variant="plain" />

按 Enter 键开始编辑

尺寸

Circular Progress 组件提供三种尺寸：sm、md (默认) 和 lg。

<CircularProgress size="sm" />
<CircularProgress size="md" />
<CircularProgress size="lg" />

<CircularProgress size="sm" />
<CircularProgress size="md" />
<CircularProgress size="lg" />

按 Enter 键开始编辑

颜色

主题中包含的每个调色板都可以通过 color prop 使用。

Variant

SolidSoftOutlinedPlain

厚度

你可以使用 thickness prop 来控制圆的描边宽度。

Determinate

determinate prop 允许你指示指定的等待时间。

<CircularProgress determinate value={25} />
<CircularProgress determinate value={50} />
<CircularProgress determinate value={75} />
<CircularProgress determinate value={100} />
<CircularProgress determinate value={progress} />

<CircularProgress determinate value={25} />
<CircularProgress determinate value={50} />
<CircularProgress determinate value={75} />
<CircularProgress determinate value={100} />
<CircularProgress determinate value={progress} />

按 Enter 键开始编辑

子元素

默认情况下，嵌套在 Circular Progress 组件内的任何子元素都将居中。

2 / 3

<CircularProgress color="warning">
  <WarningIcon color="warning" />
</CircularProgress>
<CircularProgress size="lg" determinate value={66.67}>
  2 / 3
</CircularProgress>
<CircularProgress color="danger" sx={{ '--CircularProgress-size': '80px' }}>
  <ReportIcon color="danger" />
</CircularProgress>

<CircularProgress color="warning">
  <WarningIcon color="warning" />
</CircularProgress>
<CircularProgress size="lg" determinate value={66.67}>
  2 / 3
</CircularProgress>
<CircularProgress color="danger" sx={{ '--CircularProgress-size': '80px' }}>
  <ReportIcon color="danger" />
</CircularProgress>

按 Enter 键开始编辑

使用按钮

Circular Progress 组件可以用作装饰器，以在按钮上显示加载状态。

Circular Progress 组件的尺寸由按钮、图标按钮或链接控制，除非在 progress 组件上显式指定 size prop。

<Button startDecorator={<CircularProgress variant="solid" />}>Loading…</Button>
<IconButton>
  <CircularProgress />
</IconButton>
{/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
<Link
  component="button"
  variant="plain"
  startDecorator={<CircularProgress />}
  sx={{ p: 1 }}
>
  Submitting...
</Link>

<Button startDecorator={<CircularProgress variant="solid" />}>Loading…</Button>
<IconButton>
  <CircularProgress />
</IconButton>
{/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
<Link
  component="button"
  variant="plain"
  startDecorator={<CircularProgress />}
  sx={{ p: 1 }}
>
  Submitting...
</Link>

按 Enter 键开始编辑

第三方集成

use-count-up

使用 use-count-up 包中的 useCountUp hook，通过提供 start、end 和 duration 值来创建计数动画。

CSS 变量演示场

试用组件上所有可用的 CSS 变量，看看设计如何变化。你可以使用这些变量通过 sx prop 和主题来自定义组件。

<CircularProgress />

CSS 变量

--CircularProgress-size

仅支持 px 单位

--CircularProgress-trackThickness

--CircularProgress-progressThickness

可访问性

开箱即用，aria-valuenow 属性仅在值不是 indeterminate 时指示进度条的当前值。此属性将以百分比形式显示该值。

这里有一些技巧，以确保你拥有一个可访问的圆形进度条组件

在创建圆形进度条组件时，请确保组件与其背景之间有足够的颜色对比度，使用至少 WCAG 2.0 的颜色对比度比率 4.5:1。
为了定义 aria-valuenow 的人类可读文本替代方案，aria-valuetext 将以更用户友好的方式显示当前值。例如，下载文件可以表示为 aria-valuetext="剩余 8% (34 分钟)"。
aria-valuemin 和 aria-valuemax 属性通常用于指示范围的最小值和最大值。默认情况下，这些属性分别设置为 0 和 100。如果需要为你的范围设置不同的最小值或最大值，可以使用这些属性来实现。
使用 aria-label 或 aria-labelledby 属性为你的进度组件提供一个可访问的名称。这些属性定义字符串值或标识标记进度组件的元素。

结构

Circular Progress 组件由一个根 <span> 元素和一个包裹两个 <circle> 元素的 <svg> 组件组成。

<span role="progressbar" class="MuiCircularProgress-root">
  <svg class="MuiCircularProgress-svg">
    <circle class="MuiCircularProgress-track"></circle>
    <circle class="MuiCircularProgress-progress"></circle>
  </svg>
  <!-- children are nested here when present -->
</span>

API

请参阅下面的文档，以获得此处提及的组件可用的所有 props 和 classes 的完整参考。

<CircularProgress />