Progress.js 核心用法指南：start/set/increase/end 四大方法一次快速掌握

Progress.js 核心用法指南：start/set/increase/end 四大方法一次快速掌握

【免费下载链接】progress.jsProgressJs is a JavaScript and CSS3 library which help developers to create and manage progress bar for every objects on the page.项目地址: https://gitcode.com/gh_mirrors/pr/progress.js

🎯Progress.js是一款轻量级的 JavaScript + CSS3 进度条库，帮你在网页上任意元素中创建并管理进度条。本文带你 5 分钟吃透 Progress.js 的 4 个核心方法——start/set/increase/end，从零上手到灵活进阶，让加载动画轻松可控。

一、Progress.js 是什么？为什么值得用？

Progress.js 的核心定位就一句话：为页面上的每个对象创建和自定义 HTML5 进度条。

它的几个亮点非常适合新手：

• 🪶零依赖：纯 JavaScript + CSS3，不需要 jQuery
• 🎨可换主题：内置blue、blueOverlay、blackRadiusInputs等多种主题
• 📍任意挂载：可以贴在body（整页顶部细条），也可以贴在任意指定元素上
• ⚙️完整生命周期：start创建 →set/increase推进 →end优雅收尾

库的主文件位于 src/progress.js，样式与主题在 src/progressjs.css，生产环境可直接引用压缩版 minified/progress.min.js 和 minified/progressjs.min.css。

二、快速安装：2 分钟引入 Progress.js 进度条库

使用 Progress.js 只需要两步：

第 1 步：在 HTML 中引入 JS 和 CSS（生产环境建议用压缩版）：

<link rel="stylesheet" href="progressjs.css"> <script src="progress.js"></script>

第 2 步：在页面中执行一行代码即可启动进度条：

// 为整个页面添加进度条 progressJs().start(); // 或者只针对某个指定元素 progressJs("#targetElement").start();

💡 小技巧：如果本地开发想自己构建压缩文件，项目自带 Makefile，运行make build即可自动压缩静态资源。

三、start 方法：创建进度条的第一步

start()是整个流程的起点，它做三件事：

1. 在页面底部自动创建.progressjs-container容器
2. 把进度条定位到你的目标元素（整页则为顶部固定细条）
3. 初始进度设为 1%

相关实现见 src/progress.js。

var bar = progressJs("#download-box").start();

之后所有方法都可以通过bar这个实例直接链式调用。

四、set 方法：把进度条精准设置到指定百分比

set(percent)用于直接指定当前进度，适合后端明确返回百分比的场景（比如文件下载 62%）：

bar.set(45); // 进度条平滑过渡到 45%

几个细节值得注意：

• ✅ 内部会自动把超过 100 的值钳制为 100，不会溢出
• ✅ 百分比数字会逐帧动画滚动到新值，视觉更自然（见 src/progress.js 中的动画逻辑）
• ✅ 可低于当前值，实现"回退"效果

五、increase 方法：进度条逐步递增的利器

很多任务并不知道总时长，这时increase(size)更实用——在当前基础上加一点：

bar.increase(5); // 进度 +5%

🚀 进阶玩法：autoIncrease(size, millisecond)可以让进度条自动匀速增长，特别适合上传、加载这类耗时不定的场景：

// 每 500 毫秒自动 +2%，模拟"忙碌中"的进度 bar.autoIncrease(2, 500);

任务完成后调用end()时，定时器会被自动清理，不会泄漏内存。

六、end 方法：优雅收尾并移除进度条

end()负责善后：先把进度补齐到 100%，播放淡出动画，然后移除进度条元素并清理目标元素上的标记属性。

bar.end(); // 补满 → 淡出 → 自动销毁

🔍 对比另一个方法kill()：它不补满、直接移除，适合中途取消、失败中断的场景。两者区别见 src/progress.js。

七、进阶技巧：主题换肤与生命周期回调

🎨 换肤：通过setOption('theme', '主题名')在start()之前即可换肤。可用主题均可在 src/progressjs.css 中查到，例如：

progressJs("#myCard") .setOption('theme', 'blueOverlayRadius') // 圆角遮罩样式 .setOption('overlayMode', true) // 开启遮罩模式 .start();

📣 回调：Progress.js 提供三个钩子函数（定义于 src/progress.js）：

bar.onprogress(function(el, percent) { console.log("当前进度：" + percent + "%"); });

八、常见问题速查 📌

Q1：进度条为什么显示在页面顶部而不是我的元素上？不传参数时默认作用于body；请传入选择器如progressJs("#id")，并确保选择器能选中到元素，否则会抛出错误提示。

Q2：同一个元素能重复 start 吗？不能。Progress.js 会用data-progressjs属性做标记，已初始化的元素会直接跳过。想重新开始，先kill()或end()等待其销毁。

Q3：进度超过 100% 会怎样？自动被限制为 100%，你可以放心累加，不会溢出屏幕。

Q4：如何取消正在进行的 autoIncrease？调用end()或kill()即可，内部定时器会被一并清除。

写在最后

Progress.js 用极简的 API 覆盖了进度条的完整生命周期：start()建条 →set()/increase()推进 →end()收尾。掌握这 4 个方法，你就拥有了网页加载动画的全部控制权 🎉

📚 延伸阅读：README.md · 开源协议见 LICENSE

【免费下载链接】progress.jsProgressJs is a JavaScript and CSS3 library which help developers to create and manage progress bar for every objects on the page.项目地址: https://gitcode.com/gh_mirrors/pr/progress.js