⚡
Quasar Framework 치트시트

Vue 3 기반 크로스 플랫폼 프레임워크: 신규 설치 및 기존 Vue 3 연동, 레이아웃, UI 컴포넌트, 폼 검증, 플러그인, 멀티 플랫폼 빌드 퀵 레퍼런스
#quasar#vue3#vue#frontend#vite#material-design#spa#pwa#mobile#electron최종 업데이트: 2026-09-26
Quasar Framework 치트시트 핵심 명령어 및 실전 가이드

Vue 3 기반 크로스 플랫폼 프레임워크: 신규 설치 및 기존 Vue 3 연동, 레이아웃, UI 컴포넌트, 폼 검증, 플러그인, 멀티 플랫폼 빌드 퀵 레퍼런스
## 1. 신규 Quasar 프로젝트 생성 (Quasar CLI)
```bash
# 1. 공식 추천 방식으로 새 Quasar 프로젝트 생성 (Vite 기반 권장)
npm create quasar@latest
# 또는 pnpm create quasar / yarn create quasar

# 프롬프트 설정 권장 옵션:
# ? What would you like to build? … App with Quasar CLI, Vite (권장)
# ? Project folder: … my-quasar-app
# ? Pick Quasar version: … Quasar v2 (Vue 3)
# ? Pick script type: … Typescript (권장)
# ? Pick Quasar App CLI: … Quasar CLI with Vite
# ? Pick Component style: … Composition API with <script setup> (권장)
# ? Pick features: … ESLint, Pinia, Axios

# 2. 프로젝트 폴더 이동 및 개발 서버 실행
cd my-quasar-app
quasar dev    # 또는 npm run dev (기본 포트 http://localhost:9000)

# 3. 운영 환경 프로덕션 빌드 (SPA 기본)
quasar build  # dist/spa 폴더에 최종 번들 생성
```
```text
[Quasar CLI 프로젝트 구조]
my-quasar-app/
├── quasar.config.js   → 플러그인(Notify, Dialog), 아이콘, 빌드 타겟 설정 파일
├── src/boot/          → 앱 시작 시 자동 실행 초기화 스크립트 (axios, i18n 등)
├── src/layouts/       → MainLayout.vue (헤더, 네비게이션 드로어, 푸터)
├── src/pages/         → IndexPage.vue (각 화면 페이지 컴포넌트)
└── src/App.vue        → 최상위 루트 컴포넌트 (<router-view />)
```

## 2. 기존 Vue 3 프로젝트에 Quasar 추가 (@quasar/vite-plugin)
```bash
# 1. 기존 Vite + Vue 3 프로젝트에 Quasar, 아이콘, 플러그인, Sass 설치
npm i quasar @quasar/extras
npm i -D @quasar/vite-plugin sass@^1.32.0
```
```typescript
// 2. vite.config.ts 설정 (Vite 플러그인 등록)
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { quasar, transformAssetUrls } from '@quasar/vite-plugin'

export default defineConfig({
  plugins: [
    vue({
      template: { transformAssetUrls }
    }),
    quasar({
      sassVariables: 'src/quasar-variables.sass' // (선택: 커스텀 테마 변수)
    })
  ]
})
```
```typescript
// 3. src/main.ts 설정 (Quasar 인스턴스 등록 및 CSS import)
import { createApp } from 'vue'
import { Quasar, Notify, Dialog, Loading } from 'quasar'

// Quasar 핵심 CSS 및 머티리얼 아이콘 폰트 불러오기
import '@quasar/extras/material-icons/material-icons.css'
import 'quasar/src/css/index.sass'

import App from './App.vue'

const app = createApp(App)

app.use(Quasar, {
  plugins: {
    Notify,
    Dialog,
    Loading
  }
})

app.mount('#app')
```
```bash
# 💡 (참고) 만약 Vue CLI 기반 프로젝트라면 공식 명령어로 1줄 추가 가능:
vue add quasar
```

## 3. 레이아웃 시스템 (q-layout & view 속성)
```vue
<!-- src/layouts/MainLayout.vue -->
<script setup lang="ts">
import { ref } from 'vue'

const leftDrawerOpen = ref(false)
const toggleLeftDrawer = () => {
  leftDrawerOpen.value = !leftDrawerOpen.value
}
</script>

<template>
  <!-- 💡 view="lHh Lpr lFf": Header, Drawer, Footer의 배치 구조를 9자리로 제어 -->
  <q-layout view="lHh Lpr lFf">
    <!-- 상단 헤더 -->
    <q-header elevated class="bg-primary text-white">
      <q-toolbar>
        <q-btn flat dense round icon="menu" @click="toggleLeftDrawer" />
        <q-toolbar-title>내 퀘이사 앱</q-toolbar-title>
        <q-btn flat round icon="account_circle" />
      </q-toolbar>
    </q-header>

    <!-- 좌측 사이드바 서랍 (Drawer) -->
    <q-drawer v-model="leftDrawerOpen" show-if-above bordered>
      <q-list>
        <q-item-label header>탐색 메뉴</q-item-label>
        <q-item clickable v-ripple to="/">
          <q-item-section avatar><q-icon name="home" /></q-item-section>
          <q-item-section>홈</q-item-section>
        </q-item>
      </q-list>
    </q-drawer>

    <!-- 페이지 컨테이너: 라우트 페이지 컴포넌트가 렌더링되는 곳 -->
    <q-page-container>
      <router-view />
    </q-page-container>
  </q-layout>
</template>
```

## 4. 버튼, 아이콘 & 뱃지 (q-btn, q-icon, q-badge)
```vue
<script setup lang="ts">
import { ref } from 'vue'
const isLoading = ref(false)
</script>

<template>
  <!-- 다양한 버튼 스타일 -->
  <q-btn color="primary" label="기본 버튼" />
  <q-btn outline color="secondary" label="외곽선 버튼" />
  <q-btn flat color="accent" label="플랫 버튼" />
  <q-btn round color="negative" icon="delete" />

  <!-- 로딩 상태 지원 버튼 -->
  <q-btn 
    :loading="isLoading" 
    color="primary" 
    label="저장하기" 
    @click="isLoading = true" 
  />

  <!-- 아이콘 및 플로팅 뱃지 -->
  <q-btn dense round flat icon="notifications">
    <q-badge color="red" floating>4</q-badge>
  </q-btn>
</template>
```

## 5. 폼 입력 & 유효성 검사 (q-input, q-select, q-toggle)
```vue
<script setup lang="ts">
import { ref } from 'vue'

const email = ref('')
const role = ref('USER')
const isAgreed = ref(false)

// 💡 rules 속성에 유효성 검사 함수 배열을 넣어 자동 에러 표시
const emailRules = [
  (val: string) => !!val || '이메일을 입력하세요.',
  (val: string) => /.+@.+\..+/.test(val) || '올바른 이메일 형식이 아닙니다.'
]
</script>

<template>
  <q-form @submit="onSubmit" class="q-gutter-md">
    <!-- 텍스트 인풋 (outlined, clearable, rules 지원) -->
    <q-input 
      v-model="email" 
      label="이메일 주소" 
      outlined 
      dense 
      clearable
      :rules="emailRules" 
    />

    <!-- 셀렉트 박스 -->
    <q-select 
      v-model="role" 
      :options="['ADMIN', 'USER', 'GUEST']" 
      label="권한 선택" 
      outlined 
      dense 
    />

    <!-- 토글 스위치 & 체크박스 -->
    <q-toggle v-model="isAgreed" label="알림 수신 동의" />
    <q-btn type="submit" color="primary" label="회원가입" />
  </q-form>
</template>
```

## 6. 데이터 테이블 (q-table)
```vue
<script setup lang="ts">
import { ref } from 'vue'

const filter = ref('')
const columns = [
  { name: 'id', label: 'ID', field: 'id', sortable: true, align: 'left' },
  { name: 'name', label: '이름', field: 'name', sortable: true, align: 'left' },
  { name: 'role', label: '역할', field: 'role', align: 'center' }
]
const rows = [
  { id: 1, name: '홍길동', role: 'ADMIN' },
  { id: 2, name: '이순신', role: 'USER' }
]
</script>

<template>
  <!-- 검색, 정렬, 페이지네이션 기본 내장 테이블 -->
  <q-table
    title="회원 목록"
    :rows="rows"
    :columns="columns"
    row-key="id"
    :filter="filter"
  >
    <!-- 상단 검색창 슬롯 커스터마이징 -->
    <template v-slot:top-right>
      <q-input borderless dense debounce="300" v-model="filter" placeholder="검색...">
        <template v-slot:append><q-icon name="search" /></template>
      </q-input>
    </template>

    <!-- 특정 셀 커스텀 렌더링 (뱃지 표시) -->
    <template v-slot:body-cell-role="props">
      <q-td :props="props">
        <q-badge :color="props.value === 'ADMIN' ? 'red' : 'blue'">
          {{ props.value }}
        </q-badge>
      </q-td>
    </template>
  </q-table>
</template>
```

## 7. 팝업, 알림 & 로딩 (useQuasar 플러그인)
```vue
<script setup lang="ts">
import { useQuasar } from 'quasar'

const $q = useQuasar()

// 1. 토스트 알림 (Notify)
const showToast = () => {
  $q.notify({
    type: 'positive', // positive, negative, warning, info
    message: '성공적으로 저장되었습니다!',
    position: 'top',
    timeout: 2000
  })
}

// 2. 확인 모달 대화상자 (Dialog)
const confirmDelete = () => {
  $q.dialog({
    title: '삭제 확인',
    message: '정말로 이 항목을 삭제하시겠습니까?',
    cancel: true,
    persistent: true
  }).onOk(() => {
    showToast()
  })
}

// 3. 전역 로딩 스피너 (Loading)
const loadData = () => {
  $q.loading.show({ message: '데이터를 불러오는 중...' })
  setTimeout(() => $q.loading.hide(), 1500)
}
</script>
```

## 8. 모달 다이얼로그 & 드롭다운 메뉴 (q-dialog & q-menu)
```vue
<script setup lang="ts">
import { ref } from 'vue'
const isDialogOpen = ref(false)
</script>

<template>
  <!-- 1. 커스텀 카드 모달 다이얼로그 -->
  <q-btn label="모달 열기" color="primary" @click="isDialogOpen = true" />

  <q-dialog v-model="isDialogOpen">
    <q-card style="min-width: 350px">
      <q-card-section><div class="text-h6">프로필 설정</div></q-card-section>
      <q-card-section><q-input label="닉네임" outlined dense /></q-card-section>
      <q-card-actions align="right">
        <q-btn flat label="취소" v-close-popup />
        <q-btn color="primary" label="확인" v-close-popup />
      </q-card-actions>
    </q-card>
  </q-dialog>

  <!-- 2. 드롭다운 팝업 메뉴 (q-menu) -->
  <q-btn color="secondary" label="더보기">
    <q-menu>
      <q-list style="min-width: 100px">
        <q-item clickable v-close-popup><q-item-section>수정하기</q-item-section></q-item>
        <q-item clickable v-close-popup class="text-negative"><q-item-section>삭제</q-item-section></q-item>
      </q-list>
    </q-menu>
  </q-btn>
</template>
```

## 9. 다크 모드 & 반응형 유틸리티 (Dark & Screen)
```vue
<script setup lang="ts">
import { useQuasar } from 'quasar'

const $q = useQuasar()

// 1. 다크 모드 토글
const toggleDark = () => {
  $q.dark.toggle() // 또는 $q.dark.set(true | false | 'auto')
}
</script>

<template>
  <!-- 다크 모드 버튼 -->
  <q-btn 
    flat 
    round 
    :icon="$q.dark.isActive ? 'dark_mode' : 'light_mode'" 
    @click="toggleDark" 
  />

  <!-- 2. 반응형 Flex 그리드 레이아웃 (Bootstrap 스타일) -->
  <div class="row q-col-gutter-md">
    <!-- 모바일: 12칸 전체(1열), 태블릿 이상: 6칸(2열), PC: 4칸(3열) -->
    <div class="col-12 col-sm-6 col-md-4">
      <q-card class="q-pa-md">카드 1</q-card>
    </div>
    <div class="col-12 col-sm-6 col-md-4">
      <q-card class="q-pa-md">카드 2</q-card>
    </div>
  </div>

  <!-- 현재 화면 너비 조건부 렌더링 -->
  <p v-if="$q.screen.lt.md">모바일/태블릿 화면입니다.</p>
</template>
```

## 10. 크로스 플랫폼 빌드 명령어 (Cross-Platform Targets)
```bash
# 1. PWA (Progressive Web App - 오프라인 및 설치형 웹)
quasar dev -m pwa
quasar build -m pwa

# 2. SSR (Server-Side Rendering - SEO 최적화)
quasar dev -m ssr
quasar build -m ssr

# 3. Mobile App (Capacitor 기반 Android / iOS 빌드)
quasar mode add capacitor
quasar dev -m capacitor -T android    # 안드로이드 에뮬레이터/기기 실시간 디버깅
quasar build -m capacitor -T ios      # iOS 앱스토어 배포 패키징

# 4. Desktop App (Electron 기반 Windows / Mac / Linux 앱)
quasar mode add electron
quasar dev -m electron                # 데스크톱 앱 실시간 개발 실행
quasar build -m electron              # 설치용 .exe / .dmg 인스톨러 빌드
```
💬
Quasar Framework 치트시트

의견 및 질문

댓글 수정

댓글 삭제
