Skip to page content

Quasar Vite 插件

如果您想将 Quasar 集成到现有的 Vite 项目中，请按照本指南安装和使用 @quasar/vite-plugin。 该 Vite 插件开箱即用地提供了 Quasar 的 Tree-Shaking 功能以及 Quasar Sass 变量的集成。

@quasar/vite-plugin v2 的要求
  • Vite 8+、@vitejs/plugin-vue 6+、Quasar v2.24+ 以及 Node 20.19+。
  • 该包仅支持 ESM。
  • 如果你使用的是较旧版本，请使用 @quasar/vite-plugin v1.x。
注意限制：
  • 请确认您来对了地方。本页面介绍的是 Vite 插件的用法，它与底层集成了 Vite 的完整 Quasar CLI 并不相同。
  • Vite 插件不支持 SSR/SSG 构建（SSR/SSG 只能通过 Quasar CLI with Vite 实现）。

Vite 的跨平台支持由社区插件提供。这些插件与 Quasar 的集成度不如 Quasar CLI 那么紧密，可能会遇到问题。因此，为了获得最佳开发体验，我们推荐使用 Quasar CLI with Vite。

创建 Vite 项目

pnpm create vite my-vue-app -- --template vue

完整的官方指南请访问 Vite 项目搭建指南。询问时请选择 “Vue”。

安装

进入 Vite 项目目录，安装必要的依赖包。

TIP
  • @quasar/extras 是可选的。
  • 如果要使用 Quasar 的 Sass/SCSS 变量，需要根据 Quasar UI 的版本添加 Sass 依赖：
    • Quasar >= v2.14：添加 sass-embedded@^1.93.2
    • Quasar <= v2.13：添加 sass@1.32.12（注意这是精确固定的版本号）
pnpm add quasar @quasar/extras
pnpm add -D @quasar/vite-plugin sass-embedded@^1.93.2

使用 Quasar

我们提供了一个配置器，帮助您快速上手：

Roboto font
Roboto font extended
Animations from Animate.css
Material Icons
Material Icons (Outlined)
Material Icons (Round)
Material Icons (Sharp)
Material Symbols (Outlined)
Material Symbols (Rounded)
Material Symbols (Sharp)
MDI v7
Fontawesome v6
Fontawesome v5
Ionicons v4
Eva Icons
Themify
Line Awesome
Bootstrap Icons
Quasar Sass/SCSS variables
Quasar Config Object
// FILE: main.js

import { createApp } from 'vue'
import { Quasar } from 'quasar'

// Import icon libraries
import '@quasar/extras/material-icons/material-icons.css'

// Import Quasar css
import 'quasar/src/css/index.sass'

// Assumes your root component is App.vue
// and placed in same folder as main.js
import App from './App.vue'

const myApp = createApp(App)

myApp.use(Quasar, {
  plugins: {}, // import Quasar plugins and add here
})

// Assumes you have a <div id="app"></div> in your index.html
myApp.mount('#app')

// FILE: vite.config.js

import { join } from 'node:path'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { quasar, transformAssetUrls } from '@quasar/vite-plugin'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue({
      template: { transformAssetUrls }
    }),

    // @quasar/plugin-vite options list:
    // https://github.com/quasarframework/quasar/blob/dev/vite-plugin/index.d.ts
    quasar({
      sassVariables: join(import.meta.dirname, 'src/quasar-variables.sass')
    })
  ]
})

// FILE (create it): src/quasar-variables.sass

$primary   : #1976D2
$secondary : #26A69A
$accent    : #9C27B0

$dark      : #1D1D1D

$positive  : #21BA45
$negative  : #C10015
$info      : #31CCEC
$warning   : #F2C037

@quasar/vite-plugin 配置选项

完整的配置选项列表请查看这里。

使用 Vitest 测试

Node 会通过 quasar 包的 node 导出条件来解析它，而该条件指向的是 SSR 服务端构建。Vitest 也是这么做的，因此一个不经过我们 Vite 插件的测试环境会加载那份构建，此时 Quasar 会拒绝安装（The SSR server build was installed without an ssrContext）。

请在 Vitest 使用的 Vite 配置中保留来自 @quasar/vite-plugin 的 quasar()。在提供服务（serving）期间（Vitest 也算作提供服务），插件会把 quasar 别名指向客户端构建。如果你的测试有独立的 vitest.config.js，也请在其中加上该插件：

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

export default defineConfig({
  plugins: [vue({ template: { transformAssetUrls } }), quasar()],
  test: {
    environment: 'jsdom'
  }
})

然后把 Quasar 安装进 @vue/test-utils，让每次 mount() 都能得到 $q 对象：

import { config, mount } from '@vue/test-utils'
import { Quasar } from 'quasar'

config.global.plugins.unshift([Quasar, {/* Quasar plugin options */}])
TIP

Quasar CLI 项目应改用官方的 @quasar/testing-unit-vitest 应用扩展（App Extension），它会把上述这些配置全部接好。

Storybook

Storybook 会用它自己的 Vite 配置来构建你的 stories，而这份配置对 quasar.config（Quasar CLI 项目）或你的 vite.config.js 一无所知。它缺少两样东西，而两者都可以通过把我们的 Vite 插件加入 Storybook 的配置来补回：

  • Quasar 的 Sass/SCSS 变量。没有该插件，任何使用 $primary 的 <style lang="sass"> 都会因 SassError: Undefined variable 而失败。
  • Quasar 对 quasar 包的自有解析（原因参见上文 Vitest 章节）。

@storybook/vue3-vite 框架会自行注册 @vitejs/plugin-vue，因此只剩 Quasar 插件需要添加。Storybook 引入的 Vite 版本必须满足本页顶部的要求。

// .storybook/main.js

import { join } from 'node:path'
import { mergeConfig } from 'vite'
import { quasar } from '@quasar/vite-plugin'

export default {
  framework: '@storybook/vue3-vite',
  stories: ['../src/**/*.stories.@(js|ts)'],

  async viteFinal(config) {
    return mergeConfig(config, {
      plugins: [
        quasar({
          // 你的变量文件；在 Quasar CLI 项目中即
          // quasar.config > css > variables 所设置的那个
          sassVariables: join(
            import.meta.dirname,
            '../src/css/quasar.variables.sass'
          )
        })
      ],

      resolve: {
        // Quasar CLI 项目所依赖的 "@" 别名
        alias: { '@': join(import.meta.dirname, '../src') }
      }
    })
  }
}

然后像你的应用入口那样，把 Quasar 安装进渲染 stories 的 Vue 应用并 import 相应的 css：

// .storybook/preview.js

import { setup } from '@storybook/vue3-vite'
import { Quasar } from 'quasar'

import '@quasar/extras/roboto-font/roboto-font.css'
import '@quasar/extras/material-icons/material-icons.css'
import 'quasar/src/css/index.sass'
import '../src/css/app.scss'

setup(app => {
  app.use(Quasar, {
    plugins: {} // 在此 import 并添加 Quasar 插件
  })
})

export default {
  parameters: {}
}
Quasar CLI 项目

quasar prepare（也会由 postinstall 运行）会从 quasar.config > framework 生成 .quasar/quasar-user-options.js：语言包、图标集、Quasar 插件和 config 对象。直接 import 它并传给 app.use(Quasar, quasarUserOptions)，而不必重复这些设置。

Storybook 渲染的是组件而非你的应用，因此 quasar.config 中的其他内容都不会在其中生效：boot 文件不会运行，build.env 的值不在 import.meta.env 中，自定义的 build.alias 条目需要加到上面的 resolve.alias 里，而 SSR、Capacitor、Cordova、Electron 和 BEX 模式则完全触及不到。story 需要从 boot 文件获取的任何东西（router、Pinia store、i18n）都在上面的 setup() 回调中安装。

RTL 支持

如需启用 RTL（从右到左）布局，请参阅 RTL 支持 页面并按照说明操作。

Caught a mistake?Edit this page in browser
MIT LicensePrivacy Policy
Copyright © 2015-present PULSARDEV SRL, Razvan Stoenescu