简介这是一份 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 的完整选项表插件对外暴露的参数不算多但每个都直接影响实际效果。下面是这份资源里核心配置项的作用说明参数名类型默认值作用说明valuenumber0当前进度值取值建议在 0 到 max 之间maxnumber100进度最大值用于换算百分比animatedbooleanfalse更新进度时是否启用平滑过渡动画stripedbooleanfalse是否在进度条上叠加斜向条纹textModebooleantrue是否在进度条右侧显示百分比文字onStartfunctionnull进度值从无到有开始变化时触发onChangefunctionnull每次进度更新后触发参数为当前百分比onCompletefunctionnull进度到达 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 传了总字节数 1024value 却传了已完成的百分比 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 langzh-CN head meta charsetUTF-8 titleprogressbar 最小示例/title link relstylesheet hrefprogressbar.css style #demoBar { width: 400px; margin: 40px auto; } /style /head body div iddemoBar/div script srcjquery-3.6.0.min.js/script script srcjquery.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 classtask-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 后重新 setValueonStart 能再次正常触发在动态插入的 DOM 上初始化进度条能正常渲染这份资源跑起来之后改造空间其实比想象中大。最初我在一个数据导入页面里接它时也曾经被progressbar is not a function这种低级顺序问题卡了整晚从那以后我每次引入任何 jQuery 插件都会强制先检查 script 加载顺序与版本冲突再开始写业务逻辑。这套验证习惯沿用到现在基本没有在插件接入环节翻过车。希望帮到你。本文还有配套的精品资源点击获取