最新Quasar 指南5：30021字带你了解Quasar插件核心用法及实战 - Quasar 完全教程：从基础到实战 --Ryan

Quasar Addressbar Color 插件教程

一、核心作用

这个插件专门用来修改移动端浏览器地址栏 / 状态栏的背景颜色（比如 Chrome 移动端顶部的地址栏、Safari 状态栏），让页面风格更统一，仅在移动端生效，PC 端无效果。

二、快速上手

1. 安装（Quasar V2+）

无需额外安装，插件已内置在 Quasar 框架中，直接注册即可。

2. 注册插件

在项目的quasar.config.js中启用：

// quasar.config.js module.exports = { framework: { plugins: [ 'AddressbarColor' // 启用插件 ] } }

3. 基本使用

方式 1：全局初始化（设置默认颜色）

在 // 文件: /src/boot/addressbar-color.js 或根组件中设置初始颜色：

import { AddressbarColor } from 'quasar' // 直接设置颜色（支持 Hex/RGB/RGBA） AddressbarColor.set('#ff0000') // 红色 AddressbarColor.set('rgb(255, 0, 0)') AddressbarColor.set('rgba(255, 0, 0, 0.5)')

方式 2：页面内动态修改

在 Vue 组件中根据页面需求动态切换颜色：

<template> <div> <button @click="changeColor">切换地址栏颜色</button> </div> </template> <script> import { AddressbarColor } from 'quasar' export default { methods: { changeColor() { AddressbarColor.set('#00ff00') // 切换为绿色 } } } </script>

三、关键特性

1. 自动适配主题：如果设置auto参数，会自动匹配页面根元素的背景色：

   AddressbarColor.set('auto')

2. 透明度处理：部分浏览器不支持透明地址栏，插件会自动降级为不透明颜色。
3. 仅移动端生效：PC 端调用无任何效果，无需额外判断设备。

四、注意事项

1. 颜色值建议与页面顶部导航栏颜色一致，保证视觉统一。
2. Safari iOS 对地址栏颜色支持有限，部分颜色可能被系统调整。
3. 避免使用过于鲜艳的颜色，影响地址栏文字可读性（浏览器会自动切换文字颜色为黑 / 白）。

五、实战示例（页面切换时改颜色）

在路由守卫中根据页面动态设置地址栏颜色：

// src/router/index.js import { AddressbarColor } from 'quasar' router.beforeEach((to, from, next) => { // 不同页面设置不同颜色 if (to.path === '/home') { AddressbarColor.set('#1976d2') // 蓝色 } else if (to.path === '/about') { AddressbarColor.set('#4caf50') // 绿色 } next() })

Quasar App Fullscreen 插件教程（Quasar CLI 版）

一、插件介绍

App Fullscreen 插件用于管理浏览器 / 设备的全屏模式，支持进入 / 退出全屏、监听全屏状态变化、指定元素全屏显示，兼容桌面端与移动端（部分移动端浏览器限制需用户交互触发）。

二、安装与启用（Quasar CLI 必看）

1. 启用插件

Quasar CLI 项目中插件内置，无需额外安装，直接在quasar.config.js中注册：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: [ 'AppFullscreen' // 启用 AppFullscreen 插件 ] } } }

2. 导入插件（组件内使用）

在需要控制全屏的 Vue 组件中导入：

import { AppFullscreen } from 'quasar'

三、核心 API（文档原生方法 / 属性）

1. 基础方法

2. 状态与事件

四、基础使用示例（文档同步场景）

场景 1：整个页面全屏切换

<!-- src/pages/FullscreenPage.vue --> <template> <q-page> <h1>全屏测试页面 label="切换全屏"</h1> <q-btn @click="toggleFullscreen" :label="AppFullscreen.isActive ? '退出全屏' : '进入全屏'" /> </q-page> </template> <script setup> import { AppFullscreen } from 'quasar' // 切换全屏状态 const toggleFullscreen = async () => { const success = await AppFullscreen.toggle() if (!success) { console.log('全屏切换失败（可能被浏览器阻止）') } } </script>

场景 2：指定元素全屏显示

<template> <q-page> <!-- 目标元素 --> <div ref="videoContainer" style="width: 100%; height: 500px; background: #000;"> <!-- 示例：视频元素 --> <video src="demo.mp4" controls></video> </div> <q-btn label="让视频容器全屏" @click="elementFullscreen" /> </q-page> </template> <script setup> import { ref } from 'vue' import { AppFullscreen } from 'quasar' const videoContainer = ref(null) // 指定元素全屏 const elementFullscreen = async () => { // 传入 DOM 元素（通过 ref 获取） const success = await AppFullscreen.request(videoContainer.value) if (!success) { console.log('元素全屏失败') } } </script>

五、文档关键注意事项（原文同步）

1. 触发限制：浏览器要求全屏操作必须由用户交互（如点击按钮）触发，无法通过代码自动执行（如页面加载时直接全屏）；
2. 移动端兼容：部分移动端浏览器（如 iOS Safari）不支持指定元素全屏，仅支持整个页面全屏；
3. 权限问题：如果页面嵌入在 iframe 中，需给 iframe 添加allowfullscreen属性才能使用全屏功能；
4. 响应式状态：AppFullscreen.isActive是响应式属性，可直接在模板中绑定（如示例 1 中动态修改按钮文字）；
5. 错误处理：所有异步方法返回 Promise，需通过await或.then()处理成功 / 失败状态，避免静默失败。

六、高级场景（文档拓展示例）

场景：全屏时隐藏导航栏，退出时显示

<template> <q-layout> <!-- 导航栏：全屏时隐藏 --> <q-header v-show="!AppFullscreen.isActive"> <q-toolbar> <q-toolbar-title>普通模式标题</q-toolbar-title> </q-toolbar> </q-header> <q-page-container> <q-page> <q-btn @click="toggleFullscreen" label="切换全屏" /> </q-page> </q-page-container> </q-layout> </template> <script setup> import { AppFullscreen } from 'quasar' const toggleFullscreen = () => { AppFullscreen.toggle() } </script>

七、调试与验证

1. 运行 Quasar 开发服务：quasar dev；
2. 点击触发全屏的按钮，验证是否进入全屏（桌面端按 F11 可对比，移动端需在真实设备测试）；
3. 检查控制台是否有失败日志（如浏览器阻止全屏时的提示）。

Quasar App Visibility 插件教程（Quasar CLI 版）

一、插件介绍

App Visibility 插件用于监听应用 / 页面的可见性状态（如用户切换标签页、最小化浏览器、锁屏等导致页面隐藏 / 显示），支持全局监听与响应式状态获取，兼容桌面端和移动端。

核心作用：判断页面是否处于 “活跃可见状态”，可用于暂停 / 恢复视频播放、停止 / 启动定时器、统计用户活跃时长等场景。

二、安装与启用（Quasar CLI 必看）

1. 启用插件

Quasar CLI 项目中插件内置，无需额外安装，直接在quasar.config.js中注册：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: [ 'AppVisibility' // 启用 AppVisibility 插件 ] } } }

2. 导入插件（组件内使用）

在需要监听页面可见性的 Vue 组件中导入：

import { AppVisibility } from 'quasar'

三、核心 API（文档原生属性 / 方法）

1. 响应式状态

2. 事件监听

四、基础使用示例（文档同步场景）

场景 1：响应式绑定状态（模板中直接使用）

<!-- src/pages/VisibilityPage.vue --> <template> <q-page> <div>当前页面状态：{{ AppVisibility.appVisible ? '可见（前台）' : '隐藏（后台）' }}</div> <!-- 示例：页面隐藏时暂停视频 --> <video ref="videoRef" src="demo.mp4" controls :autoplay="AppVisibility.appVisible" ></video> </q-page> </template> <script setup> import { AppVisibility } from 'quasar' </script>

场景 2：监听可见性变化（业务逻辑处理）

<template> <q-page> <q-btn label="模拟启动定时器" @click="startTimer" /> <div>定时器计数：{{ count }}</div> </q-page> </template> <script setup> import { ref, onMounted, onUnmounted } from 'vue' import { AppVisibility } from 'quasar' const count = ref(0) let timer = null // 启动定时器 const startTimer = () => { if (timer) clearInterval(timer) timer = setInterval(() => { // 仅页面可见时计数 if (AppVisibility.appVisible) { count.value++ } }, 1000) } // 定义可见性变化处理器 const handleVisibilityChange = (isVisible) => { console.log('页面可见性变化：', isVisible ? '进入前台' : '进入后台') // 示例：页面隐藏时清除定时器，显示时重启 if (!isVisible && timer) { clearInterval(timer) timer = null } else if (isVisible && !timer) { startTimer() } } // 挂载时绑定监听，卸载时移除 onMounted(() => { AppVisibility.on('visibility-change', handleVisibilityChange) }) onUnmounted(() => { AppVisibility.off('visibility-change', handleVisibilityChange) if (timer) clearInterval(timer) }) </script>

场景 3：全局监听（入口文件中使用）

在src/main.js中全局监听页面可见性，用于全局业务控制：

// src/main.js import { createApp } from 'vue' import { Quasar, AppVisibility } from 'quasar' import App from './App.vue' const app = createApp(App) app.use(Quasar, { plugins: { AppVisibility } }) // 全局监听页面可见性 AppVisibility.on('visibility-change', (isVisible) => { if (!isVisible) { console.log('应用进入后台，暂停所有异步任务') // 全局暂停逻辑：如停止轮询、暂停音频播放等 } else { console.log('应用回到前台，恢复异步任务') // 全局恢复逻辑 } }) app.mount('#app')

五、文档关键注意事项（原文同步）

1. 触发场景：以下操作会触发可见性变化：
   • 切换浏览器标签页（当前标签隐藏 / 显示）
   • 最小化 / 还原浏览器窗口
   • 设备锁屏 / 解锁（移动端 / 桌面端）
   • 切换到其他应用（移动端）
2. 兼容性：支持所有现代浏览器（Chrome、Firefox、Safari、Edge 等），无 IE 支持；
3. 响应式特性：AppVisibility.appVisible是响应式属性，可直接在 Vue 模板或响应式逻辑（如 watch）中使用；
4. 监听清理：使用AppVisibility.off()移除监听时，必须传入与绑定相同的handler函数（避免内存泄漏）；
5. 移动端特殊：部分移动端浏览器在应用后台时，JavaScript 执行可能被节流（如定时器延迟），依赖可见性判断可优化体验。

六、高级场景（文档拓展示例）

场景：页面隐藏时暂停 API 轮询，显示时恢复

<script setup> import { ref, onMounted, onUnmounted } from 'vue' import { AppVisibility, useQuasar } from 'quasar' const $q = useQuasar() let pollInterval = null // 模拟 API 轮询函数 const fetchData = async () => { try { const res = await fetch('/api/data') const data = await res.json() console.log('轮询获取数据：', data) } catch (err) { $q.notify({ type: 'negative', message: '轮询失败' }) } } // 可见性变化处理 const handleVisibility = (isVisible) => { if (isVisible) { // 恢复轮询（每5秒一次） pollInterval = setInterval(fetchData, 5000) // 立即获取一次数据 fetchData() } else { // 暂停轮询 clearInterval(pollInterval) pollInterval = null } } onMounted(() => { // 初始可见时启动轮询 if (AppVisibility.appVisible) { pollInterval = setInterval(fetchData, 5000) } // 绑定监听 AppVisibility.on('visibility-change', handleVisibility) }) onUnmounted(() => { AppVisibility.off('visibility-change', handleVisibility) clearInterval(pollInterval) }) </script>

七、调试与验证

1. 运行 Quasar 开发服务：quasar dev；
2. 验证场景：
   • 切换浏览器标签页，查看控制台日志是否触发可见性变化；
   • 最小化浏览器窗口，检查定时器 / 轮询是否暂停；
   • 移动端测试：切换到其他应用后返回，验证业务逻辑是否恢复。

Quasar BottomSheet（底部对话框）插件核心总结

一、核心定位

BottomSheet 是从屏幕底部向上滑动的对话框插件，用于展示操作选项（替代部分菜单场景），不支持导航功能。它始终悬浮于所有组件上方，触发后背景变暗聚焦选项，需手动关闭才能操作底层内容。

二、安装启用（Quasar CLI）

无需额外安装，在quasar.config.js中注册即可：

// quasar.config.js module.exports = { framework: { plugins: ['BottomSheet'] // 启用插件 } }

三、核心用法

1. 调用方式

• 组件外使用：导入BottomSheet直接调用create方法
• 组件内使用：通过useQuasar获取$q实例，调用$q.bottomSheet()
• 均返回操作对象，支持后续控制

2. 展示形式

支持两种核心布局，适配不同场景：

• 列表形式（List BottomSheet）：适合展示带描述的选项
• 网格形式（Grid BottomSheet）：适合图标化、简洁的选项集合

3. 附加特性

• 支持深色模式（Dark mode）
• 可搭配图标、头像增强视觉效果
• 快捷键支持：桌面端按 ESC 键关闭，Cordova 应用按设备后退按钮自动关闭

Quasar Cookies 插件教程（Quasar CLI 版）

一、插件介绍

Cookies 插件是对浏览器document.cookie的友好封装，提供简洁的 API 实现 Cookie 的增、删、改、查，支持设置过期时间、路径、域、安全标志等参数，兼容所有现代浏览器。

核心优势：无需手动拼接 Cookie 字符串，通过对象参数配置即可完成复杂操作，内置过期时间格式化（支持天数、日期对象等）。

二、安装与启用（Quasar CLI 必看）

1. 启用插件

Quasar CLI 项目中插件内置，无需额外安装，直接在quasar.config.js中注册：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: [ 'Cookies' // 启用 Cookies 插件 ] } } }

2. 导入插件（组件内使用）

在需要操作 Cookie 的 Vue 组件中导入：

import { Cookies } from 'quasar'

三、核心 API（文档原生方法 / 参数）

1. 基础操作方法

2.options配置对象（设置 / 删除时）

四、基础使用示例（文档同步场景）

场景 1：设置与获取 Cookie

<!-- src/pages/CookiesPage.vue --> <template> <q-page> <q-btn label="设置用户信息 Cookie" @click="setUserCookie" /> <q-btn label="获取用户信息 Cookie" @click="getUserCookie" /> <div>用户 Cookie：{{ userCookie }}</div> </q-page> </template> <script setup> import { ref } from 'vue' import { Cookies } from 'quasar' const userCookie = ref(null) // 设置 Cookie（7 天后过期，仅 HTTPS 下传输） const setUserCookie = () => { Cookies.set('user_info', { id: 1, name: '张三' }, { expires: 7, // 7 天过期 secure: process.env.NODE_ENV === 'production', // 生产环境启用 secure sameSite: 'Lax' }) } // 获取 Cookie const getUserCookie = () => { userCookie.value = Cookies.get('user_info') } </script>

场景 2：删除 Cookie 与判断存在性

<template> <q-page> <q-btn label="删除用户 Cookie" @click="removeUserCookie" /> <q-btn label="检查 Cookie 是否存在" @click="checkCookieExists" /> <div>Cookie 存在状态：{{ cookieExists }}</div> </q-page> </template> <script setup> import { ref } from 'vue' import { Cookies } from 'quasar' const cookieExists = ref(false) // 删除 Cookie（需与设置时的 path/domain 一致） const removeUserCookie = () => { Cookies.remove('user_info', { path: '/' // 必须与设置时的 path 一致（默认 '/'） }) } // 检查 Cookie 存在性 const checkCookieExists = () => { cookieExists.value = Cookies.has('user_info') } </script>

场景 3：清除所有 Cookie 与批量操作

五、文档关键注意事项（原文同步）

1. 值序列化：Cookies.set()会自动将非字符串值（对象、数组等）序列化为 JSON 字符串，Cookies.get()会自动反序列化，无需手动处理；
2. 过期时间：
   • 传入 Number 表示 “从现在开始的天数”（如1表示 1 天后过期）；
   • 传入 Date/Dayjs 对象表示具体过期时间（如new Date('2025-12-31')）；
   • 不设置expires则为会话 Cookie（浏览器关闭后失效）；
3. 删除 Cookie 注意事项：
   • 删除时必须保证path/domain与设置时完全一致，否则删除失败；
   • 若设置了secure: true，仅能在 HTTPS 环境下删除；
4. httpOnly 限制：若设置httpOnly: true，JavaScript 无法访问该 Cookie（Cookies.get()返回null），仅服务端可操作；
5. 跨域 Cookie：domain配置需符合浏览器跨域规则（如不能设置非当前域名的域），sameSite: 'None'需配合secure: true；
6. 服务端渲染（SSR）：在 SSR 环境中，Cookies 插件会自动适配服务端上下文，无需额外配置。

六、高级场景（文档拓展示例）

场景：设置永久 Cookie（10 年过期）

// 设置 10 年过期的 Cookie Cookies.set('token', 'abc123', { expires: 365 * 10, // 10 年 = 3650 天 path: '/', secure: true, sameSite: 'Strict' })

场景：按域名设置 Cookie（支持子域名）

// 使 Cookie 在 example.com 及其所有子域名（如 a.example.com）生效 Cookies.set('global_setting', 'dark_mode', { domain: '.example.com', // 注意前缀点号 expires: 30 })

七、调试与验证

1. 运行 Quasar 开发服务：quasar dev；
2. 打开浏览器开发者工具（F12）→ Application → Cookies → 查看当前域名下的 Cookie 列表；
3. 验证操作：设置 Cookie 后刷新页面，检查是否存在；删除后检查是否消失。

Quasar Dark（暗色模式）插件核心总结

一、核心作用

快速实现应用的暗色 / 浅色模式切换，自动适配 Quasar 内置组件样式，支持手动控制、自动适配系统主题，无需额外编写大量样式代码。

二、安装说明

插件已内置在 Quasar 框架中，无需手动安装启用，可直接在项目中使用。

三、核心 API 与用法

1. 状态获取

• 组件内：通过useQuasar()获取$q.dark，可访问$q.dark.isActive（布尔值，当前是否为暗色模式）、$q.dark.mode（配置状态："auto"/true/false）。
• 组件外（非 SSR）：导入Dark直接访问Dark.isActive、Dark.mode（SSR 环境下此方式无效）。

2. 模式设置

• 组件内：$q.dark.set(val)，val支持true（强制暗色）、false（强制浅色）、"auto"（适配系统主题）；也可通过$q.dark.toggle()切换模式。
• 组件外（非 SSR）：Dark.set(val)或Dark.toggle()。
• 全局配置（quasar.config.js）：在framework.config.dark中设置默认值（"auto"/true/false）。
• SSR 环境：建议在src/App.vue中通过$q.dark.set(val)设置，避免使用组件外导入方式。

3. 状态监听

通过 Vue 的watch监听$q.dark.isActive变化，触发模式切换后的业务逻辑（如修改自定义样式、保存用户偏好）。

四、关键注意事项

1. 禁止手动给$q.dark.isActive或$q.dark.mode赋值，必须使用set()方法修改状态。
2. SSR 环境建议避免设置为"auto"，否则可能出现客户端接管后主题闪烁（SSR 无法推断客户端主题偏好）。
3. 组件外导入Dark仅适用于非 SSR 构建，SSR 环境需通过组件内$q.dark或全局配置设置。

Quasar Dialog 插件教程（Quasar CLI 版）

一、插件介绍

Dialog 插件用于创建各种类型的弹窗（提示框、确认框、自定义弹窗等），替代浏览器原生alert/confirm/prompt，支持自定义样式、按钮、内容，兼容桌面端与移动端，始终悬浮于应用顶层。

二、安装与启用（Quasar CLI 必看）

插件内置，无需额外安装，直接在quasar.config.js中注册启用：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: [ 'Dialog' // 启用 Dialog 插件 ] } } }

三、核心使用方式

1. 基础调用（组件内）

通过useQuasar()获取$q.dialog实例调用，支持预定义弹窗（Alert/Confirm/Prompt）和自定义弹窗：

<script setup> import { useQuasar } from 'quasar' const $q = useQuasar() </script>

2. 预定义弹窗类型（文档原生）

（1）Alert 提示框（仅确认按钮）

// 基础用法 $q.dialog({ title: '提示', message: '操作成功！', ok: { label: '确定', color: 'primary' } }).onOk(() => { console.log('用户点击确定') }) // 简化版（仅消息） $q.dialog.alert('操作失败，请重试！')

（2）Confirm 确认框（确认 + 取消按钮）

// 基础用法 $q.dialog({ title: '确认删除', message: '是否确定删除该数据？删除后不可恢复', ok: { label: '删除', color: 'negative' }, cancel: { label: '取消', color: 'grey' } }).onOk(() => { console.log('用户确认删除') }).onCancel(() => { console.log('用户取消删除') }) // 简化版 $q.dialog.confirm('是否退出登录？') .then(() => console.log('确认退出')) .catch(() => console.log('取消退出'))

（3）Prompt 输入框（带输入的确认框）

$q.dialog({ title: '修改昵称', message: '请输入新的昵称', prompt: { model: '', // 输入框初始值 type: 'text', // 输入框类型（text/number/email等） placeholder: '请输入昵称' }, ok: { label: '保存' }, cancel: { label: '取消' } }).onOk((data) => { console.log('用户输入的昵称：', data) // data 为输入框值 }) // 简化版 $q.dialog.prompt('请输入验证码') .then((code) => console.log('验证码：', code)) .catch(() => console.log('取消输入'))

3. 自定义弹窗（文档核心特性）

支持自定义内容、按钮、样式，甚至嵌入 Quasar 组件：

$q.dialog({ title: '自定义弹窗', // 自定义内容（支持 HTML 或 Vue 组件） message: ` <div style="padding: 16px;"> <q-input v-model="form.phone" label="手机号" type="tel"></q-input> <q-input v-model="form.code" label="验证码" type="number" style="margin-top: 12px;"></q-input> </div> `, // 传递数据到弹窗内 form: { phone: '', code: '' }, // 自定义按钮 buttons: [ { label: '取消', color: 'grey', handler: () => {} }, { label: '提交', color: 'primary', handler: (data) => { console.log('提交的数据：', data.form) // 可返回 Promise 实现异步验证 return new Promise((resolve) => { setTimeout(() => { if (data.form.phone) resolve() else $q.notify({ type: 'negative', message: '手机号不能为空' }) }, 500) }) } } ], // 其他配置 persistent: true, // 点击外部不关闭弹窗 maximized: false, // 是否最大化弹窗 fullWidth: true, // 全屏宽度（移动端） breakpoint: 'sm' // 响应式断点（sm/md/lg） })

4. 弹窗关闭与回调（文档细节）

• onOk(callback)：点击确认按钮触发
• onCancel(callback)：点击取消 / 关闭按钮触发
• onDismiss(callback)：弹窗关闭时触发（无论哪种方式）
• 手动关闭：const dialogInstance = $q.dialog({...}); dialogInstance.hide()

四、核心配置项（文档完整参数）

五、文档关键注意事项

1. 异步处理：按钮 handler 可返回 Promise，弹窗会等待 Promise 完成后再关闭（用于异步验证）；
2. Vue 组件嵌入：自定义弹窗内容支持嵌入 Quasar 组件，但需确保组件已全局注册或通过components配置；
3. 响应式适配：breakpoint配置可控制弹窗在不同屏幕尺寸下的显示方式（如移动端全屏）；
4. ESC 键关闭：仅当persistent: false时，按 ESC 键可关闭弹窗；
5. 组件外调用：非组件环境（如工具函数）可直接导入Dialog调用：

   import { Dialog } from 'quasar' Dialog.alert('全局提示')

六、实战示例（文档拓展示例）

场景：表单提交前确认（带异步验证）

const submitForm = () => { $q.dialog({ title: '提交确认', message: '是否提交当前表单数据？', ok: { label: '提交', color: 'primary' }, cancel: { label: '取消' }, persistent: true }).onOk(async () => { try { await api.submitForm(formData) $q.notify({ type: 'positive', message: '提交成功' }) } catch (err) { $q.notify({ type: 'negative', message: '提交失败：' + err.message }) } }) }

Quasar Loading 插件教程（Quasar CLI 版）

一、插件介绍

Loading 插件用于创建全局加载遮罩（全屏 / 局部），替代手动编写加载动画，支持自定义样式、文案、图标，适配异步操作（如接口请求）的加载状态提示，兼容桌面端与移动端。

二、安装与启用（Quasar CLI 必看）

插件内置，无需额外安装，直接在quasar.config.js中注册启用：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: [ 'Loading' // 启用 Loading 插件 ] } } }

三、核心使用方式

1. 全局 Loading（全屏遮罩）

（1）基础调用（组件内）

通过useQuasar()获取$q.loading实例，支持show()/hide()控制显示 / 隐藏：

<script setup> import { useQuasar } from 'quasar' const $q = useQuasar() // 显示全局 Loading const showLoading = () => { $q.loading.show({ message: '加载中...', // 加载文案 spinner: 'dots', // 加载动画类型（见文档支持的 spinner 类型） backgroundColor: 'rgba(0, 0, 0, 0.7)', // 背景遮罩颜色 spinnerColor: 'white' // 动画颜色 }) } // 隐藏全局 Loading const hideLoading = () => { $q.loading.hide() } // 示例：模拟接口请求 const fetchData = async () => { showLoading() try { await new Promise(resolve => setTimeout(resolve, 2000)) // 模拟异步请求 console.log('数据加载完成') } finally { hideLoading() // 无论成功失败都隐藏 Loading } } </script>

（2）简化调用（直接传文案）

// 仅显示文案，使用默认配置 $q.loading.show('正在提交...')

（3）组件外调用（全局工具）

在非组件文件（如 api 封装文件）中直接导入Loading：

// src/utils/api.js import { Loading } from 'quasar' // 显示 Loading Loading.show({ message: '请求中...' }) // 隐藏 Loading Loading.hide()

2. 局部 Loading（指定元素遮罩）

通过$q.loading.show()的target参数指定遮罩元素（需传入 DOM 元素或组件 ref）：

<template> <div ref="containerRef" style="width: 500px; height: 300px; border: 1px solid #eee;"> <!-- 需加载的内容 --> <div v-if="data">加载完成：{{ data }}</div> </div> <q-btn label="加载局部内容" @click="loadPartialData" /> </template> <script setup> import { ref } from 'vue' import { useQuasar } from 'quasar' const $q = useQuasar() const containerRef = ref(null) const data = ref(null) const loadPartialData = async () => { // 仅遮罩指定元素 $q.loading.show({ target: containerRef.value, // 目标元素 message: '局部加载中...', spinner: 'audio' }) try { await new Promise(resolve => setTimeout(resolve, 1500)) data.value = '局部内容加载完成' } finally { $q.loading.hide() } } </script>

3. 配置项详解（文档完整参数）

四、关键特性（文档原文）

1. 单例模式：全局 Loading 为单例，多次调用show()只会更新配置，不会重复显示；hide()只需调用一次即可隐藏。
2. 延迟显示：通过delay参数避免短时间异步操作导致的 Loading 闪烁（如接口请求 100ms 完成，无需显示 Loading）。
3. 自动清理：hide()会自动清理所有配置，无需手动重置。
4. SSR 兼容：插件完全支持服务端渲染，无需额外配置。

五、注意事项（文档同步）

1. 局部 Loading 目标：target必须是真实 DOM 元素，不能直接传组件实例（需通过 ref 获取 DOM）。
2. 异步操作安全：建议在finally块中调用hide()，避免异步操作失败导致 Loading 一直显示。
3. 样式优先级：自定义颜色需使用 RGBA 确保透明度，避免遮罩遮挡内容不明显。
4. Spinner 类型：支持所有 Quasar Spinner 组件名称（如q-spinner-dots可简写为dots），完整列表见 Quasar 官方文档。

六、高级场景（文档拓展示例）

场景 1：带超时的 Loading（防止无限加载）

$q.loading.show({ message: '请求超时测试', timeout: 5000, // 5 秒后自动隐藏 onTimeout: () => { $q.notify({ type: 'negative', message: '请求超时，请重试' }) } })

场景 2：延迟显示 Loading（避免闪烁）

$q.loading.show({ message: '加载中...', delay: 300 // 300ms 后仍未隐藏才显示 })

Quasar LoadingBar 插件核心总结

一、核心定位

LoadingBar 插件是 QAjaxBar 组件的简化封装，用于快速实现顶部 / 底部加载进度条，适配 Ajax 请求、路由切换等场景，无需手动编写进度条逻辑，支持自动监听或手动控制。

二、安装启用（Quasar CLI）

1. 插件内置，在quasar.config.js中注册即可：

// quasar.config.js module.exports = { framework: { plugins: ['LoadingBar'], // 启用插件 config: { loadingBar: { /* 全局默认配置 */ } // 可选，设置默认样式 } } }

1. UMD 版本默认启用，若需禁用监听 Ajax 流量，可配置loadingBar: { skipHijack: true }。

三、核心用法

1. 基础控制方法

2. 调用方式

• 组件内：通过useQuasar()获取$q.loadingBar调用：

  import { useQuasar } from 'quasar' const $q = useQuasar() $q.loadingBar.start() // 启动 $q.loadingBar.stop() // 结束

• 组件外（含启动文件）：直接导入LoadingBar调用：

  import { LoadingBar } from 'quasar' LoadingBar.start() LoadingBar.increment(50) // 进度更新到 50%

3. 关键配置（支持所有 QAjaxBar 属性）

通过setDefaults()或全局配置设置，核心配置项：

• color：进度条颜色（如purple、#ff0000）；
• size：进度条高度（如15px、2rem）；
• position：显示位置（top/bottom，默认顶部）；
• hijackFilter(url)：Ajax 过滤函数，返回布尔值控制是否对该 URL 触发进度条（v2.4.5+）。

四、核心特性

1. 自动监听：默认监听全局 Ajax 流量，无需手动调用start()/stop()；
2. 灵活过滤：通过hijackFilter配置仅对指定 URL 触发进度条；
3. 全局统一：支持全局设置默认样式，无需重复配置；
4. 手动控制：支持分步更新进度，适配复杂加载场景。

五、注意事项

1. 配置优先级：局部调用时的配置会覆盖全局默认配置；
2. UMD 版本：默认启用所有插件，禁用 Ajax 监听需配置skipHijack: true；
3. 进度条逻辑：start()后需调用stop()结束，否则进度条会一直停留。

Quasar WebStorage 插件教程（Quasar CLI 版）

一、插件介绍

WebStorage 插件是对浏览器localStorage/sessionStorage的友好封装，提供统一的 API 实现数据的增、删、改、查，支持自动序列化 / 反序列化复杂数据（对象、数组），兼容所有现代浏览器，且无需手动处理存储异常。

• localStorage：持久化存储（除非手动删除，否则永久保存）；
• sessionStorage：会话存储（浏览器标签页关闭后失效）。

二、安装与启用（Quasar CLI 必看）

插件内置，无需额外安装，直接在quasar.config.js中注册启用：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: [ 'LocalStorage','SessionStorage' // 启用 WebStorage 插件 ] } } }

三、核心 API（文档原生方法）

1. 导入方式

组件内 / 组件外均可通过以下方式导入对应存储对象：

import { LocalStorage, SessionStorage } from 'quasar'

2. 通用方法（LocalStorage/SessionStorage 完全一致）

四、基础使用示例（文档同步场景）

场景 1：LocalStorage 持久化存储用户偏好

<!-- src/pages/StoragePage.vue --> <template> <q-page> <q-btn label="保存用户偏好" @click="saveUserPref" /> <q-btn label="获取用户偏好" @click="getUserPref" /> <div>用户偏好：{{ userPref }}</div> </q-page> </template> <script setup> import { ref } from 'vue' import { LocalStorage } from 'quasar' const userPref = ref(null) // 保存复杂数据（对象） const saveUserPref = () => { LocalStorage.set('user_preference', { theme: 'dark', fontSize: 16, notifications: true }) } // 获取数据（带默认值） const getUserPref = () => { userPref.value = LocalStorage.get('user_preference', { theme: 'light', fontSize: 14 }) } </script>

场景 2：SessionStorage 临时存储表单数据

<template> <q-page> <q-input v-model="form.name" label="姓名" /> <q-input v-model="form.age" type="number" label="年龄" /> <q-btn label="临时保存表单" @click="saveFormTemp" /> <q-btn label="恢复表单数据" @click="restoreForm" /> </q-page> </template> <script setup> import { ref } from 'vue' import { SessionStorage } from 'quasar' const form = ref({ name: '', age: '' }) // 临时保存表单（标签页关闭后失效） const saveFormTemp = () => { SessionStorage.set('temp_form', form.value) } // 恢复表单数据 const restoreForm = () => { const tempData = SessionStorage.get('temp_form') if (tempData) form.value = tempData } </script>

场景 3：批量操作与判断

import { LocalStorage } from 'quasar' // 判断键是否存在 if (LocalStorage.has('token')) { console.log('Token 已存储') } // 获取所有键名 const allKeys = LocalStorage.getKeys() console.log('所有存储键：', allKeys) // 删除指定键 LocalStorage.remove('temp_data') // 清空所有 LocalStorage LocalStorage.clear()

五、文档关键特性与注意事项

1. 核心特性

• 自动序列化：存储对象、数组时自动转为 JSON 字符串，获取时自动反序列化，无需手动JSON.stringify()/JSON.parse()；
• 异常处理：封装了浏览器存储配额不足、权限拒绝等异常，避免代码崩溃；
• 类型安全：获取数据时可指定默认值，确保返回类型一致；
• API 统一：LocalStorage与SessionStorage方法完全一致，切换存储方式仅需修改导入对象。

2. 注意事项

• 存储大小限制：浏览器对localStorage/sessionStorage有大小限制（通常 5MB 左右），避免存储大文件或大量数据；
• 数据类型：不支持存储Function、Symbol等类型，此类数据会被自动忽略；
• 跨域限制：localStorage/sessionStorage遵循同源策略，不同域名无法共享数据；
• SSR 兼容：在服务端渲染（SSR）环境中，需确保仅在客户端调用 WebStorage 方法（可通过process.client判断）；
• setJson/getJson：与set/get功能完全一致，仅为语义化别名，无额外差异。

六、高级场景（文档拓展示例）

场景 1：SSR 环境下安全使用

import { LocalStorage, process } from 'quasar' // 仅在客户端执行存储操作 if (process.client) { LocalStorage.set('client_data', '仅客户端存储') }

场景 2：存储过期逻辑（手动实现）

import { LocalStorage } from 'quasar' // 存储带过期时间的数据 const setWithExpiry = (key, value, expiryHours) => { const data = { value, expiry: Date.now() + expiryHours * 3600000 // 过期时间戳（小时转毫秒） } LocalStorage.set(key, data) } // 获取带过期时间的数据 const getWithExpiry = (key) => { const data = LocalStorage.get(key) if (!data) return null // 检查是否过期 if (Date.now() > data.expiry) { LocalStorage.remove(key) return null } return data.value } // 使用示例：存储 2 小时后过期的 token setWithExpiry('temp_token', 'abc123', 2) const token = getWithExpiry('temp_token') // 未过期返回 token，过期返回 null

Quasar Meta 插件核心总结

一、核心作用

专门用于动态管理页面元信息，优化 SEO 效果，支持修改页面标题、<meta>标签、<html>/<body>属性，以及添加 / 删除文档头部的<style>/<script>/<noscript>标签，适配 SSR（服务器端渲染）和 SPA（单页应用），尤其在 SSR 中能让元信息由服务器直接提供，提升 SEO 表现。

二、安装启用（Quasar CLI）

插件内置，在quasar.config.js中注册即可：

// quasar.config.js module.exports = { framework: { plugins: ['Meta'] // 启用 Meta 插件 } }

三、核心用法

1. 基础配置（组件内静态配置）

在 Vue 组件中通过meta属性定义静态元信息，支持多类型配置：

export default { meta: { // 页面标题相关 title: '首页', // 基础标题 titleTemplate: title => `${title} - 我的网站`, // 标题模板（最终显示“首页 - 我的网站”） // meta 标签（name/http-equiv 类型） meta: { description: { name: 'description', content: '这是网站首页，提供优质内容' }, keywords: { name: 'keywords', content: 'Quasar,Meta,SEO' }, contentType: { 'http-equiv': 'Content-Type', content: 'text/html; charset=UTF-8' } }, // 外部资源链接（如字体、样式表） link: { materialIcons: { rel: 'stylesheet', href: 'https://fonts.googleapis.com/icon?family=Material+Icons' } }, // 脚本标签（如 JSON-LD 结构化数据） script: { ldJson: { type: 'application/ld+json', innerHTML: `{ "@context": "http://schema.org" }` } }, // html 标签属性 htmlAttr: { 'xmlns:cc': 'http://creativecommons.org/ns#' }, // body 标签属性 bodyAttr: { 'action-scope': 'xyz' }, // noscript 标签（无 JS 时显示） noscript: { default: '您的浏览器不支持 JavaScript，请开启后访问' } } }

2. 动态配置（绑定组件状态）

meta可设为函数，绑定组件内数据，数据变化时自动更新元信息：

export default { data() { return { pageDesc: '初始描述' } }, // 动态绑定，依赖组件状态 meta() { return { title: this.pageDesc, meta: { description: { name: 'description', content: this.pageDesc } } } }, methods: { updateDesc() { this.pageDesc = '更新后的页面描述' // 触发元信息自动更新 } } }

3. 配置覆盖规则

元信息按组件渲染链顺序（如 App.vue → 布局组件 → 页面组件）叠加，后续组件可通过相同键名覆盖前序组件的配置：

// 父组件配置 meta: { meta: { desc: { name: 'description', content: '父组件描述' } } } // 子组件配置（覆盖父组件的 desc 键对应的 meta 标签） meta: { meta: { desc: { name: 'description', content: '子组件描述' } } }

四、关键注意事项

1. 避免重复配置：若src/index.template.html中已有元信息，建议删除，避免与插件配置冲突；若元信息固定不变，直接在 HTML 模板中定义更高效。
2. 适用场景差异：SSR 中使用效果最佳，元信息可由服务器直接返回；SPA 中元信息在运行时添加，SEO 优化效果有限。
3. 验证工具：部署前建议通过 https://metatags.io/ 验证元信息是否生效。

Quasar Notify 插件教程（Quasar CLI 版）

一、插件介绍

Notify 插件用于创建轻量级通知提示（Toast / 通知栏），支持自定义样式、位置、动画、持续时间，替代原生alert或自定义弹窗，适配桌面端与移动端，可快速实现操作反馈、系统提示等场景。

二、安装与启用（Quasar CLI 必看）

插件内置，无需额外安装，直接在quasar.config.js中注册启用：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: [ 'Notify' // 启用 Notify 插件 ] } } }

三、核心使用方式

1. 基础调用（组件内）

通过useQuasar()获取$q.notify实例，支持直接传字符串（简化版）或配置对象（完整版）：

<script setup> import { useQuasar } from 'quasar' const $q = useQuasar() // 简化版：仅提示文本（默认类型为 info） $q.notify('操作成功！') // 完整版：自定义配置 $q.notify({ type: 'positive', // 通知类型（positive/negative/warning/info/ongoing） message: '数据保存成功', caption: '2025-12-15 10:00', // 副标题（可选） position: 'top-right', // 显示位置（top/top-left/top-right/bottom/bottom-left/bottom-right） timeout: 3000, // 自动关闭时间（毫秒，0 表示永不关闭） actions: [ // 自定义操作按钮（可选） { label: '关闭', color: 'white', handler: () => {} } ] }) </script>

2. 组件外调用（全局工具）

在非组件文件（如 api 封装、工具函数）中直接导入Notify：

// src/utils/notify.js import { Notify } from 'quasar' // 全局提示 Notify.create({ type: 'negative', message: '请求失败，请重试' }) // 简化版 Notify.create('全局通知')

3. 通知类型与预设样式

4. 核心配置项（文档完整参数）

actions: [ { label: '详情', // 按钮文本 color: 'white', // 文本颜色 handler: () => { console.log('点击详情按钮') } // 点击事件 }, { label: '关闭', color: 'white', handler: (notify) => { notify.close() } // 手动关闭通知 } ]

四、高级功能（文档原生特性）

1. 手动控制通知生命周期

// 创建通知实例并手动控制 const notifyInstance = $q.notify({ message: '正在处理...', type: 'ongoing', timeout: 0 // 永不自动关闭 }) // 手动关闭通知 notifyInstance.close() // 更新通知内容（v2.14.0+） notifyInstance.update({ message: '处理完成！', type: 'positive', timeout: 3000 })

2. 全局默认配置

在quasar.config.js中设置全局默认值，覆盖所有通知的默认配置：

// quasar.config.js module.exports = function (ctx) { return { framework: { plugins: ['Notify'], config: { notify: { position: 'bottom-right', timeout: 4000, multiLine: true, progress: true } } } } }

3. 自定义通知样式

通过color/textColor/icon完全自定义通知外观：

$q.notify({ message: '自定义样式通知', color: 'purple-6', // 自定义背景色 textColor: 'white', icon: { name: 'star', // Quasar 图标名 color: 'yellow' }, position: 'bottom' })

五、关键注意事项（文档同步）

1. 关闭逻辑：timeout: 0时通知永不自动关闭，需通过actions或手动调用close()关闭；
2. 图标支持：icon支持 Quasar 内置图标（如 'warning'）、Material Icons 或自定义 SVG 图标；
3. 移动端适配：position: 'bottom'在移动端体验更佳，避免遮挡顶部导航栏；
4. 多通知叠加：同一位置的通知会自动堆叠显示，最多同时显示 5 个（可通过全局配置调整）；
5. SSR 兼容：插件完全支持服务端渲染，无需额外配置。

六、实战示例（文档拓展示例）

场景 1：表单提交反馈

const submitForm = async () => { try { await api.submitForm(formData) $q.notify({ type: 'positive', message: '表单提交成功', caption: '将在 3 秒后跳转', progress: true }) setTimeout(() => { router.push('/success') }, 3000) } catch (err) { $q.notify({ type: 'negative', message: '提交失败', caption: err.message, multiLine: true, timeout: 0, actions: [{ label: '关闭', handler: (n) => n.close() }] }) } }

场景 2：持续操作提示（手动更新）

// 开始加载时显示通知 const notify = $q.notify({ message: '正在下载文件...', type: 'ongoing', timeout: 0, progress: false }) // 模拟下载进度更新 const simulateDownload = () => { let progress = 0 const timer = setInterval(() => { progress += 10 if (progress >= 100) { clearInterval(timer) // 下载完成后更新通知 notify.update({ message: '文件下载完成', type: 'positive', timeout: 3000 }) } else { notify.update({ message: `正在下载文件...(${progress}%)` }) } }, 500) } simulateDownload()

实战

<template> <div class="q-pa-md q-gutter-y-sm column items-center"> <div> <div class="row q-gutter-sm"> <q-btn round size="sm" color="secondary" @click="showNotif('top-left')"> <q-icon name="arrow_back" class="rotate-45" /> </q-btn> <q-btn round size="sm" color="accent" @click="showNotif('top')"> <q-icon name="arrow_upward" /> </q-btn> <q-btn round size="sm" color="secondary" @click="showNotif('top-right')"> <q-icon name="arrow_upward" class="rotate-45" /> </q-btn> </div> </div> <div> <div class="row q-gutter-sm"> <div> <q-btn round size="sm" color="accent" @click="showNotif('left')"> <q-icon name="arrow_back" /> </q-btn> </div> <div> <q-btn round size="sm" color="accent" @click="showNotif('center')"> <q-icon name="fullscreen_exit" /> </q-btn> </div> <div> <q-btn round size="sm" color="accent" @click="showNotif('right')"> <q-icon name="arrow_forward" /> </q-btn> </div> </div> </div> <div> <div class="row q-gutter-sm"> <div> <q-btn round size="sm" color="secondary" @click="showNotif('bottom-left')"> <q-icon name="arrow_forward" class="rotate-135" /> </q-btn> </div> <div> <q-btn round size="sm" color="accent" @click="showNotif('bottom')"> <q-icon name="arrow_downward" /> </q-btn> </div> <div> <q-btn round size="sm" color="secondary" @click="showNotif('bottom-right')"> <q-icon name="arrow_forward" class="rotate-45" /> </q-btn> </div> </div> </div> </div> </template> <script> import { useQuasar } from 'quasar' const alerts = [ { color: 'negative', message: 'Woah! Danger! You are getting good at this!', icon: 'report_problem' }, { message: 'You need to know about this!', icon: 'warning' }, { message: 'Wow! Nice job!', icon: 'thumb_up' }, { color: 'teal', message: 'Quasar is cool! Right?', icon: 'tag_faces' }, { color: 'purple', message: 'Jim just pinged you', avatar: 'https://cdn.quasar.dev/img/boy-avatar.png' }, { multiLine: true, message: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit. Hic quisquam non ad sit assumenda consequuntur esse inventore officia. Corrupti reiciendis impedit vel, fugit odit quisquam quae porro exercitationem eveniet quasi.' } ] export default { setup () { const $q = useQuasar() return { showNotif (position) { const { color, textColor, multiLine, icon, message, avatar } = alerts[ Math.floor(Math.random(alerts.length) * 10) % alerts.length ] const random = Math.random() * 100 const twoActions = random > 70 const buttonColor = color ? 'white' : void 0 $q.notify({ color, textColor, icon: random > 30 ? icon : null, message, position, avatar, multiLine, actions: twoActions ? [ { label: 'Reply', color: buttonColor, handler: () => { /* console.log('wooow') */ } }, { label: 'Dismiss', color: 'yellow', handler: () => { /* console.log('wooow') */ } } ] : (random > 40 ? [{ label: 'Reply', color: buttonColor, handler: () => { /* console.log('wooow') */ } }] : null ), timeout: Math.random() * 5000 + 3000 }) } } } } </script>