YprogressBar 是一款基於 HTML5、極輕量的進度條 jQuery 插件,設計靈感源自經典解壓軟體介面,內建數字顯示並支援動態參數插值(如上傳速度、剩餘時間),適合檔案上傳、資料匯入、長時間運算等場景。本文將完整介紹安裝、配置、API 使用與進階技巧。
yprogressbar.css 與 yprogressbar.js{{y:paramName}} 語法,動態更新細節資訊destroy() 皆觸發 cancelCallbackdestroy() 可徹底釋放資源<link rel="stylesheet" href="yprogressbar.css">
<script src="jquery.min.js"></script>
<script src="yprogressbar.js"></script>
const ypb = new YprogressBar({
title: '正在上傳檔案...',
des: '上傳速度:{{y:speed}} MB/s 剩餘時間:約 {{y:second}} 秒',
closeable: true,
cancelCallback: (rate, vars) => {
console.log(`使用者取消,進度 ${rate}%` , vars);
}
});
ypb.show(); // 必須呼叫 show() 才會顯示
// 模擬上傳過程
let progress = 0;
const timer = setInterval(() => {
progress += Math.random() * 10;
if (progress >= 100) {
progress = 100;
clearInterval(timer);
ypb.destroy(); // 完成後銷毀
}
// 第二個參數為物件,對應 des 模板中的變數
ypb.update(Math.floor(progress), {
speed: (Math.random() * 5 + 1).toFixed(2),
second: Math.ceil((100 - progress) / 10)
});
}, 500);
| 方法 / 參數 | 說明 | 必要性 |
|---|---|---|
| title | 進度條標題文字 | 選填 |
| des | 描述文字,支援 {{y:key}} 佔位符 | 選填 |
| closeable | 是否顯示關閉按鈕(預設 false) | 選填 |
| cancelCallback(rate, vars) | 關閉/銷毀時回呼,rate 為當前進度,vars 為參數物件 | 選填 |
| show() | 顯示進度條 | 必呼叫 |
| update(rate, varsObj) | 更新進度(0-100)與動態參數 | 視需求 |
| destroy() | 銷毀進度條、移除 DOM、解除事件、釋放記憶體 | 建議呼叫 |
若需在進行中變更描述格式,可直接修改實例屬性後再 update:
ypb.options.des = '處理中:{{y:current}} / {{y:total}}';
ypb.update(50, { current: 500, total: 1000 });
$.ajax({
url: '/api/upload',
xhr: () => {
const xhr = new window.XMLHttpRequest();
xhr.upload.addEventListener('progress', e => {
if (e.lengthComputable) {
const pct = Math.round((e.loaded / e.total) * 100);
const speed = (e.loaded / 1024 / ((Date.now() - start) / 1000)).toFixed(2);
ypb.update(pct, { speed, second: Math.ceil((e.total - e.loaded) / 1024 / speed) });
}
});
return xhr;
},
// ... 其他設定
});
show(),且 jQuery 版本 ≥ 1.7。update 第二參數鍵名必須與 des 中 {{y:key}} 完全一致(區分大小寫)。YprogressBar 以極小的體積提供了專業級的進度回饋體驗,動態參數插值與完整的生命週期回呼,讓前端開發者能快速整合上傳、匯入、批次處理等長耗時操作的視覺化回饋。下載原始碼請參考 GitHub 專案頁。