简介：这是一份 jQuery progressbar 插件的可用示例资源，面向需要为文件上传、后台处理或页面加载流程补充实时进度反馈的前端开发者。压缩包内共 9 个文件，以 HTML 演示页面、jQuery 脚本、PNG/GIF 效果截图以及 txt/url 说明文档为主，整体仅 34KB；其中 HTML 页面可直接查看运行效果，JS 脚本承载插件调用逻辑，图片与说明文档辅助理解实现细节，结构精简、易于移植。目前已有 405 人学习/下载。资源集中演示了 progressbar 的初始化、value 方法实时刷新进度、百分比数据同步显示以及 animate 动画和自定义外观设置，并给出异步任务回调中更新进度的典型写法，覆盖从页面元素搭建、样式调整到事件联动的完整链路。示例页面可直接在浏览器打开查看效果，配套脚本稍作调整即可接入实际业务，适合初中级前端开发者参考，也可作为封装统一进度组件的起点。
1. jQuery progressbar 进度条插件：让"卡了多久、还剩多少"不再靠猜
运行一个花了三分钟还没走完的进度条，用户侧的第一反应不是耐心等待，而是怀疑页面卡死了。这个项目选了个很小很专的切入点：用 jQuery 封装一个 progressbar 插件，把进度百分比以数字形式直接渲染在进度条上，让"进行到哪一步、还剩多少"一眼可见。它插拔轻量、不依赖任何 UI 框架，适合后台管理系统里的上传、导入、批量任务这类低频但必须给用户反馈的场景。需要手动管理进度、又不想引入重型组件库的前端开发者，从这个插件起步是最省事的。项目中所有的样式、逻辑和示例都集中在几个文件里，读代码不需要先搭一套工程化环境，浏览器打开 demo 就能跑。下面按"结构—实现—坑—接入—改造"的顺序把它拆开。
2. 项目拆解：目录结构、配置参数与插件生命周期
2.1 文件构成与依赖环境
这种插件类资源，文件组织方式通常非常固定，拿到手基本是下面这个结构：
jquery-progressbar/ ├── jquery.progressbar.js # 插件主逻辑 ├── progressbar.css # 基础样式与主题类 ├── demo.html # 可直接打开的运行示例 └── README.md # 参数说明与快速开始主文件jquery.progressbar.js内部按"默认参数 → 构造函数 → 原型方法 → jQuery 插件注册"四段组织，这个顺序几乎成了 jQuery 插件的事实标准。progressbar.css负责两条核心视觉规则：轨道背景色和进度条填充宽度，以及可选的条纹、动画过渡效果，类名统一以progressbar-开头，避免和业务样式冲突。
依赖方面，整个插件只依赖 jQuery 核心库，不挂 Bootstrap、不引字体图标。代码里用到的 API 全部是$.fn.extend、$.extend、$.data、$.each这类从 1.7 到 3.x 都稳定的方法，所以老项目也不存在升级兼容问题。我一般建议用 jQuery 1.12.x 以上的版本，配合noConflict方式引入，避免和其他全局变量打架。
2.2 参数配置：从 value 到 onComplete 的完整选项表
插件对外暴露的参数不算多，但每个都直接影响实际效果。下面是这份资源里核心配置项的作用说明：
| 参数名 | 类型 | 默认值 | 作用说明 |
|---|---|---|---|
| value | number | 0 | 当前进度值，取值建议在 0 到 max 之间 |
| max | number | 100 | 进度最大值，用于换算百分比 |
| animated | boolean | false | 更新进度时是否启用平滑过渡动画 |
| striped | boolean | false | 是否在进度条上叠加斜向条纹 |
| textMode | boolean | true | 是否在进度条右侧显示百分比文字 |
| onStart | function | null | 进度值从无到有开始变化时触发 |
| onChange | function | null | 每次进度更新后触发，参数为当前百分比 |
| onComplete | function | null | 进度到达 100% 时触发一次 |
max这个参数容易被忽略。很多初次使用的开发者只关心 value，遇到"上传 5 个文件，整体进度到第 3 个"这种场景，直接传 3 当进度，结果进度条只走了一点点。正确做法是把max设为总文件数，value 传已完成数，百分比由插件内部换算，这样外部业务代码只需要维护"完成了几件事"这个计数。
textMode控制百分比数字的显隐，改成false之后只保留填充条，适合空间局促的表格行。format参数在部分影印版本里会暴露出来，用来定制文本内容，比如显示"3/10"而不是"30%"，这个在改造章节单独讲。
2.3 生命周期：从初始化到状态更新的完整路径
这个插件的生命周期非常简单，只有两个阶段：初始化阶段和更新阶段。初始化阶段，插件在目标元素上构建 DOM 骨架，给容器加progressbar类，内部追加两个子元素：填充条progressbar-bar和文本标签progressbar-label，然后读入 value 渲染第一帧。更新阶段，外部任意时刻调用方法修改进度值，插件重算宽度和文本。
生命周期里有一个值得注意的细节：插件实例被缓存在元素自身的data对象里，键名是progressbar。这意味着重复调用$el.progressbar()不会重复创建实例，而是复用首次创建的实例，只有参数为字符串时才走方法调用分支。这种"惰性单例"模式带来的好处是，页面里多个模块同时对同一个进度条赋值，不会出现互相覆盖实例的情况。没有内置 destroy 方法，需要清理时常见做法是手动移除缓存：$el.removeData('progressbar')，同时把内部生成的 DOM 一并清掉。
3. 核心实现精读：进度值如何变成宽度和百分比数字
3.1 插件骨架：jQuery 原型封装与单例缓存
这个插件的骨架遵循了 jQuery 插件开发的标准形态，先看整体代码结构：
(function ($) { 'use strict'; // 默认配置 var defaults = { value: 0, max: 100, animated: false, striped: false, textMode: true, onStart: null, onChange: null, onComplete: null }; // 构造函数 function Progressbar(element, options) { this.$element = $(element); this.options = $.extend({}, defaults, options); this._lastPercent = undefined; this._init(); } Progressbar.prototype._init = function () { // 构建 DOM、绑定初始进度 }; // jQuery 插件注册入口 $.fn.progressbar = function (options) { return this.each(function () { var $this = $(this); var instance = $this.data('progressbar'); if (!instance) { instance = new Progressbar(this, typeof options === 'object' ? options : {}); $this.data('progressbar', instance); } if (typeof options === 'string') { instance[options].apply(instance, Array.prototype.slice.call(arguments, 1)); } }); }; })(jQuery);逻辑说明：defaults是插件私有的默认配置，外面的调用方可以通过改默认值的方式全局调整行为。构造函数Progressbar接收两个参数，element是原生 DOM 节点，options是调用方传入的配置，二者通过$.extend合并，实现"默认配置被调用配置覆盖"。_lastPercent这个私有变量用来记录上一次的百分比，后面判断"是否开始""是否完成"都用它作为参照。
参数说明：$.fn.progressbar是整个插件的对外入口，返回this.each(...)保证链式调用正常。第一次初始化时把实例写进data('progressbar')，后续再调用同一个方法名时不再重建。这里有个常见误用：想用$('#bar').progressbar({ value: 50 })更新进度，写出来却发现不生效，原因就在这个缓存分支——实例已经存在，对象参数不会触发 setValue。更新进度必须写成字符串方法调用：$('#bar').progressbar('setValue', 50)。
3.2 进度更新链路：setValue 如何把数字变成像素宽度
setValue是插件最核心的方法，它负责把外部传入的数值，经过边界处理、百分比换算，最终作用到 DOM 的宽度属性和文本节点上。实现如下：
Progressbar.prototype.setValue = function (value) { var self = this; var opts = this.options; // 1. 数值清洗 value = parseFloat(value); if (isNaN(value)) { value = 0; } if (value < 0) { value = 0; } if (value > opts.max) { value = opts.max; } // 2. 换算百分比并取整 var percent = Math.round((value / opts.max) * 100); // 3. 触发 onStart：仅在首次有值时触发一次 if (self._lastPercent === undefined && percent > 0) { if (typeof opts.onStart === 'function') { opts.onStart.call(this, percent); } } // 4. 根据 animated 选择更新方式 if (opts.animated) { this.$bar.stop(true, true).animate({ width: percent + '%' }, 300, 'swing', function () { self._updateText(percent); self._fireChange(percent); }); } else { this.$bar.css('width', percent + '%'); this._updateText(percent); this._fireChange(percent); } };逻辑说明：第一步的parseFloat是为了兼容后端返回字符串的情况，比如"42"这种类型。但parseFloat遇到"abc"会得到NaN，所以紧接着必须用isNaN兜底，否则后面value / opts.max会一路传递NaN，最终渲染出NaN%的文本。第二步的percent是给用户看的百分比数字，用Math.round取整，避免出现 33.333333% 这种不美观的文本。
参数说明：stop(true, true)两个参数分别表示清除动画队列和直接跳到最终状态。连续快速调用 setValue 时，如果不清队列，动画会一帧一帧排队执行，进度条慢慢蹭到目标位置，视觉上非常拖沓，而且旧的回调会在新动画后继续触发，导致 onChange 乱序。设了animated: true后，300 毫秒的过渡时间配合swing缓动函数，视觉上最自然。如果追求极致的实时反馈，比如文件上传场景，建议animated: false，直接无动画更新宽度，避免进度数字和填充宽度之间出现明显的滞后。
3.3 文本渲染与回调触发：onChange 和 onComplete 的发射时机
_updateText和_fireChange是内部辅助方法，一个管文本、一个管回调：
Progressbar.prototype._updateText = function (percent) { if (!this.options.textMode) { this.$label.hide(); return; } this.$label.show(); var text = percent + '%'; if (typeof this.options.format === 'function') { text = this.options.format.call(this, percent); } this.$label.text(text); }; Progressbar.prototype._fireChange = function (percent) { if (typeof this.options.onChange === 'function') { this.options.onChange.call(this, percent); } if (percent >= 100 && self._lastPercent !== undefined && self._lastPercent < 100) { if (typeof this.options.onComplete === 'function') { this.options.onComplete.call(this, percent); } } this._lastPercent = percent; };逻辑说明：_updateText先判断textMode，关闭时直接隐藏文本节点，而不是把文本置空，这样布局不会跳动。format回调允许外部完全接管文本内容，插件只负责把百分比数字传进去，返回什么就显示什么。_fireChange里对onComplete的判断是重点是用了_lastPercent < 100这个条件，保证 100% 只在跨过边界的那一刻触发一次，而不是每次 setValue(100) 都重复触发。
参数说明：call(this, percent)把回调函数的 this 指向插件实例，回调里可以通过this.$element拿到原始的 jQuery 对象，做加类名、变色等样式操作，不需要再在外部重新查询 DOM。这里也埋了一个常见问题的根因：如果_lastPercent初始值不设成undefined，而在构造函数里设成 0，那么第一次 setValue(0) 也会被判定为"变化"，onStart 和 onChange 的行为就会和预期不一致。
4. 避坑指南：进度条插件最常见的五类运行问题排查
4.1 报错progressbar is not a function
现象：打开页面控制台抛 TypeError，浏览器认为$el.progressbar不是一个函数，进度条完全没渲染。
原因：多数情况是 jQuery 和插件文件的加载顺序反了，或者 jQuery 被二次加载覆盖。插件挂在$.fn上，如果执行$.fn.progressbar注册时全局$已经被后加载的另一个 jQuery 替换，注册方法就丢了。
解决：打开 Network 面板确认脚本加载顺序，jQuery 必须在jquery.progressbar.js之前引入。如果页面里确实存在多个 jQuery 版本，用jQuery.noConflict(true)声明主版本，插件文件内的$会正确引用已加载的 jQuery。排查脚本顺序是最快的确认手段，这属于典型的踩坑点，顺序对了基本就解决。
4.2 进度条显示NaN%或undefined%
现象：进度条能渲染，但文本区域显示的是 NaN%，或者直接冒出一行 undefined。
原因：setValue 被传入了无法解析的字符串，常见来源是后端接口返回的字段名打错了，或者从>function normalizePercent(value) { var num = parseFloat(value); return isNaN(num) ? 0 : num; }
后端返回的数据建议在原项目里也做一版类型约束，进度字段统一返回数字类型。这个问题的根子往往不在插件，而在数据链路，排查时先把接口返回的原样打印出来看一眼。
4.3 进度条填充宽度溢出容器
现象：进度条到达 100% 时，填充条超出容器边界，甚至撑破外层布局，滚动条都冒出来了。
原因：一种是 max 和 value 的单位不一致，比如 max 传了总字节数 1024，value 却传了已完成的百分比 80，导致换算结果远大于 100；另一种是对容器用了padding，而child的宽度用百分比时把 padding 也算进去了，box-sizing 默认是content-box。
解决：插件内部的边界钳制只会把 value 限制到max，但 max 本身如果设错了，算法是无能为力的。检查 max 是否与业务单位一致。布局层面给轨道容器加上box-sizing: border-box; overflow: hidden;，填充条宽度永远不会溢出。这是 CSS 层面最省事的后悔药，两条规则就能根治。
4.4 动态新增的元素上调用插件不生效
现象：页面初始化时进度条都正常，通过 JS 动态插入的新行里，$('.task-progress').progressbar(...)完全没有反应，或者控制台不报错但元素是裸的。
原因：$.fn.progressbar内部是this.each，只会处理当前已经存在于 DOM 里的节点。动态插入的节点是在初始化之后才出现的，如果直接对全量选择器调用，只会重复初始化旧节点，新节点被漏掉。
解决：动态插入 DOM 之后，单独对新增节点调用一次初始化。常见做法是把初始化封装成函数，在插入完成后调用：
function bindProgressbar($container) { $container.find('.task-progress').progressbar({ value: $container.data('progress') }); } // 动态添加行之后，只初始化新行 var $newRow = renderRow(taskData); $('#taskTable').append($newRow); bindProgressbar($newRow);如果新插入的节点带><!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>progressbar 最小示例</title> <link rel="stylesheet" href="progressbar.css"> <style> #demoBar { width: 400px; margin: 40px auto; } </style> </head> <body> <div id="demoBar"></div> <script src="jquery-3.6.0.min.js"></script> <script src="jquery.progressbar.js"></script> <script> $('#demoBar').progressbar({ value: 30, max: 100, textMode: true, onChange: function (percent) { console.log('当前进度：' + percent + '%'); } }); // 每 800ms 前进 10%，模拟一个任务在推进 var current = 30; var timer = setInterval(function () { if (current >= 100) { clearInterval(timer); return; } current += 10; $('#demoBar').progressbar('setValue', current); }, 800); </script> </body> </html>
逻辑说明：这段示例先用对象参数完成初始化，把初始进度定位到 30%，然后用setInterval模拟真实任务推进，每 0.8 秒通过字符串方法调用setValue更新一次。onChange回调里打印当前百分比，打开控制台就能看到进度值的变化曲线，验证插件回调是否按预期触发。
参数说明：setInterval里的current += 10是模拟值，真实场景中应该被替换成从业务逻辑拿到的实际进度。初始 30% 的设置是为了演示"页面打开时已经有一定进度"的场景，实际项目中如果任务是刚启动的，初始 value 传 0 即可。
5.2 对接文件上传接口的真实进度场景
进度条最常见的应用场景之一是文件上传。基于XMLHttpRequest的上传进度事件，可以拿到真实的已上传字节数和总字节数，这里用 jQuery 的$.ajax配置来对接：
var formData = new FormData(); formData.append('file', fileInput.files[0]); $.ajax({ url: '/api/upload', type: 'POST', data: formData, processData: false, contentType: false, xhr: function () { var xhr = new XMLHttpRequest(); // 监听上传进度事件 xhr.upload.addEventListener('progress', function (e) { if (e.lengthComputable) { var percent = Math.round((e.loaded / e.total) * 100); $('#uploadBar').progressbar('setValue', percent); } }); return xhr; }, success: function (resp) { // 上传完成，进度条强制置为 100% $('#uploadBar').progressbar('setValue', 100); }, error: function () { // 失败时回退到 0，并给出错误提示 $('#uploadBar').progressbar('setValue', 0); alert('上传失败，请重试'); } });逻辑说明：xhr.upload.addEventListener('progress', ...)是浏览器原生能力，事件对象e.loaded表示已上传字节数，e.total表示总字节数，两者相除再乘 100 就是当前真实进度。lengthComputable为false时无法计算进度，此时应该忽略更新，保持上一次的值。成功回调里强制 setValue(100) 是双保险，保证进度条一定以满格收尾。
参数说明：processData: false和contentType: false是 jQuery 上传 FormData 时的必备配置，否则 jQuery 会把 FormData 转成字符串导致上传失败。progress事件的触发频率由浏览器控制，一般在几十到几百毫秒一次，配合animated: false让宽度直接跳变，视觉上就是流畅地爬升。
5.3 表格批量初始化：一次处理多个进度实例
后台管理里常见一整张任务表，每一行都有一个进度条。逐行初始化不需要循环嵌套，关键是利用each和><table class="task-table"> <tr>$('.task-table tr').each(function () { var $row = $(this); var progress = parseInt($row.data('progress') || '0', 10); $row.find('.task-progress').progressbar({ value: progress, max: 100, animated: true, onComplete: function () { // 进度满格后标记整行 $row.addClass('task-done'); } }); });
逻辑说明：>// 扩展 reset：回到起点并清理完成状态 $.fn.progressbar.Constructor.prototype.reset = function () { this._lastPercent = undefined; this.setValue(0); return this; }; // 扩展 getPercent：读取当前百分比，方便统计或日志 $.fn.progressbar.Constructor.prototype.getPercent = function () { var value = this.options.value || 0; return Math.round((value / this.options.max) * 100); }; $('#bar').progressbar('reset'); var p = $('#bar').progressbar('getPercent');
逻辑说明：reset把_lastPercent重置为undefined，这样下一次setValue会被当作首次更新，onStart 能正常触发；setValue(0)负责把 UI 带回零位。getPercent通过this.options.value读取当前内部值，换算成整数百分比返回，修改后记得在setValue方法里同步更新this.options.value = value，否则 getPercent 读到的永远是初始值。
6.2 主题定制与文案格式化
想让进度条适配不同业务场景，不需要改动插件源码，初始化时传format和自定义 CSS 就够了：
$('#scoreBar').progressbar({ value: 3, max: 10, format: function (percent) { return '已完成 ' + this.options.value + ' / ' + this.options.max; }, onChange: function (percent) { // 进度超过 80% 时换主题色 this.$element.toggleClass('progressbar-danger', percent > 80); } });.progressbar { height: 18px; background: #eee; border-radius: 4px; overflow: hidden; } .progressbar-bar { height: 100%; width: 0; background: #337ab7; transition: width 0.2s ease; } .progressbar-danger .progressbar-bar { background: #d9534f; }逻辑说明：format回调里的this指向插件实例，所以能通过this.options.value拿到未换算的原始进度值，渲染出"已完成 3 / 10"这种更业务化的文案。onChange里用this.$element.toggleClass动态切换主题类，配合 CSS 的.progressbar-danger覆盖背景色，就实现了"任务进度越快、颜色越危险"的警戒效果。整个过程没有改动插件一行核心代码，全部通过回调与样式类完成。
6.3 改造后的验证清单
每次对插件做二次开发后，我会按这个清单走一遍，确认没有把原来的行为改坏：
- 初始化后进度条正确渲染出初始百分比，文本与宽度一致
- setValue 传 0、100、负数、非字符串四类值，界面均无异常
- 连续快速 setValue 后，最终宽度与最后一次调用一致
- onComplete 只在进度首次到达 100% 时触发一次
- reset 后重新 setValue，onStart 能再次正常触发
- 在动态插入的 DOM 上初始化，进度条能正常渲染
这份资源跑起来之后，改造空间其实比想象中大。最初我在一个数据导入页面里接它时，也曾经被progressbar is not a function这种低级顺序问题卡了整晚，从那以后我每次引入任何 jQuery 插件都会强制先检查 script 加载顺序与版本冲突，再开始写业务逻辑。这套验证习惯沿用到现在，基本没有在插件接入环节翻过车。希望帮到你。
本文还有配套的精品资源，点击获取
