在前端开发中，用户体验往往体现在细节之处。当页面加载、数据请求时，如果没有任何反馈，用户很容易产生 “页面卡住” 的误解，进而降低对产品的好感度。而 nprogress 组件作为一款轻量级的进度条插件，能完美解决这一问题 —— 它可以在页面加载、接口请求等场景中显示动态进度，让用户清晰感知操作进度。今天，我们就从基础到进阶，全面拆解 nprogress 组件的用法，帮你轻松提升项目的交互体验。

nprogress 组件基础：快速上手三步走

nprogress 的核心优势在于 “轻量” 和 “易用”，整个插件体积不足 2KB，且无需复杂配置就能快速集成到各类前端项目中。无论是 Vue、React 还是原生 JS 项目，都能轻松适配。下面我们以最常见的 Vue 项目为例，演示基础用法。

第一步：安装 nprogress

nprogress 支持 npm 和 yarn 两种安装方式，直接在项目终端执行以下命令即可：

// npm安装
npm install nprogress --save

// yarn安装
yarn add nprogress

如果是原生 JS 项目，也可以通过 CDN 引入，在 HTML 文件头部添加如下代码：

<link rel="stylesheet" href="https://unpkg.com/nprogress@0.2.0/nprogress.css">
<script src="https://unpkg.com/nprogress@0.2.0/nprogress.js"></script>

第二步：引入并初始化

在 Vue 项目中，我们通常会在路由拦截器或请求拦截器中使用 nprogress，因此建议在main.js或单独的工具类文件中引入：

// 引入nprogress和其样式文件
import NProgress from 'nprogress'
import 'nprogress/nprogress.css'

// 简单配置（可选）：关闭右上角的旋转加载动画
NProgress.configure({ showSpinner: false })

这里的configure方法用于基础配置，除了showSpinner，还支持easing（动画缓动效果）、speed（动画速度）等参数，具体配置我们会在 “进阶技巧” 部分详细说明。

第三步：核心 API 调用

nprogress 的 API 非常简洁，常用的只有 4 个，掌握后就能覆盖 80% 的使用场景：

• NProgress.start()：启动进度条，进度会从 0 开始逐渐增长
• NProgress.done()：结束进度条，进度会直接跳转到 100% 并消失
• NProgress.set(n)：手动设置进度值，n 的范围为 0-1（例如NProgress.set(0.5)表示 50% 进度）
• NProgress.inc()：随机增加进度，每次调用增加的幅度在 0.01-0.1 之间，避免进度条长时间停留在同一位置

最经典的用法是结合路由跳转和接口请求。比如在路由拦截中，当用户切换页面时启动进度条，页面加载完成后结束：

// 路由前置守卫：跳转时启动进度条
router.beforeEach((to, from, next) => {
  NProgress.start()
  next()
})

// 路由后置守卫：页面加载完成后结束进度条
router.afterEach(() => {
  NProgress.done()
})

在接口请求中，我们可以结合 Axios 拦截器使用：

// Axios请求拦截器：发起请求时启动进度条
axios.interceptors.request.use(config => {
  NProgress.start()
  return config
})

// Axios响应拦截器：请求完成后结束进度条
axios.interceptors.response.use(response => {
  NProgress.done()
  return response
}, error => {
  // 请求失败也要结束进度条，避免进度条一直显示
  NProgress.done()
  return Promise.reject(error)
})

这样一来，无论是页面跳转还是数据请求，进度条都会自动显示，用户能清晰感知操作状态，避免 “无反馈” 的尴尬。

进阶配置：自定义进度条样式与行为

默认的 nprogress 进度条是蓝色细线条，虽然简洁，但可能无法适配所有项目的设计风格。好在 nprogress 提供了丰富的配置项，支持自定义样式、动画速度等，让进度条更贴合项目需求。

1. 基础配置项详解

通过NProgress.configure(options)方法可以配置进度条的核心行为，常用的 options 参数如下：

比如我们想让进度条动画更平缓，且关闭旋转动画，可以这样配置：

NProgress.configure({
  showSpinner: false, // 关闭旋转动画
  easing: 'linear', // 线性动画
  speed: 300, // 动画速度300ms
  minimum: 0.1 // 最小进度显示10%
})

2.自定义进度条样式

nprogress 的样式是通过 CSS 实现的，我们可以通过覆盖默认 CSS 类来修改进度条的颜色、高度、背景等样式。默认的核心 CSS 类有两个：

• .nprogress-bar：进度条本体
• .nprogress-spinner：右上角的旋转动画（如果开启的话）

比如我们想把进度条改成红色、高度调整为 3px，可以在项目的全局 CSS 文件中添加如下代码：

/* 自定义进度条样式 */
#nprogress .bar {
  background: #ff4d4f !important; /* 红色进度条 */
  height: 3px !important; /* 高度3px */
}

/* 自定义进度条顶部阴影 */
#nprogress .peg {
  box-shadow: 0 0 10px #ff4d4f, 0 0 5px #ff4d4f !important;
}

/* 自定义旋转动画颜色 */
#nprogress .spinner-icon {
  border-top-color: #ff4d4f !important;
  border-left-color: #ff4d4f !important;
}

这里需要注意添加!important来覆盖默认样式，确保自定义样式生效。如果项目使用了 Less 或 Sass，也可以通过变量重定义的方式修改，更符合 CSS 预处理器的使用习惯。

3. 特殊场景：手动控制进度

在一些特殊场景中，比如文件上传、大文件加载，我们可以获取到具体的进度百分比，这时就可以用NProgress.set(n)手动控制进度条。以文件上传为例，结合 Axios 的onUploadProgress回调：

// 文件上传时手动更新进度条
const uploadFile = (file) => {
  const formData = new FormData()
  formData.append('file', file)
  
  axios.post('/api/upload', formData, {
    onUploadProgress: (progressEvent) => {
      // 计算上传进度（已上传字节数/总字节数）
      const percent = progressEvent.loaded / progressEvent.total
      // 手动设置进度条值
      NProgress.set(percent)
    }
  }).then(() => {
    // 上传完成，结束进度条
    NProgress.done()
    alert('上传成功！')
  }).catch(() => {
    NProgress.done()
    alert('上传失败！')
  })
}

实战避坑：这些问题你一定要注意

虽然 nprogress 用法简单，但在实际项目中，很多开发者会遇到 “进度条不显示”“多次触发导致混乱” 等问题。下面我们总结几个高频坑点及解决方案，帮你少走弯路。

1. 坑点 1：进度条不显示，排查三步走

很多开发者引入 nprogress 后发现进度条不显示，大概率是以下三个原因导致的，按顺序排查即可：

• 第一步：检查样式是否引入：nprogress 的进度条样式依赖nprogress.css，如果漏引，会导致进度条只在 DOM 中存在但不可见。Vue 项目中要确保import 'nprogress/nprogress.css'语句存在。
• 第二步：检查调用时机是否正确：如果在异步操作完成后才调用start()，会导致进度条 “一闪而过” 或不显示。比如路由守卫中，要确保NProgress.start()在next()之前调用。
• 第三步：检查样式是否被覆盖：如果项目的全局 CSS 中有#nprogress或.bar等类的样式，可能会覆盖 nprogress 的默认样式。可以通过浏览器开发者工具的 “Elements” 面板查看进度条元素的样式是否生效，必要时添加!important强制生效。

2. 坑点 2：多次请求导致进度条重复触发

当页面同时发起多个接口请求时，如果每个请求都调用start()和done()，会导致进度条反复启动和结束，出现 “闪烁” 问题。解决方案是通过 “计数器” 控制进度条的启动和结束：

// 定义计数器，记录当前未完成的请求数
let requestCount = 0

// 请求拦截器：计数器+1，启动进度条
axios.interceptors.request.use(config => {
  requestCount++
  NProgress.start()
  return config
})

// 响应拦截器：计数器-1，当计数器为0时结束进度条
axios.interceptors.response.use(response => {
  requestCount--
  if (requestCount === 0) {
    NProgress.done()
  }
  return response
}, error => {
  requestCount--
  if (requestCount === 0) {
    NProgress.done()
  }
  return Promise.reject(error)
})

这样一来，只有当所有请求都完成后，进度条才会结束，避免了重复触发的问题。

3. 坑点 3：单页应用中路由快速切换导致进度条异常

在 Vue、React 等单页应用中，如果用户快速切换路由，可能会导致前一个路由的done()在新路由的start()之后调用，出现进度条 “提前结束” 的问题。解决方案是在路由前置守卫中先判断进度条是否已启动，如果已启动，先调用done()再重新start()：

router.beforeEach((to, from, next) => {
  // 如果进度条已启动，先结束再重新启动
  if (NProgress.isStarted()) {
    NProgress.done()
  }
  NProgress.start()
  next()
})

NProgress.isStarted()方法可以判断进度条是否处于启动状态，通过这个判断可以避免路由切换时的进度条冲突。

扩展场景：nprogress 的更多实用玩法

除了常规的路由和接口请求场景，nprogress 还可以应用在更多场景中，进一步提升项目的交互体验。

1. 页面加载进度：结合 Vue 的生命周期

在 Vue 组件中，如果某个页面需要加载大量数据或渲染复杂 DOM，可以在组件的生命周期钩子中使用 nprogress。比如在created钩子中启动进度条，在mounted或数据加载完成后结束：

export default {
  data() {
    return {
      list: []
    }
  },
  created() {
    // 组件创建时启动进度条
    NProgress.start()
    // 加载数据
    this.loadData()
  },
  methods: {
    async loadData() {
      try {
        const res = await axios.get('/api/list')
        this.list = res.data
        // 数据加载完成，结束进度条
        NProgress.done()
      } catch (error) {
        NProgress.done()
        console.error('数据加载失败：', error)
      }
    }
  }
}

这种方式适合数据量较大、加载时间较长的页面，让用户清晰感知页面的准备过程。

2. 自定义进度条位置：从顶部到底部

默认的 nprogress 进度条显示在页面顶部，但通过 CSS 修改，我们可以让它显示在底部、左侧甚至右侧。比如让进度条显示在页面底部：

/* 让进度条显示在页面底部 */
#nprogress .bar {
  top: auto !important;
  bottom: 0 !important;
}

如果想让进度条显示在左侧（垂直方向），可以这样配置：

#nprogress .bar {
  top: 0 !important;
  left: 0 !important;
  width: 3px !important;
  height: 100% !important;
  /* 垂直方向的动画需要修改过渡属性 */
  transition: height 0.2s ease !important;
}

不过垂直进度条需要配合NProgress.set(n)手动控制高度，更适合文件上传等需要精准显示进度的场景。

3. 结合 UI 框架：与 Element UI、Ant Design 适配

如果项目中使用了 Element UI、Ant Design 等 UI 框架，可以将 nprogress 与框架的加载状态结合。比如在 Element UI 的el-upload组件中使用：

<el-upload
  action="/api/upload"
  :on-progress="handleProgress"
  :on-success="handleSuccess"
  :on-error="handleError"
>
  <el-button size="small" type="primary">点击上传</el-button>
</el-upload>

methods: {
  handleProgress() {
    // 上传进度变化时启动进度条（或更新进度）
    if (!NProgress.isStarted()) {
      NProgress.start()
    }
  },
  handleSuccess() {
    NProgress.done()
  },
  handleError() {
    NProgress.done()
  }
}

这样可以让进度条与框架的组件状态联动，保持交互体验的一致性。

总结

nprogress 作为一款轻量级的进度条组件，虽然功能简单，但却能在细节处显著提升用户体验。它的核心优势在于 “易用性” 和 “灵活性”—— 无论是基础的路由跳转反馈，还是复杂的文件上传进度显示，都能通过简单的配置和 API 实现。

在实际开发中，我们需要注意：

合理选择调用场景：避免在高频次、短时间的操作中使用，以免造成视觉干扰；

自定义样式适配项目：让进度条的颜色、风格与项目设计保持一致；

处理边界情况：通过计数器、状态判断等方式解决多请求、路由切换等场景下的异常问题。

最后，附上 nprogress 的官方文档地址：
https://github.com/rstacruz/nprogress，里面有更详细的 API 说明和配置示例。如果在使用过程中遇到其他问题，欢迎在评论区交流分享你的解决方案！