狀態與回饋系統
彈簧進度條
以彈簧補間的線性進度條：百分比數字逐位滾動，支援不確定進度掃光與緩衝層，達成 100% 時脈衝一次並顯示勾。
一條會「彈」的線性進度條。進度變化時指示條以 spring 補間到新位置，右側百分比逐位滾動；不知道總量時切到不確定模式，一段 40% 寬的光條在軌道上來回掃動；影片或串流情境可以加上同色淺一階的緩衝層。進度由未滿變為滿的那一刻，整條軌道脈衝一次、右側文字交叉淡接成勾，並呼叫 onComplete。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add progress-barPlayground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
42
120
編輯中的呼叫預設屬性
<ProgressBar/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add https://webberui.com/r/progress-bar.json或在 components.json 設定 registries 後，改用 @webberui/progress-bar 安裝。
使用
import { ProgressBar } from "@/components/ui/progress-bar";
<ProgressBar
value={uploaded}
max={total}
label="設計稿-v3.fig"
showLabel
onComplete={() => console.log("上傳完成")}
/>
{/* 不確定進度 */}
<ProgressBar indeterminate label="備份封存.zip" />
{/* 影片播放＋緩衝 */}
<ProgressBar value={played} buffer={buffered} size="sm" />Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
value | number | null | 0 | 目前進度（0..max，超出會 clamp）；傳 null 視為不確定進度 |
max | number | 100 | 進度上限 |
indeterminate | boolean | false | 不確定進度模式：顯示來回掃光，並省略 aria-valuenow |
buffer | number | — | 緩衝進度（0..max），以同色 40% 不透明的第二層條呈現 |
showLabel | boolean | false | 是否在軌道右側顯示百分比 |
label | ReactNode | — | 左上角的標籤文字（例如檔名），同時作為 progressbar 的可及名稱 |
formatLabel | (percent: number) => string | — | 自訂百分比文字；提供時改以純文字顯示，不做逐位滾動 |
size | "sm" | "md" | "lg" | "md" | 軌道高度：sm 4px、md 8px、lg 12px |
color | string | — | 指示條顏色；未提供時使用 --wb-progress-bar-color（再退回 neutral 色階） |
stiffness | number | 120 | 寬度與數字補間的 spring 剛性 |
damping | number | 20 | 寬度與數字補間的 spring 阻尼 |
showComplete | boolean | true | 達成 100% 時是否脈衝一次並把右側文字換成勾 |
onComplete | () => void | — | 進度由未滿變為滿時呼叫（降回後再滿可再次觸發） |
className | string | — | 透傳到最外層容器 |
細節
- 指示條用
scaleX（transform-origin: left）而不是width做動畫，補間過程不會觸發版面重排。 - 數字滾動：百分比的每一位是一個高 1em、
overflow: hidden的欄，內放 0–9 直列，以 spring 的y移到目標位；位數增減（9% → 10%、99% → 100%）時新位淡入，tabular-nums讓寬度不跳動。 - 不確定模式的光條寬 40%，以 1.4 秒 easeInOut 在軌道上來回掃動。
- 完成脈衝只在「未滿 → 滿」時觸發一次；初次掛載就是滿的不會脈衝，降回後再滿則會再次觸發。
- 顏色：設定全域 CSS 變數
--wb-progress-bar-color即可統一換色，colorprop 會覆寫它；緩衝層的過渡長度讀取根元素上的--wb-progress-bar-duration（預設 300ms）。
可及性
- 根元素為
role="progressbar"，帶aria-valuemin、aria-valuemax、aria-valuenow與aria-valuetext（例如「已完成 42%」）；不確定模式省略aria-valuenow，aria-valuetext改為「處理中」並設定aria-busy - 有
label時以aria-labelledby指向標籤；沒有時退回aria-label="進度" - 逐位滾動的數字與勾號對輔助科技隱藏，朗讀內容以
aria-valuetext為準 - 使用者系統開啟「減少動態效果」時：指示條直接到位不做 spring、數字直接替換、不確定模式改為靜態 40% 條緩慢明暗呼吸並顯示「處理中」文字、完成時不脈衝只顯示勾