Quasar QAjaxBar 组件实战指南Ajax 请求进度条的实现原理与完整用法【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasarQAjaxBar 是 Quasar Framework 提供的加载进度条组件只要应用里有 Ajax 请求在进行它就会像 YouTube 那样在页面顶部或左右下自动显示一条加载进度条为耗时超过一两秒的 API 通信提供即时视觉反馈。本文以 ajax-bar.md 官方文档为骨架结合 QAjaxBar.js 源码、QAjaxBar.json 组件 API 定义、QAjaxBar.test.js 测试用例与 Basic.vue 官方示例系统讲解 QAjaxBar 的自动捕获机制、全部属性与事件、手动控制 API以及它在 XHR 拦截、Fetch 兼容性与无障碍访问方面的底层细节。读完本文你将能独立在 Quasar 应用中接入、定制并验证 Ajax 加载条。QAjaxBar 是什么在大多数移动应用甚至部分桌面应用中客户端几乎必然要通过 Ajax 请求与服务器通信。当一次请求可能耗时一两秒以上时良好的用户体验要求应用立即给出正在请求的反馈。QAjaxBar 正是为此而生它是一个显示加载进度条形如 YouTube 顶部的进度条的组件只要应用中有 Ajax 请求正在进行它就会自动出现——无论你用的是哪个 Ajax 库。与它在功能上互补的还有 Loading Bar Plugin官方文档明确指出如果希望更简单、更方便地提供 Ajax 加载条推荐优先使用 Loading Bar 插件——它内部其实正是封装了 QAjaxBar 组件见 LoadingBar.js 第 3 行对 QAjaxBar 的导入与第 57 行的渲染调用由插件负责在全局节点挂载组件、由$q.loadingBar暴露统一 API。快速上手Basic 示例QAjaxBar 默认会自动捕获hijack应用中的 Ajax 请求并驱动进度条。官方示例 Basic.vue 为了演示效果通过skip-hijack关闭了自动捕获改为手动触发template div classq-pa-md q-ajax-bar refbarRef positionbottom coloraccent size10px skip-hijack / q-btn colorprimary labelTrigger clicktrigger / /div /template script setup import { useTemplateRef } from vue const barRef useTemplateRef(barRef) // we manually trigger it (this is not needed if we // dont skip Ajax calls hijacking) function trigger() { barRef.value.start() setTimeout( () { barRef.value?.stop() }, Math.random() * 3000 1000 ) } /script该示例展示了本组件区别于纯插件方案的关键点通过模板引用ref拿到组件实例后可以调用实例上暴露的start()、stop()、increment()方法。示例将进度条放在页面底部positionbottom设置10px粗细默认是 2px并使用自定义颜色accent——这正是原文档所说的多位置可选 自定义尺寸与颜色的典型配置。注意注释中的关键提示只要没有跳过 Ajax 拦截就不需要手动调用start()/stop()组件会自动完成。完整 API属性、事件与方法以下内容完整继承自官方文档引用的 QAjaxBar.json 组件 API 定义并补充了源码中的实现细节与默认值。属性Props属性类型默认值说明positionStringtop进度条在窗口中的显示位置可选top、right、bottom、left。源码 QAjaxBar.js 用positionValues数组做合法性校验sizeString2px进度条粗细。位于顶部/底部时作用于height位于左/右时作用于width见源码sizeProp计算逻辑QAjaxBar.jscolorString—进度条颜色。源码会拼接bg-${color}类名QAjaxBar.js即复用 Quasar 色彩体系例如primary、accent、orange等reverseBooleanfalse反转进度方向skip-hijackBooleanfalse跳过 Ajax 自动捕获非响应式属性组件挂载时一次性读取。置为true后进度条完全由手动方法驱动hijack-filterFunction—过滤函数接收参数urlString被触发的 URL返回 Boolean 决定该 URL 是否触发start()stop()。默认对所有 URL 生效事件Events事件说明start进度条被触发出现时发出每次从隐藏进入显示状态只发一次stop进度条完成任务、即将隐藏时发出方法Methods组件挂载后通过模板引用调用源码在 QAjaxBar.js 用Object.assign(proxy, { start, stop, increment })暴露这三个方法方法参数返回值说明start(speed)speedNumber默认300即进度自动递增的时间间隔毫秒传入0可禁用自动递增Number当前同时进行的会话session数量。通知进度条正在等待一个新进程结束increment(amount)amountNumber递增幅度0 x 100Number当前会话数量。手动触发一次进度递增stop()无Number当前会话数量。通知进度条一个正在等待的进程已结束手动控制与多会话计数机制与 QAjaxBar 的自动模式不同手动模式下每次开始一个新事件都要调用一次start()每次事件结束都要调用一次stop()。原文档特别强调如果多个事件同时进行start与stop事件仍然只会各触发一次——分别对应进度条真正显示和真正隐藏的时刻。从源码可以印证这一点start()内部用sessions计数器记录并发会话数QAjaxBar.js只有sessions从 0 变为 1 时才执行真正的显示逻辑并emit(start)stop()则递减sessions只有减到 0 时才会走隐藏流程并emit(stop)QAjaxBar.js。start()和stop()的返回值就是当前活跃会话数方便调用方自行判断状态。进度值本身是合成的源码中的inc()函数根据当前进度值所在区间使用不同速率的随机增量0–25% 时每次加 3~699% 以上不再增加并通过planNextStep()按speed毫秒的间隔定时递增QAjaxBar.js、QAjaxBar.js。也就是说进度条并不反映真实网络传输进度而是一种永远接近但不会真正到 100%的等待暗示直到stop()被调用时才瞬间推进到 100% 并淡出。测试用例 QAjaxBar.test.js 对事件语义做了明确验证调用一次start(0)后start事件恰好发射一次随后调用stop()后stop事件恰好发射一次L142-L152 验证increment(10)后aria-valuenow变为10L154-L165 验证stop()后进度被置为100。Ajax 自动捕获拦截 XHR 的底层原理QAjaxBar 的核心能力是自动捕获 Ajax 请求。源码揭示了它的实现方式在onMounted时只要未设置skip-hijack调用highjackAjax()通过改写XMLHttpRequest.prototype.open在全局层面拦截所有 XHR 请求QAjaxBar.js请求调用xhr.open(method, url, ...)时会给该 XHR 实例注册loadstart与loadend两个一次性事件监听loadstart触发时遍历当前所有已挂载的 QAjaxBar 实例逐一用其hijackFilter判断 URL 是否匹配无过滤函数则全部匹配匹配则调用entry.start()并收集其stop回调loadend触发时按逆序调用收集到的stop()进度条随之收尾。组件卸载时调用restoreAjax()恢复原始的open实现QAjaxBar.js。整个过程通过模块级的stack数组与highjackCount计数支持多个 QAjaxBar 实例共存只有第一个实例真正改写原型最后一个实例卸载时才还原避免相互干扰。测试 QAjaxBar.test.js 验证了skip-hijack: true时XMLHttpRequest.prototype.open保持原样L81-L97 则验证hijackFilter会被以真实 URL 调用且返回false时不会触发start事件。重要限制仅支持 XHR不支持 Fetch原文档明确提示自动捕获机制专门针对基于XMLHttpRequest (XHR)的库设计。如果你使用浏览器原生Fetch API进度条不会自动触发。这一点在源码中体现得淋漓尽致文件顶部直接声明const xhr __QUASAR_SSR_SERVER__ ? null : XMLHttpRequest整套拦截逻辑完全建立在xhr.prototype.open之上QAjaxBar.js。另外在 SSR服务端渲染环境下该变量为null意味着自动捕获逻辑不会在服务端执行。因此使用 Fetch 或基于 Fetch 的请求库如 axios 的 fetch 适配器时请改用 Loading Bar 插件 手动调用start()/stop()或在请求封装层统一触发。Ajax 过滤器只对特定 URL 生效如果希望 QAjaxBar 仅对部分 URL 触发默认行为是对所有 URL 生效可以使用hijackFilter属性。它接收被请求的 URL 字符串返回true才触发进度条template q-ajax-bar :hijack-filtermyFilterFn / /template script setup function myFilterFn(url) { // example (only https://my-service.com/* should trigger) return /^https:\/\/my-service\.com/.test(url) } /script结合源码来看过滤判断发生在loadstart回调里entry.hijackFilter.value null || entry.hijackFilter.value(url)QAjaxBar.js。组件内部用computed(() props.hijackFilter || null)包装过滤函数过滤函数会收到完整的请求 URL。官方 playground 示例 ajax-bar.vue 展示了一个实用场景用正则让只有包含/server的 URL 触发、而/second-server不触发同时实时打印判定结果。外观定制位置、尺寸、颜色与方向位置position支持top/right/bottom/left四个方位进度条贴住窗口对应边缘。样式类为q-loading-bar--top等由 QAjaxBar.sass 定义水平位置宽度 100%、垂直位置高度 100%并通过position: fixed与z-index: $z-max悬浮于所有内容之上。尺寸size默认2px水平布局时作为height、垂直布局时作为width写入内联样式源码 QAjaxBar.js。测试用例验证了size: 4pxposition: right时样式里出现width: 4pxQAjaxBar.test.js。颜色color复用 Quasar 调色板最终渲染为bg-${color}类。未指定时SASS 里默认背景为$red红色。测试用color: primary验证类名包含bg-primaryQAjaxBar.test.js。方向reverse可反转进度推进方向。源码中水平位置还会考虑 RTL 语言方向当$q.lang.rtl为真且位置为 top/bottom 时实际反转逻辑会自动取反QAjaxBar.js保证 RTL 布局下进度方向语义正确。位置与方向测试QAjaxBar.test.js逐一断言了四个方位对应 CSS 类的生成可作为你自定义样式时的参考依据。无障碍访问v2.25从 v2.25 开始QAjaxBar 增加了无障碍支持实现在源码的attributes计算属性中QAjaxBar.js运行期间进度条元素暴露roleprogressbar以及常规的aria-valuemin0、aria-valuemax100、aria-valuenow当前合成进度值空闲时元素以aria-hiddentrue对辅助技术隐藏。需要特别说明的是进度值是合成的——由定时器递增而非真实测量官方文档因此将其定性为装饰性反馈。这意味着使用时应当为进度条补充aria-label例如 Page loading让屏幕阅读器用户知道这一区域代表什么对于真正需要用户知晓的长时间操作自行通过 live region实时区域播报开始与完成因为进度条自身的开始和完成不会被辅助技术自动播报。与 Loading Bar 插件的关系QAjaxBar 是组件Loading Bar 是封装它的全局插件。若不需要在模板中手动放置组件推荐按官方建议使用插件方案// 全局配置quasar.config 文件 // framework: { config: { loadingBar: { color: purple, size: 15px, position: bottom } } } import { LoadingBar } from quasar // 组件外部含 boot 文件 LoadingBar.setDefaults({ color: purple, size: 15px, position: bottom }) // 组件内部 import { useQuasar } from quasar const $q useQuasar() $q.loadingBar.start() $q.loadingBar.stop() $q.loadingBar.increment(value)插件同样支持通过setDefaults({ hijackFilter(url) { ... } })配置 URL 过滤器内部实现与 QAjaxBar 的hijackFilter完全一致见 loading-bar.md 与 LoadingBar.js。此外官方文档提醒UMD 版本默认安装所有组件/指令/插件包括 LoadingBar若想关闭其对 Ajax 流量的监听需显式配置loadingBar: { skipHijack: true }。小结与最佳实践默认开箱即用在模板中放入q-ajax-bar /XHR 类请求即可自动驱动进度条无需任何手动代码。按需过滤通过hijackFilter限定触发 URL多个 QAjaxBar 实例可共存且互不干扰。手动模式设置skip-hijack后务必为每个事件成对调用start()/stop()可传入速度参数并留意并发会话计数与一次 start 事件、一次 stop 事件的语义。Fetch 场景自动捕获仅覆盖 XHRFetch 请求需手动触发或改走插件 封装层方案。无障碍给进度条补充aria-label并对关键长任务使用 live region 播报不要把合成进度当作精确状态。更省心的选择若只需全局加载条直接使用 Loading Bar Plugin它内部就是封装好的 QAjaxBar。相关源码与测试均可在本仓库中直接查阅组件实现、API 定义、样式、单元测试、官方示例、playground 演示页。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考