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

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

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

// src/hooks/useProgress.ts
import { merge } from 'lodash-es'
import NProgress from 'nprogress'
import type { NProgressOptions } from 'nprogress'
interface ProgressConfig extends NProgressOptions {
  /** 是否显示进度条 */
  show: boolean
}
const DEFAULT_CONFIG: Partial<ProgressConfig> = {
  /** 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<ProgressConfig> = {}) {
  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 }
}

// src/utils/request.ts

import 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

// src/router/index.ts

import { 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

<template>
  <div class="app">
    <button @click="loadData">加载数据</button>
  </div>
</template>
<script setup lang="ts">
import { useProgress } from '@/hooks/useProgress'
const NProgress = useProgress({ show: import.meta.env.VITE_REQUEST_NPROGRESS !== 'false' })
async function loadData() {
  NProgress.start()
  try {
    await fetch('/api/data')
  } finally {
    NProgress.done()
  }
}
</script>

// src/styles/index.scss
@use './variables.scss';
@use './transition.scss';
@use 'nprogress/nprogress.css';
@use './element-plus/el-table.scss';
@use './element-plus/el-dialog.scss';
@use './element-plus/el-dropdown.scss';
body {
  font-family: var(--el-font-family);
  background-color: var(--el-bg-color-page);
}
#nprogress .bar {
  background-color: var(--el-color-primary);
}

// src/styles/nprogress.scss
#nprogress .bar {
  background-color: var(--el-color-primary);
  height: 3px;
  // 添加渐变效果
  background: linear-gradient(90deg, var(--el-color-primary-light-3) 0%, var(--el-color-primary) 100%);
}
#nprogress .peg {
  box-shadow: 0 0 10px var(--el-color-primary);
}
#nprogress .spinner-icon {
  border-top-color: var(--el-color-primary);
  border-left-color: var(--el-color-primary);
}

// src/styles/index.scss
@use './variables.scss';
@use './transition.scss';
@use './nprogress.scss'; // 替换为自定义样式文件
@use './element-plus/el-table.scss';
@use './element-plus/el-dialog.scss';
@use './element-plus/el-dropdown.scss';
body {
  font-family: var(--el-font-family);
  background-color: var(--el-bg-color-page);
}
#nprogress .bar {
  background-color: var(--el-color-primary);
}

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import './styles/index.scss' // 引入全局样式
const app = createApp(App)
app.mount('#app')

const EASING_FUNCTIONS = {
  // 匀速运动
  linear: 'linear',

  // 标准缓动
  ease: 'ease',
  easeIn: 'ease-in',
  easeOut: 'ease-out',
  easeInOut: 'ease-in-out',

  // 自定义贝塞尔曲线
  smooth: 'cubic-bezier(0.4, 0, 0.2, 1)',
  gentle: 'cubic-bezier(0.25, 0.1, 0.25, 1)',
  swift: 'cubic-bezier(0.4, 0, 0.6, 1)',
}