Миграция с Vuetify 2 на 3

Переход от Vuetify 2 к Vuetify 3 представляет собой не просто обновление компонентов, а фундаментальную переработку архитектуры библиотеки. Основой новой версии стал Vue 3, что привело к внедрению современных возможностей фреймворка:

  • Composition API
  • улучшенная реактивность
  • Tree-shaking
  • оптимизация производительности
  • переработанная система темизации

Vuetify 3 построен с расчётом на модульность и гибкость, поэтому многие механизмы, ранее встроенные в ядро, теперь подключаются отдельно.

Ключевые изменения:

Область Vuetify 2 Vuetify 3
Базовый фреймворк Vue 2 Vue 3
API компонентов Options API Composition API + Options API
Система тем Sass переменные CSS Variables
Система сетки flex-based grid переработанная grid-система
Установка глобальная регистрация createVuetify()
Tree-shaking ограниченный полноценный

Эти изменения требуют адаптации существующего кода при миграции.

Обновление зависимостей

Перед миграцией необходимо обновить основные зависимости проекта.

Удаляются старые версии:

npm remove vuetify

Устанавливаются новые пакеты:

npm install vuetify@latest
npm install vue@latest
npm install vite-plugin-vuetify

Vuetify 3 изначально оптимизирован под Vite, поэтому многие проекты переходят с Webpack на Vite для упрощения конфигурации.

Новая инициализация Vuetify

В Vuetify 2 библиотека подключалась напрямую к экземпляру Vue:

import Vue from 'vue'
import Vuetify from 'vuetify'

Vue.use(Vuetify)

export default new Vuetify({})

В Vuetify 3 используется фабричная функция createVuetify.

import { createApp } from 'vue'
import { createVuetify } from 'vuetify'
import App from './App.vue'

const vuetify = createVuetify()

const app = createApp(App)

app.use(vuetify)
app.mount('#app')

Такой подход соответствует архитектуре Vue 3 и позволяет более гибко управлять плагинами.

Изменение структуры импорта компонентов

Vuetify 2 автоматически регистрировал большинство компонентов.

Vuetify 3 предполагает явную регистрацию для уменьшения размера сборки.

import { createVuetify } from 'vuetify'
import { VBtn, VCard } from 'vuetify/components'
import { Ripple } from 'vuetify/directives'

export const vuetify = createVuetify({
  components: {
    VBtn,
    VCard
  },
  directives: {
    Ripple
  }
})

Такой подход позволяет сборщику удалять неиспользуемые компоненты.

Переход на Composition API

Vuetify 3 активно использует Composition API. Это влияет на работу с сервисами и утилитами библиотеки.

Пример использования темы:

Vuetify 2:

this.$vuetify.theme.dark = true

Vuetify 3:

import { useTheme } from 'vuetify'

const theme = useTheme()

theme.global.name.value = 'dark'

Сервисы теперь доступны через composable-функции.

Изменения в системе сетки

Vuetify 2 использовал сетку на основе flexbox:

<v-container>
  <v-row>
    <v-col cols="6">
      Content
    </v-col>
  </v-row>
</v-container>

В Vuetify 3 структура осталась похожей, но API компонентов обновлено и оптимизировано.

<v-container>
  <v-row>
    <v-col cols="6">
      Content
    </v-col>
  </v-row>
</v-container>

Главные отличия:

  • улучшенная адаптивность
  • более гибкая работа с breakpoints
  • переработанные пропсы

Обновление системы темизации

Vuetify 2 использовал Sass-переменные для настройки темы.

Vuetify 3 перешёл на CSS variables, что позволяет изменять тему во время выполнения.

Конфигурация темы:

const vuetify = createVuetify({
  theme: {
    defaultTheme: 'light',
    themes: {
      light: {
        colors: {
          primary: '#1976D2',
          secondary: '#424242'
        }
      }
    }
  }
})

Преимущества:

  • динамическое переключение тем
  • отсутствие необходимости пересборки
  • улучшенная поддержка тёмной темы

Изменения в компонентах

Некоторые компоненты были:

  • переименованы
  • объединены
  • удалены

Примеры изменений:

Vuetify 2 Vuetify 3
v-list-item-content удалён
v-simple-table заменён на v-table
v-app-bar-nav-icon обновлён API
v-chip-group изменён механизм выбора

Изменение v-model

В Vue 3 изменился механизм v-model. Vuetify 3 использует новый синтаксис.

Vuetify 2:

<v-text-field v-model="name"></v-text-field>

Vuetify 3:

<v-text-field
  v-model="name"
/>

В большинстве случаев код остаётся прежним, но внутри компонентов используется новый контракт:

  • prop: modelValue
  • событие: update:modelValue

Пример кастомного компонента:

defineProps({
  modelValue: String
})

defineEmits(['update:modelValue'])

Удалённые или переработанные компоненты

Часть компонентов была полностью исключена.

Наиболее заметные изменения:

Компонент Статус
v-data-iterator переработан
v-calendar временно отсутствует
v-treeview переписан
v-virtual-scroll новый API

Некоторые функции были перенесены в сторонние библиотеки.

Работа с иконками

Vuetify 3 использует новую систему конфигурации иконок.

import { aliases, mdi } from 'vuetify/iconsets/mdi'

createVuetify({
  icons: {
    defaultSet: 'mdi',
    aliases,
    sets: {
      mdi
    }
  }
})

В версии 2 иконки часто подключались через CDN или Sass.

Изменения в утилитах

Система display и breakpoint изменилась.

Vuetify 2:

this.$vuetify.breakpoint.mdAndUp

Vuetify 3:

import { useDisplay } from 'vuetify'

const display = useDisplay()

display.mdAndUp.value

Новая система полностью построена на Composition API.

Обновление директив

Некоторые директивы получили новые API.

Vuetify 2:

<div v-ripple></div>

Vuetify 3 требует регистрации директивы:

import { Ripple } from 'vuetify/directives'

createVuetify({
  directives: {
    Ripple
  }
})

Работа со стилями

Vuetify 3 уменьшает зависимость от Sass и активно использует CSS variables.

Подключение стилей:

import 'vuetify/styles'

При необходимости можно использовать Sass для дополнительной кастомизации.

Обновление layout системы

В Vuetify 2 layout строился вокруг v-app.

<v-app>
  <v-app-bar></v-app-bar>
  <v-main></v-main>
</v-app>

В Vuetify 3 структура стала более предсказуемой:

<v-app>
  <v-layout>
    <v-app-bar></v-app-bar>
    <v-main></v-main>
  </v-layout>
</v-app>

Компонент v-layout теперь играет центральную роль в построении интерфейса.

Пошаговая стратегия миграции

Процесс миграции обычно включает несколько этапов:

1. Обновление Vue до версии 3

Проверяется совместимость зависимостей проекта.

2. Установка Vuetify 3

Удаляется старая версия и добавляется новая.

3. Переписывание инициализации

Переход на createVuetify().

4. Исправление компонентов

Замена устаревших компонентов.

5. Обновление темизации

Переход с Sass на CSS variables.

6. Проверка реактивности

Использование Composition API для сервисов.

Типичные проблемы миграции

Несовместимость сторонних библиотек

Некоторые плагины поддерживают только Vuetify 2.

Изменение API компонентов

Часто требуется переписать props и события.

Проблемы со стилями

Sass-переменные больше не работают так же, как раньше.

Удалённые компоненты

Иногда приходится реализовывать альтернативы.

Подход к постепенной миграции

В крупных проектах используется постепенный переход:

  1. Обновление Vue.
  2. Миграция инфраструктуры.
  3. Переписывание компонентов интерфейса.
  4. Оптимизация темы.
  5. тестирование и стабилизация.

Такой подход уменьшает риск регрессий и упрощает контроль изменений.

Оглавление