从入门到精通详解Vue3如何集成NProgress进度条

前端应用开发中，用户体验是绕不开的核心命题。页面加载或数据请求时，一个恰到好处的进度条，不仅能告诉用户“系统正在干活”，还能有效缓解等待的焦灼感。NProgress 作为轻量级进度条库，凭借简洁的设计和良好的兼容性，几乎成了各类 Web 项目中的常客。这次我们就来聊聊，如何在 Vue3 项目里优雅地把它集成进来，并且用得顺手。

一、环境准备

1.1 安装依赖

# 安装 NProgress 核心库和 lodash-es 工具库pnpm i nprogress lodash-es# 安装 TypeScript 类型定义（开发依赖）pnpm i @types/nprogress @types/lodash-es -D

1.2 依赖说明

• nprogress：进度条核心库，提供简单的进度控制 API
• lodash-es：高效的 Ja vaScript 工具库，用于对象合并等操作
• @types/nprogress：NProgress 的 TypeScript 类型定义文件
• @types/lodash-es：lodash-es 的 TypeScript 类型定义文件

1.3 环境变量配置

在 .env 文件中配置进度条的开关：

# 路由进度条，默认开启（设置为 'false' 可关闭）VITE_ROUTER_NPROGRESS = true# 请求进度条，默认开启（设置为 'false' 可关闭）VITE_REQUEST_NPROGRESS = true

二、核心实现

2.1 基础封装

// src/hooks/useProgress.tsimport { merge } from 'lodash-es'import NProgress from 'nprogress'import type { NProgressOptions } from 'nprogress'interface ProgressConfig extends NProgressOptions {  /** 是否显示进度条 */  show: boolean}const DEFAULT_CONFIG: Partial = {  /** CSS3 缓冲动画字符串，支持 ease、linear、ease-in、ease-out、ease-in-out 以及自定义 cubic-bezier 等 */  easing: 'ease',  /** 指定进度条的父容器，默认为 body */  parent: 'body',  /** 是否显示进度条，可通过环境变量控制 */  show: true,  /** 是否显示右侧的环形进度动画 */  showSpinner: false,  /** 是否开启自动递增模式 */  trickle: true,  /** 设置开始时最低百分比，范围 0-1 */  minimum: 0.08,  /** 动画速度，单位毫秒 */  speed: 200,}/** * 进度条控制工具 Hook * @param config 自定义配置，会与默认配置深度合并 * @returns { start, done } 启动/结束进度条方法 */export function useProgress(config: Partial = {}) {  const mergeConfig = merge({}, DEFAULT_CONFIG, config)  NProgress.configure(mergeConfig)  /**   * 启动进度条   */  function start() {    if (!mergeConfig.show) return    NProgress.start()  }  /**   * 结束进度条   */  function done() {    if (!mergeConfig.show || !NProgress.isStarted()) return    NProgress.done()  }  return { start, done }}

三、实际应用场景

3.1 Axios 请求拦截器集成

在实际项目中，通常需要为 API 请求自动加上进度条。下面的示例展示了如何配合 Axios 使用，并通过环境变量控制显示：

// src/utils/request.tsimport axios, { AxiosInstance, AxiosResponse, InternalAxiosRequestConfig } from 'axios'const NProgress = useProgress({ show: import.meta.env.VITE_REQUEST_NPROGRESS !== 'false' })const instance: AxiosInstance = axios.create({  baseURL: import.meta.env.VITE_API_BASE_URL,  timeout: 15000,})// 请求拦截器instance.interceptors.request.use(  (config: InternalAxiosRequestConfig) => {    NProgress.start()    return config  },  (error) => {    NProgress.done()    return Promise.reject(error)  },)// 响应拦截器instance.interceptors.response.use(  (response: AxiosResponse) => {    NProgress.done()    return response  },  (error) => {    NProgress.done()    return Promise.reject(error)  },)export const request = instance

3.2 Vue Router 路由守卫集成

结合 Vue Router，可以在页面切换时显示进度条，同样通过环境变量控制：

// src/router/index.tsimport { createRouter, createWebHistory } from 'vue-router'const router = createRouter({  history: createWebHistory(),  routes: [],})const NProgress = useProgress({ show: import.meta.env.VITE_ROUTER_NPROGRESS !== 'false' })router.beforeEach((to, from, next) => {  NProgress.start()  next()})router.afterEach(() => {  NProgress.done()})export default router

3.3 组合式使用示例