前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载useNProgress是 VueUse Integrations 系列中对nprogress的响应式封装让你以 Vue 原生的 Ref 语法驱动经典的顶部细进度条。本文基于 VueUse 仓库中 useNProgress 的参考文档 与 源码实现完整讲解安装、基础用法、进度百分比控制与样式定制并结合源码剖析其响应式联动原理。读完本文你将掌握如何用寥寥几行代码为路由切换、异步请求等场景接入一个可声明式控制的进度条。背景为什么需要响应式封装nprogress是一个轻量、无依赖的顶部进度条库其核心 API 是命令式的start()、done()、set(n)与configure(options)。在 Vue 3 的组合式 API 语境下命令式调用难以与模板、watch等响应式机制直接联动。useNProgress的做法是把命令式 API 包装成Ref与WritableComputedRef让进度状态成为组件数据流的一部分。在 VueUse 仓库中它位于 Integrations 包内并由 packages/integrations/index.ts 统一导出。安装与依赖说明useNProgress是一个集成封装本身不打包nprogress因此需要单独安装npm i nprogress^0如果使用 pnpm还可一并安装类型声明pnpm add nprogress^0 pnpm add -D types/nprogress在 packages/integrations/package.json 中nprogress被声明为可选 peer 依赖nprogress: ^0.2并在peerDependenciesMeta中标记optional: true意味着你只在使用该函数时才需要安装它不会强制拖入无关依赖。基础用法声明式开关 isLoading使用方式非常直接——从vueuse/integrations/useNProgress子路径导入import { useNProgress } from vueuse/integrations/useNProgress const { isLoading } useNProgress() function toggle() { isLoading.value !isLoading.value }isLoading是一个WritableComputedRefboolean, boolean把isLoading.value置为true会调用nprogress.start()让进度条开始流动置为false则调用nprogress.done()让进度条收尾并淡出。因此在模板中可以直接绑定button clickisLoading !isLoading {{ isLoading ? Stop : Start }} /button这段写法的演示可参见仓库中的 useNProgress/demo.vue它还展示了配合progress实时显示百分比b v-ifisLoading classml-2{{ ((progress || 0) * 100).toFixed(0) }}%/b底层联动原理从源码 packages/integrations/useNProgress/index.ts 可以看到isLoading的完整定义const isLoading computed({ set: load load ? nprogress.start() : nprogress.done(), get: () typeof progress.value number progress.value 1, })get的判定逻辑是只有当progress是数字且小于1时才算加载中。这与nprogress的语义一致——进度到达1即表示完成。由此isLoading既能手动写入驱动进度条也能从当前进度反推出加载状态供模板展示实现双向联动。控制进度百分比progress RefuseNProgress的第一个参数用于传入初始进度支持数字、Ref或 getter 函数MaybeRefOrGetternumber | null | undefinedconst { progress } useNProgress(0.5) function done() { progress.value 1.0 }要改变进度百分比只需设置progress.value n其中n是0..1之间的数字。默认参数为null表示进度条处于未知进度的流动状态。源码中的同步机制源码对进度的同步做了两层处理packages/integrations/useNProgress/index.tsconst setProgress nprogress.set nprogress.set (n: number) { progress.value n return setProgress.call(nprogress, n) } watchEffect(() { if (typeof progress.value number isClient) setProgress.call(nprogress, progress.value) })第一处拦截并重写nprogress.set。当nprogress内部因自动递增而更新进度时同步写回progress.value保证 Ref 始终反映真实进度第二处watchEffect反向驱动。当外部修改progress.value为数字时调用底层的set把进度推给nprogress且通过isClient来自vueuse/shared在服务端渲染时跳过 DOM 操作保证 SSR 安全。这种双向同步正是响应式封装的核心价值无论进度来自手动赋值、路由守卫还是nprogress内部逻辑progressRef 都能保持一致。配置项第二个参数 options可以通过第二个参数传入配置对象来定制行为例如设置进度条的最小初始值import { useNProgress } from vueuse/integrations/useNProgress useNProgress(null, { minimum: 0.1, // 其他 nprogress 配置项 })options的类型是UseNProgressOptions PartialNProgressOptionspackages/integrations/useNProgress/index.ts即nprogress全部配置项的浅层可选子集常见可用项包括配置项作用典型值minimum起始最小进度避免刚启动就跳到过高的百分比0.08起示例中使用0.1easing进度条运动的缓动函数名ease、linearspeed进度条动画速度毫秒200trickle是否启用自动递增的小步前进truetrickleSpeed自动递增的时间间隔毫秒200showSpinner是否显示右上角旋转加载圈true/falseparent进度条挂载的父容器元素body或某个 DOM 元素这些配置会通过nprogress.configure(options)一次性应用到全局packages/integrations/useNProgress/index.ts因此适合在应用初始化时统一配置。样式定制进度条的外观由nprogress自带的 CSS 控制。最直接的做法是修改nprogress.css中你喜欢的部分——通常只需查找并替换主题色#29dnprogress 的默认蓝色即可。仓库中的示例 useNProgress/style.css 提供了一套可参考的自定义样式它把主色替换为绿色#67d391保留#nprogress上pointer-events: none让点击事件穿透进度条并为进度条.bar设置了position: fixed、z-index: 1031、top: 0、height: 2px的顶部细条布局同时用.peg的box-shadow实现右侧发光拖尾效果。在自己的项目中引入自定义样式的方式与 demo 一致import { useNProgress } from vueuse/integrations/useNProgress import ./style.css如果需要把进度条限制在某个局部容器内而不是全屏顶部可以配合parent配置项指定容器并给容器添加nprogress-custom-parent类样式文件中有对应的绝对/相对定位规则。返回的完整 APIuseNProgress返回一个包含五个成员的对象packages/integrations/useNProgress/index.tsexport interface UseNProgressReturn { isLoading: WritableComputedRefboolean, boolean progress: Refnumber | null | undefined start: () NProgress done: (force?: boolean) NProgress remove: () void }成员类型说明isLoadingWritableComputedRefboolean读写双向置true调用start()置false调用done()读取时按progress 1判断progressRefnumber \| null \| undefined当前进度百分比0..1可读可写start() NProgress启动进度条透传自nprogress.startdone(force?: boolean) NProgress结束进度条force为true时强制立即完成remove() void移除进度条 DOM同时将progress重置为null注意done(force)支持一个可选的force参数传true时跳过淡出动画立即移除进度条。而remove的语义更彻底——源码中它同时把progress.value重置为null并调用nprogress.remove()packages/integrations/useNProgress/index.ts适合在组件卸载或需要彻底清除进度条时使用。生命周期自动清理一个值得关注的细节源码在函数末尾调用了tryOnScopeDispose(nprogress.remove)packages/integrations/useNProgress/index.ts。tryOnScopeDispose来自vueuse/shared导出见 packages/shared/index.ts它的语义是如果当前存在活跃的 effect scope如组件实例或手动effectScope就在作用域销毁时自动执行清理回调否则直接忽略。这意味着当使用useNProgress的组件被卸载或包裹它的effectScope被释放时进度条会自动移除无需手动清理避免进度条残留在页面上或产生内存泄漏。典型应用场景把以上能力组合起来最常见的落地场景是路由级加载指示。以 Vue Router 为例在全局前置守卫中结合isLoading即可实现跳转期间显示进度条import { useNProgress } from vueuse/integrations/useNProgress const { isLoading, done } useNProgress(null, { showSpinner: false }) router.beforeEach(() { isLoading.value true }) router.afterEach(() { done() })异步请求场景中也可以用progress精确反映上传/下载进度或对多个并行请求统一以start/done收口。由于isLoading、progress都是标准的响应式引用它们天然可以放进watch、计算属性或组件模板中与 Vue 3 的组合式 API 生态无缝衔接。小结useNProgress是nprogress的响应式薄封装核心价值在于把命令式 API 转换为isLoading/progress两个响应式引用并保持双向同步安装时需单独引入nprogress可选 peer 依赖样式可参考 style.css 自定义配置通过第二个参数传入通过重写nprogress.set与watchEffect实现进度双向同步借助tryOnScopeDispose实现组件卸载自动清理官方参考文档 useNProgress.md 与源码 index.ts、demo.vue 可直接对照阅读是理解该函数最权威的第一手资料。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐VueUse useNProgress在 Vue 3 中响应式驱动 nprogress 顶部进度条VueUse useNProgress在 Vue 3 中响应式驱动 nprogress 顶部进度条 useNProgress 是 VueUse Integra前端在 airi 中集成 VueUse useNProgress从响应式进度条到路由加载指示实战在 airi 中集成 VueUse useNProgress从响应式进度条到路由加载指示实战 useNProgress 是 VueUse 生态中针对 nproAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染VueUse useGamepad 实战在 Vue 3 应用中响应式接入 Gamepad APIAiri 仓库参考指南VueUse useGamepad 实战在 Vue 3 应用中响应式接入 Gamepad APIAiri 仓库参考指南 本文基于 Airi 开源仓库中的AI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染上一篇Claude Code 代码现代化插件code-modernization实战指南从 COBOL 遗留系统到可验证的新架构下一篇魔兽争霸3终极重生指南5分钟让经典游戏在Windows 11上流畅运行创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VueUse useNProgress 实战：为 Vue 3 应用接入响应式顶部进度条
前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载useNProgress是 VueUse Integrations 系列中对nprogress的响应式封装让你以 Vue 原生的 Ref 语法驱动经典的顶部细进度条。本文基于 VueUse 仓库中 useNProgress 的参考文档 与 源码实现完整讲解安装、基础用法、进度百分比控制与样式定制并结合源码剖析其响应式联动原理。读完本文你将掌握如何用寥寥几行代码为路由切换、异步请求等场景接入一个可声明式控制的进度条。背景为什么需要响应式封装nprogress是一个轻量、无依赖的顶部进度条库其核心 API 是命令式的start()、done()、set(n)与configure(options)。在 Vue 3 的组合式 API 语境下命令式调用难以与模板、watch等响应式机制直接联动。useNProgress的做法是把命令式 API 包装成Ref与WritableComputedRef让进度状态成为组件数据流的一部分。在 VueUse 仓库中它位于 Integrations 包内并由 packages/integrations/index.ts 统一导出。安装与依赖说明useNProgress是一个集成封装本身不打包nprogress因此需要单独安装npm i nprogress^0如果使用 pnpm还可一并安装类型声明pnpm add nprogress^0 pnpm add -D types/nprogress在 packages/integrations/package.json 中nprogress被声明为可选 peer 依赖nprogress: ^0.2并在peerDependenciesMeta中标记optional: true意味着你只在使用该函数时才需要安装它不会强制拖入无关依赖。基础用法声明式开关 isLoading使用方式非常直接——从vueuse/integrations/useNProgress子路径导入import { useNProgress } from vueuse/integrations/useNProgress const { isLoading } useNProgress() function toggle() { isLoading.value !isLoading.value }isLoading是一个WritableComputedRefboolean, boolean把isLoading.value置为true会调用nprogress.start()让进度条开始流动置为false则调用nprogress.done()让进度条收尾并淡出。因此在模板中可以直接绑定button clickisLoading !isLoading {{ isLoading ? Stop : Start }} /button这段写法的演示可参见仓库中的 useNProgress/demo.vue它还展示了配合progress实时显示百分比b v-ifisLoading classml-2{{ ((progress || 0) * 100).toFixed(0) }}%/b底层联动原理从源码 packages/integrations/useNProgress/index.ts 可以看到isLoading的完整定义const isLoading computed({ set: load load ? nprogress.start() : nprogress.done(), get: () typeof progress.value number progress.value 1, })get的判定逻辑是只有当progress是数字且小于1时才算加载中。这与nprogress的语义一致——进度到达1即表示完成。由此isLoading既能手动写入驱动进度条也能从当前进度反推出加载状态供模板展示实现双向联动。控制进度百分比progress RefuseNProgress的第一个参数用于传入初始进度支持数字、Ref或 getter 函数MaybeRefOrGetternumber | null | undefinedconst { progress } useNProgress(0.5) function done() { progress.value 1.0 }要改变进度百分比只需设置progress.value n其中n是0..1之间的数字。默认参数为null表示进度条处于未知进度的流动状态。源码中的同步机制源码对进度的同步做了两层处理packages/integrations/useNProgress/index.tsconst setProgress nprogress.set nprogress.set (n: number) { progress.value n return setProgress.call(nprogress, n) } watchEffect(() { if (typeof progress.value number isClient) setProgress.call(nprogress, progress.value) })第一处拦截并重写nprogress.set。当nprogress内部因自动递增而更新进度时同步写回progress.value保证 Ref 始终反映真实进度第二处watchEffect反向驱动。当外部修改progress.value为数字时调用底层的set把进度推给nprogress且通过isClient来自vueuse/shared在服务端渲染时跳过 DOM 操作保证 SSR 安全。这种双向同步正是响应式封装的核心价值无论进度来自手动赋值、路由守卫还是nprogress内部逻辑progressRef 都能保持一致。配置项第二个参数 options可以通过第二个参数传入配置对象来定制行为例如设置进度条的最小初始值import { useNProgress } from vueuse/integrations/useNProgress useNProgress(null, { minimum: 0.1, // 其他 nprogress 配置项 })options的类型是UseNProgressOptions PartialNProgressOptionspackages/integrations/useNProgress/index.ts即nprogress全部配置项的浅层可选子集常见可用项包括配置项作用典型值minimum起始最小进度避免刚启动就跳到过高的百分比0.08起示例中使用0.1easing进度条运动的缓动函数名ease、linearspeed进度条动画速度毫秒200trickle是否启用自动递增的小步前进truetrickleSpeed自动递增的时间间隔毫秒200showSpinner是否显示右上角旋转加载圈true/falseparent进度条挂载的父容器元素body或某个 DOM 元素这些配置会通过nprogress.configure(options)一次性应用到全局packages/integrations/useNProgress/index.ts因此适合在应用初始化时统一配置。样式定制进度条的外观由nprogress自带的 CSS 控制。最直接的做法是修改nprogress.css中你喜欢的部分——通常只需查找并替换主题色#29dnprogress 的默认蓝色即可。仓库中的示例 useNProgress/style.css 提供了一套可参考的自定义样式它把主色替换为绿色#67d391保留#nprogress上pointer-events: none让点击事件穿透进度条并为进度条.bar设置了position: fixed、z-index: 1031、top: 0、height: 2px的顶部细条布局同时用.peg的box-shadow实现右侧发光拖尾效果。在自己的项目中引入自定义样式的方式与 demo 一致import { useNProgress } from vueuse/integrations/useNProgress import ./style.css如果需要把进度条限制在某个局部容器内而不是全屏顶部可以配合parent配置项指定容器并给容器添加nprogress-custom-parent类样式文件中有对应的绝对/相对定位规则。返回的完整 APIuseNProgress返回一个包含五个成员的对象packages/integrations/useNProgress/index.tsexport interface UseNProgressReturn { isLoading: WritableComputedRefboolean, boolean progress: Refnumber | null | undefined start: () NProgress done: (force?: boolean) NProgress remove: () void }成员类型说明isLoadingWritableComputedRefboolean读写双向置true调用start()置false调用done()读取时按progress 1判断progressRefnumber \| null \| undefined当前进度百分比0..1可读可写start() NProgress启动进度条透传自nprogress.startdone(force?: boolean) NProgress结束进度条force为true时强制立即完成remove() void移除进度条 DOM同时将progress重置为null注意done(force)支持一个可选的force参数传true时跳过淡出动画立即移除进度条。而remove的语义更彻底——源码中它同时把progress.value重置为null并调用nprogress.remove()packages/integrations/useNProgress/index.ts适合在组件卸载或需要彻底清除进度条时使用。生命周期自动清理一个值得关注的细节源码在函数末尾调用了tryOnScopeDispose(nprogress.remove)packages/integrations/useNProgress/index.ts。tryOnScopeDispose来自vueuse/shared导出见 packages/shared/index.ts它的语义是如果当前存在活跃的 effect scope如组件实例或手动effectScope就在作用域销毁时自动执行清理回调否则直接忽略。这意味着当使用useNProgress的组件被卸载或包裹它的effectScope被释放时进度条会自动移除无需手动清理避免进度条残留在页面上或产生内存泄漏。典型应用场景把以上能力组合起来最常见的落地场景是路由级加载指示。以 Vue Router 为例在全局前置守卫中结合isLoading即可实现跳转期间显示进度条import { useNProgress } from vueuse/integrations/useNProgress const { isLoading, done } useNProgress(null, { showSpinner: false }) router.beforeEach(() { isLoading.value true }) router.afterEach(() { done() })异步请求场景中也可以用progress精确反映上传/下载进度或对多个并行请求统一以start/done收口。由于isLoading、progress都是标准的响应式引用它们天然可以放进watch、计算属性或组件模板中与 Vue 3 的组合式 API 生态无缝衔接。小结useNProgress是nprogress的响应式薄封装核心价值在于把命令式 API 转换为isLoading/progress两个响应式引用并保持双向同步安装时需单独引入nprogress可选 peer 依赖样式可参考 style.css 自定义配置通过第二个参数传入通过重写nprogress.set与watchEffect实现进度双向同步借助tryOnScopeDispose实现组件卸载自动清理官方参考文档 useNProgress.md 与源码 index.ts、demo.vue 可直接对照阅读是理解该函数最权威的第一手资料。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐VueUse useNProgress在 Vue 3 中响应式驱动 nprogress 顶部进度条VueUse useNProgress在 Vue 3 中响应式驱动 nprogress 顶部进度条 useNProgress 是 VueUse Integra前端在 airi 中集成 VueUse useNProgress从响应式进度条到路由加载指示实战在 airi 中集成 VueUse useNProgress从响应式进度条到路由加载指示实战 useNProgress 是 VueUse 生态中针对 nproAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染VueUse useGamepad 实战在 Vue 3 应用中响应式接入 Gamepad APIAiri 仓库参考指南VueUse useGamepad 实战在 Vue 3 应用中响应式接入 Gamepad APIAiri 仓库参考指南 本文基于 Airi 开源仓库中的AI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染上一篇Claude Code 代码现代化插件code-modernization实战指南从 COBOL 遗留系统到可验证的新架构下一篇魔兽争霸3终极重生指南5分钟让经典游戏在Windows 11上流畅运行创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考