quasar-skilld

Quasar [email protected]

适用于 SPA、PWA、SSR、SSG、移动端（Cordova/Capacitor）和桌面端（Electron）应用的 Vue 3 UI 框架，可使用同一套代码库构建。仅支持 Vue 3。ESM 包，Node >= 22（package.json:102-104）。本 Skill 的基准版本：quasar 2.33.1（2026-09-22）。

首先：阅读已安装包中附带的文档

Quasar 2.33+ 内置了离线文档。在猜测 API 之前，请先查看项目的 node_modules/quasar：

• dist/api/<Name>.json — 每个组件、插件和指令的 props、插槽、事件、方法，并带有 addedIn 版本标记。这是权威依据。
• dist/mcp/**/*.md — quasar.dev 页面（组件、插件、指令、组合式函数、工具函数、样式、布局）的 Markdown；dist/mcp/api/<Name>.md 以精简易读的格式提供相同 API。dist/mcp/meta.json（160 个页面，version: 2.33.1）为所有页面编制了索引。
• @quasar/mcp MCP 服务会向支持 MCP 的 Agent 提供相同文档。

详情和搜索命令：references/offline-docs.md

包结构

入口	路径	备注
浏览器 ESM	dist/quasar.client.js	默认 import 目标
Node/服务端	dist/quasar.server.prod.js	未使用 Vite 插件时 Node/Vitest 解析的目标
UMD	dist/quasar.umd.prod.js	搭配 Vue 3 全局构建版本用于 CDN
类型	dist/types/index.d.ts
wrappers	wrappers/index.js	无操作类型定义，已弃用；请使用 #q-app/wrappers（wrappers/index.js:9-16）
语言包	lang/*.js（75 个）	import langDe from 'quasar/lang/de'
图标集	icon-set/*.js（44 个）	import iconSet from 'quasar/icon-set/material-icons'

完整导出内容（组件、插件、指令、组合式函数、工具函数）： references/api-surface.md

常见任务

使用 Vite 插件安装（@quasar/vite-plugin v2 需要 Vite 8+、 @vitejs/plugin-vue 6+、quasar v2.24+、Node 20.19+；仅支持 ESM； dist/mcp/start/vite-plugin.md:10）：

// main.js
import { createApp } from 'vue'
import { Quasar, Notify } from 'quasar'
import '@quasar/extras/material-icons/material-icons.css'
import 'quasar/src/css/index.sass'
import App from './App.vue'

createApp(App).use(Quasar, { plugins: { Notify } }).mount('#app')

// vite.config.js
import { quasar, transformAssetUrls } from '@quasar/vite-plugin'
import vue from '@vitejs/plugin-vue'

plugins: [vue({ template: { transformAssetUrls } }), quasar()]

在 Composition API 中访问 $q：

import { useQuasar } from 'quasar'
const $q = useQuasar()
$q.notify('Saved') // $q.platform, $q.dark, $q.screen, $q.lang, ...

模板中使用与 API JSON 完全一致的 kebab-case props （hide-dropdown-icon、no-error-icon）；双向 props 绑定使用 v-model:propName（v1 的 .sync 修饰符已移除）。

Sass 变量：quasar >= 2.14 搭配 sass-embedded@^1.93.2；quasar <= 2.13 需要固定使用 [email protected]（dist/mcp/start/vite-plugin.md:38-39）。

有关 Vite、Vitest、Storybook、UMD 和 Quasar CLI 的更多信息： references/installation.md

最佳实践（已对照随附的 2.33.1 文档验证）

• 为提升性能，优先使用响应式 CSS 类（gt-sm、lt-md、窗口宽度可见性类），而非在 JS 中使用 Screen 插件。
• 大型 QTree：大数据集使用 no-transition；超大数据集使用 virtual-scroll（v2.25+）。
• 自定义 Dialog 插件组件：使用 useDialogPluginComponent 进行初始化；直接绑定 @hide="onDialogHide"（v2.28+ 会转发关闭原因）。
• 优先使用 useInterval/useTimeout/useAnimationFrame，而非原生计时器；组件卸载时会自动取消，且在 SSR 中会安全地变为空操作。
• SSR/SSG：除非服务端知道用户偏好（cookie），否则避免将 Dark 模式设为 'auto'，否则用户会看到短暂的浅色闪烁。
• 使用 LoadingBar 插件，而非手动使用 QAjaxBar。
• QInput 的校验：Quasar 推荐 Regle（dist/mcp/vue-components/input.md:2397）。
• Quasar CLI 项目：从 #q-app/wrappers 导入 wrappers，切勿使用 quasar/wrappers。

含引用的完整列表：references/best-practices.md

升级（2.20 -> 2.33.1 重点）

• v2.33.0：文档和精简 API 现在随软件包一同发布（离线可用，版本精确）；与 @quasar/mcp 服务搭配使用。修复：extractDate() 会匹配最长的区域设置名称；QTable 每页行数选择器会遵循受控的 v-model:pagination；虚拟滚动的 scrollTo() 不再在滚动事件后立即失效。
• v2.33.1：QPagination 的 input 模式会在提交时清除输入的页码（src/components/pagination/QPagination.js:290-292）；textToRgb() 会保留 rgb(R, G, B, A) 的 alpha 值（src/utils/colors/colors.js:149-174）。
• v2.28：QMenu/QTooltip 移除了 scroll-target 属性；弹出层会自动跟踪每个滚动容器。Platform.is 移除了 ie、edgeChromium、winphone、kindle、silk。
• v2.29：QItem/QChip 上的 @click 监听器现在会隐式启用 clickable。
• v2.31：只读字段（QInput/QSelect/QFile/QField）现在会反映焦点状态，并在失焦时进行验证。
• v2.32：当容器形状已知时（ratio/initial-ratio/height），QImg 会在 SSR HTML 中渲染其 <img>；否则可通过 ssr-prerender 启用此功能。QExpansionItem/QTree 不再使用 QSlideTransition 包裹内容。
• 已弃用：QInput/QFile 的 getNativeElement() -> 请改用 nativeEl 属性（dist/api/QInput.json）。

2.33.x 本身没有新增 API：dist/api/*.json 中不存在 addedIn: v2.33 标记。所有行为变更和新 API 及其发布说明 URL： references/whats-new.md

安全

*-html 布尔属性（options-html、display-value-html、Notify/Dialog/Loading 上的 html）会启用 HTML 渲染，因此存在 XSS 风险：启用前请先进行清理。QEditor 没有清理选项；请在服务端移除 <script>/<iframe>。Quasar CLI 只会向客户端代码公开带有 QCLI_ 前缀的环境变量。

检查清单：references/security.md