環形進度條

圓形進度條元件展示了流程的持續時間或不確定的等待時間。

簡介

環形進度指示器，通常稱為旋轉器，是操作或任務進度的視覺化呈現。

圓形進度條元件預設為不確定模式，表示未定義的等待時間。使用確定模式來指示給定操作將花費多長時間。

基本

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

圓形進度條元件為使用者提供正在進行的程序狀態更新，例如載入應用程式、提交表單或儲存更新。

客製化

變體

圓形進度條元件支援 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 開始編輯

尺寸

圓形進度條提供三種尺寸：sm、md（預設）和 lg。

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

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

按下 Enter 開始編輯

顏色

主題中包含的每個調色盤都可透過 color 屬性使用。

變體

SolidSoftOutlinedPlain

粗細

您可以使用 thickness 屬性來控制圓圈的筆劃寬度。

確定

determinate 屬性可讓您指示指定的等待時間。

<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 開始編輯

子節點

預設情況下，巢狀在圓形進度條內的任何子節點都將置中。

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 開始編輯

與按鈕一起使用

圓形進度條元件可以用作裝飾器，以顯示按鈕上的載入狀態。

除非在進度條上明確指定 size 屬性，否則圓形進度條的尺寸由按鈕、圖示按鈕或連結控制。

<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 變數 Playground

試用元件上所有可用的 CSS 變數，以查看設計如何變化。您可以使用這些變數透過 sx 屬性和主題來自訂元件。

<CircularProgress />

CSS 變數

--CircularProgress-size

僅支援 `px` 單位

--CircularProgress-trackThickness

--CircularProgress-progressThickness

無障礙設計

在預設情況下，只有在值不是不確定時，aria-valuenow 屬性才會指示進度列的目前值。此屬性會將值顯示為百分比。

以下是一些確保您的圓形進度條元件具有無障礙功能的訣竅

建立圓形進度條元件時，請確保它與背景之間有足夠的色彩對比，使用至少 WCAG 2.0 的色彩對比度 4.5:1。
若要為 aria-valuenow 定義人類可讀的文字替代方案，aria-valuetext 將以更使用者友善的方式顯示目前值。例如，下載檔案可以表示為 aria-valuetext="剩餘 8% (34 分鐘)。
aria-valuemin 和 aria-valuemax 屬性通常用於指示範圍的最小值和最大值。預設情況下，這些屬性分別設定為 0 和 100。如果您需要為範圍設定不同的最小值或最大值，可以使用這些屬性來執行此操作。
使用 aria-label 或 aria-labelledby 屬性為您的進度條元件提供無障礙名稱。這些屬性定義字串值或識別標記進度條元件的元素。

結構

圓形進度條元件由單個根 <span> 和一個 <svg> 元件組成，該元件包裹著兩個 <circle>。

<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

請參閱以下文件，以取得此處提及之元件的所有屬性和類別的完整參考。

<CircularProgress />