前端UI组件【免费下载链接】nprogressFor slim progress bars like on YouTube, Medium, etc项目地址https://gitcode.com/gh_mirrors/np/nprogress点击查看免费下载NProgress 是一个只有约 1KB 的极简进度条库专为 Ajax 型应用设计灵感来自 Google、YouTube 与 Medium 的顶部加载条。本文以仓库 Readme.md 为核心骨架结合 nprogress.js、nprogress.css 与 test/test.js 的源码细节系统讲解从安装引入、基础调用、Turbolinks/Pjax 集成到进阶 API、八项配置项与样式自定义的完整实战方案并深入剖析其“涓流递增trickle”动画的底层实现原理。读完本文你将能独立在任何前端项目中接入、定制并理解 NProgress 的完整工作机制。NProgress 是什么NProgress 是一个极简minimalist的进度条库官方定位为 “Minimalist progress bar”专为 Ajax 型应用设计受 Google、YouTube 和 Medium 等网站的顶部加载进度条启发。它只依赖两个文件nprogress.js核心逻辑约 1000 行以内的纯 JavaScript 实现无任何运行时依赖jQuery 仅用于演示与测试页面nprogress.css样式与动画定义体积同样十分精简。从 package.json 可以看到项目的dependencies为空main字段指向nprogress.js这意味着它可以直接在浏览器中以script标签方式引入也可以通过 CommonJS / AMD / 全局变量三种方式加载见 nprogress.js 的 UMD 包装。安装与引入根据 Readme.md 的 Installation 章节将 nprogress.js 与 nprogress.css 加入项目即可script srcnprogress.js/script link relstylesheet hrefnprogress.css/NProgress 同时支持 bower 与 npm 两种包管理方式安装$ npm install --save nprogress也可以直接通过 CDN 引入以 0.2.0 版本为例当前仓库 nprogress.js 中的NProgress.version即为0.2.0script srchttps://unpkg.com/nprogress0.2.0/nprogress.js/script link relstylesheet hrefhttps://unpkg.com/nprogress0.2.0/nprogress.css/此外bower.json 中声明了main: [nprogress.js, nprogress.css]因此 bower 安装后同样只需引入这两个文件component.json与package.json中的jspm/spm配置则保证了它还可以被 Component、JSPM、SPM 等模块体系直接使用。基础用法start() 与 done()NProgress 的用法极其简单只需调用start()和done()控制进度条NProgress.start(); NProgress.done();从源码看start()会以NProgress.set(0)渲染进度条并立即进入涓流trickle自动递增模式而done()内部实际上是NProgress.inc(0.3 0.5 * Math.random()).set(1)——先随机跳跃一段进度再设置到 100% 并淡出移除从而产生“逼真的运动感”见 nprogress.js 的注释说明。仓库根目录的 index.html 就是一个完整的可运行示例页面加载时调用NProgress.start()1 秒后NProgress.done()并提供了start、set(0.4)、inc()、done()四个演示按钮可以直接打开体验实际效果。与 Turbolinks / Pjax 集成NProgress 最典型的应用场景是配合 Turbolinks 或 Pjax 这类“无刷新换页”技术让用户在页面切换期间看到顶部进度条。Turbolinks5 及以上版本$(document).on(turbolinks:click, function() { NProgress.start(); }); $(document).on(turbolinks:render, function() { NProgress.done(); NProgress.remove(); });注意render事件回调中额外调用了NProgress.remove()用于在页面渲染完成后立即把进度条 DOM 从页面中移除避免残留。Turbolinks3 及以下版本要求 Turbolinks 1.3.0 以上$(document).on(page:fetch, function() { NProgress.start(); }); $(document).on(page:change, function() { NProgress.done(); }); $(document).on(page:restore, function() { NProgress.remove(); });Pjax$(document).on(pjax:start, function() { NProgress.start(); }); $(document).on(pjax:end, function() { NProgress.done(); });这一系列集成模式的价值在于进度条的生命周期完全由框架事件驱动无需手工在业务代码里穿插进度更新逻辑。更多应用想法Readme 还给出了两个实用的扩展思路给所有 Ajax 调用加进度条把start()/done()绑定到 jQuery 的全局ajaxStart与ajaxStop事件即可让页面上所有 Ajax 请求共享一条顶部进度条即使没有 Turbolinks/Pjax 也能做出漂亮的加载条把进度条绑定到$(document).ready和$(window).load模拟整页加载过程。这两种方案都不需要修改 NProgress 本身只需在你的业务代码中组织事件绑定即可。进阶用法set / inc / done(true) / status设置百分比.set(n)set(n)接受0.0到1.0之间的数值用于精确控制进度NProgress.set(0.0); // 相当于 .start() NProgress.set(0.4); NProgress.set(1.0); // 相当于 .done()从源码看set()内部会对 n 做clamp(n, Settings.minimum, 1)处理即下限被钳制为minimum配置值默认 0.08上限为 1当 n 为 1 时NProgress.status会被置回null表示“未开始”并执行淡出与移除流程nprogress.js。这一点在 test/test.js 中有对应测试set(0)后 status 等于settings.minimumset(-100)同样被钳制到 minimumset(456)则视为完成。递增.inc().inc()以随机增量推进进度条永远不会到达 100%适合配合“每张图片加载完成”之类的场景使用NProgress.inc();也可以传入明确的增量值NProgress.inc(0.2); // 在当前 status 基础上加 0.2上限 0.994从 nprogress.js 的源码可以看到无参inc()的“涓流”算法进度在 0~0.2 区间时每次递增 0.10.2~0.5 区间递增 0.040.5~0.8 区间递增 0.020.8~0.99 区间递增 0.005越接近完成增量越小最后统一clamp(n amount, 0, 0.994)——永远不会到 1。测试 test/test.js 也验证了连续调用 100 次inc()后 status 依然小于 1.0。强制完成.done(true)默认情况下如果从未调用过start()调用done()不会做任何事情源码中if (!force !NProgress.status) return this;。传入true则可以强制显示并完成进度条NProgress.done(true);读取当前状态.status通过NProgress.status可以随时读取当前进度值。源码中status初始为null一旦set()被调用就成为0.08~1.0之间的数字完成n1后又回到nullisStarted()正是通过typeof NProgress.status number来判断进度条是否已启动。配置详解configure 的八项参数所有配置都通过NProgress.configure({ ... })设置。源码中这些配置集中定义在NProgress.settings对象里nprogress.jsconfigure()会把传入对象中所有非 undefined 的键值合并进 settingsnprogress.js。下表汇总了全部配置项、默认值与作用配置项默认值说明minimum0.08起始时的最小百分比template默认 bar spinner 模板自定义进度条 DOM 结构easinglinearReadme 示例中为easeCSS 缓动函数字符串speed200动画时长毫秒trickletrue是否开启自动递增trickleSpeed200自动递增的间隔毫秒showSpinnertrue是否显示右侧加载圈parentbody进度条的父容器minimum起始最小百分比NProgress.configure({ minimum: 0.1 });minimum会在set()/start()时把初始进度钳制到该值以上避免进度条从 0 突兀开始。测试 test/test.js 验证了configure({ minimum: 0.5 })能正确写入 settings。template自定义 DOM 模板NProgress.configure({ template: div class......./div });使用template可以完全替换进度条的 DOM 结构但为了让进度条正常工作模板中必须保留一个rolebar的元素。默认模板定义在源码中nprogress.jsdiv classbar rolebardiv classpeg/div/divdiv classspinner rolespinnerdiv classspinner-icon/div/divrender()会把模板注入#nprogress容器并通过barSelector: [rolebar]和spinnerSelector: [rolespinner]两个选择器定位 bar 与 spinner 元素nprogress.js所以自定义模板时保证role属性不变即可。easing与speed动画设置NProgress.configure({ easing: ease, speed: 500 });easing是 CSS 缓动字符串Readme 示例为ease源码默认值是linearspeed是动画时长毫秒默认 200。二者会拼接成transition: all speed ms ease应用到 bar 元素上nprogress.js控制进度条每次位移的过渡效果。trickle关闭自动递增NProgress.configure({ trickle: false });trickle默认true此时start()会启动一个以trickleSpeed为间隔的递归定时器不断调用trickle()即无参inc()模拟真实的加载过程nprogress.js。设为false后进度只会在你显式调用set()/inc()时变化适合需要完全手动控制进度的场景。trickleSpeed递增间隔NProgress.configure({ trickleSpeed: 200 });控制自动递增的频率单位毫秒默认 200ms。在start()的定时器中每次回调都会先检查NProgress.status是否仍存在若进度条已被done()移除则自动终止递归避免内存泄漏。showSpinner关闭加载圈NProgress.configure({ showSpinner: false });默认true会在页面右上角显示一个 18×18 的旋转圆圈样式见 nprogress.css。设为false后render()会直接把模板中的 spinner 元素从 DOM 移除nprogress.js。测试 test/test.js 验证了默认渲染 spinner、配置false后不渲染。parent更换父容器NProgress.configure({ parent: #container });默认进度条固定在body上position: fixed见 nprogress.css。指定parent后进度条会被插入该容器内同时容器会获得nprogress-custom-parent类CSS 中对应规则会把 bar 和 spinner 改为position: absolute使其跟随容器滚动而非固定在视口顶部nprogress.css。测试 test/test.js 验证了configure({parent: #test})后进度条确实挂载到#test下且父容器带上了nprogress-custom-parent类。parent既支持 CSS 选择器字符串也支持直接传入 DOM 元素isDOM()检测见 nprogress.js。自定义样式改 nprogress.cssReadme 的 Customization 章节指出只需按需编辑 nprogress.css 即可最常用的做法是全局查找并替换主题色#29d。这个颜色在样式表中共出现在 4 处bar 的背景色nprogress.css右侧peg拖尾元素的模糊光晕box-shadownprogress.cssspinner 圆圈的border-top-color与border-left-colornprogress.css。从结构上看默认进度条由三部分组成顶部 2px 高的蓝色bar、bar 右端 100px 宽带有发光效果的旋转peg拖尾、以及右上角旋转的spinner。Readme 强调“自带的 CSS 非常精简完全可以弃用并自行编写”因此你可以自由决定是否保留 peg 光晕、spinner甚至改用完全不同的视觉呈现——只要 JS 端的模板与role约定保持一致即可。源码原理NProgress 是如何工作的渲染与移除render()是核心渲染函数先检查document.getElementById(nprogress)是否已存在isRendered()不存在则在html上添加nprogress-busy类、创建#nprogress容器并注入模板。首次渲染时 bar 的位移被设为translate3d(-100%,0,0)完全移出视口之后每次set()都通过queue队列串行执行位移动画nprogress.js。remove()则负责移除nprogress-busy与nprogress-custom-parent类并删除 DOMnprogress.js。兼容性处理三种位移策略getPositioningCSS()nprogress.js会在首次使用时嗅探浏览器能力从三种位移方案中选择translate3d支持 3D 变换的现代浏览器如 WebKit、IE10translate不支持 3D 但支持 transform 的浏览器如 IE9margin两者都不支持的老旧浏览器如 IE7-8退化为修改margin-left。动画队列进度条的每次移动都通过内部queue函数串行排队执行保证快速连续调用set()时动画按顺序完成不会互相打断nprogress.js。Promise 支持除了 Readme 中介绍的 API源码还内置了NProgress.promise($promise)nprogress.js传入 jQuery Promise 后会自动start()并随 Promise 的 resolve 进度逐步set()全部完成后自动done()。这为“多请求并行、统一进度展示”提供了开箱即用的方案。测试验证仓库使用 Mocha Chai jsdom 编写了覆盖核心 API 的测试test/test.js运行方式为npm test见 package.json 的 scripts。测试覆盖了set()的渲染与钳制、start()的最小值与 parent 挂载、done()的 force 行为、remove()的清理、inc()的递增与永不触顶、以及configure()与showSpinner等关键行为是理解 NProgress 各 API 语义的最佳参考。小结NProgress 的价值在于以最小的体积和最简单的 APIstart()/done()两个方法即可驱动为 Ajax 型应用提供一条足够“真实”的顶部进度条。本文从 Readme.md 出发完整覆盖了安装引入、基础/进阶用法、Turbolinks/Pjax 集成、八项配置参数与样式定制并结合 nprogress.js 源码剖析了涓流递增算法、渲染队列、位移降级与 Promise 支持等底层机制。实际接入时只需记住三条铁律保留模板中的rolebar、用configure()调整行为、用nprogress.css控制外观——其余交给 NProgress 即可。赞分享前端UI组件【免费下载链接】nprogressFor slim progress bars like on YouTube, Medium, etc项目地址https://gitcode.com/gh_mirrors/np/nprogress点击查看免费下载相关推荐VuePress 官方 nprogress 插件vuepress/plugin-nprogress完全指南原理、安装与自定义进度条VuePress 官方 nprogress 插件vuepress/plugin nprogress完全指南原理、安装与自定义进度条 本文以 VuePre前端文档SSRVuePress 官方 nprogress 进度条插件安装、配置与路由加载进度条原理剖析VuePress 官方 nprogress 进度条插件安装、配置与路由加载进度条原理剖析 导读 vuepress/plugin nprogress 是 Vu前端文档SSRVuePress nprogress 插件指南为页面跳转添加顶部进度条VuePress nprogress 插件指南为页面跳转添加顶部进度条 本指南聚焦 VuePress 官方插件 vuepress/plugin nprogr前端文档SSR上一篇Translator3000RenPy游戏自动翻译工具下一篇零基础教程5步搞定无人机航拍3D建模 - OpenDroneMap完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考