Breaking changes между версиями

Quasar Framework активно развивается, и каждая новая версия может содержать изменения, которые ломают совместимость с предыдущими версиями. Основные breaking changes обычно касаются компонентов, утилит и конфигурации сборки. Важно понимать, что код, работающий в одной версии, может потребовать существенной переработки при обновлении.

Удаление устаревших свойств компонентов Компоненты Quasar периодически избавляются от устаревших пропсов и событий. Например:

  • В некоторых версиях был удалён проп dense в некоторых специфических компонентах, заменённый на более универсальный подход через class="q-pa-xs".
  • Проп flat для кнопок в последних версиях имеет изменённую логику отображения: теперь он влияет не только на тень, но и на внутреннюю стилизацию границ.

Изменения событий компонентов

  • События типа @input для некоторых формовых компонентов могут быть заменены на @update:model-value, что связано с переходом на v-model с синтаксисом model-value.
  • Для компонентов QSelect, QAutocomplete и QDate произошла унификация работы с событиями @change и @input, что требует переработки обработчиков данных.

Модификация системы маршрутизации и плагинов

Vue Router и Quasar

  • Стандартный способ подключения Vue Router в проекте на Quasar мог измениться: старые хелперы для lazy-loading страниц заменены на асинхронный синтаксис через defineAsyncComponent.
  • В quasar.conf.js могут быть удалены устаревшие ключи, такие как supportIE или extendWebpack, которые теперь требуют использования новых хуков vitePlugins или viteExtendConfig.

Плагины Quasar

  • Некоторые плагины, например Dialog и Notify, изменили методы вызова. Старые методы типа this.$q.dialog({...}) могут оставаться, но теперь рекомендуется использовать строгий типизированный вызов с Dialog.create({...}).
  • Параметры конфигурации по умолчанию для Notify были пересмотрены: timeout, position и color имеют новые значения по умолчанию, что может изменить поведение уведомлений после обновления.

Стилизация и CSS

Переход на новую систему CSS переменных

  • Старые SCSS-переменные для темы ($primary, $secondary) были заменены на CSS-переменные --q-primary, --q-secondary. Это изменение требует адаптации всех пользовательских стилей.
  • Изменения в системах dark/light mode: методы установки темы через this.$q.dark.set(true) остаются, но некоторые компоненты начали использовать новые свойства для динамического переключения цветов, что может ломать старую стилизацию.

Классы утилит

  • Классы типа q-mt-md, q-pa-sm остаются, но появились новые, более точные: q-mt-xs, q-pa-xl, что требует проверки существующего CSS и замены при необходимости для сохранения визуального соответствия.

Обновления CLI и сборки

Переход на Vite

  • В последних версиях Quasar отказался от Webpack в пользу Vite как основной системы сборки. Это изменяет логику конфигурации, путь подключения плагинов, а также методы импорта ресурсов.
  • Параметры quasar dev и quasar build теперь имеют отличия в обработке ассетов: например, изображения меньше 10кБ автоматически инлайнются в код, что раньше контролировалось через url-loader.

Конфигурация quasar.config.js

  • Старый файл quasar.conf.js полностью заменён на quasar.config.js с новым API. Опции framework, plugins, cssAddon и extras теперь имеют строгую типизацию и могут вызвать ошибки при старой структуре.

Поддержка TypeScript и Composition API

  • В новых версиях Quasar официально поддерживается Composition API. Старый Options API продолжает работать, но интеграция с компонентами, использующими ref и reactive, может потребовать переписывания логики обработки состояния.
  • Типизация компонентов Quasar стала более строгой: пропсы, события и слоты теперь полностью типизированы, что повышает безопасность кода, но может вызвать ошибки при прямом обновлении с версии без TypeScript.

Рекомендации при обновлении

  1. Перед обновлением обязательно изучить changelog каждой версии, особенно секцию breaking changes.
  2. Проверять устаревшие пропсы и методы компонентов через документацию: многие из них получили альтернативные варианты с новой логикой.
  3. В проектах с Webpack переход на Vite потребует пересмотра всех настроек импорта, ассетов и плагинов.
  4. Переписать обработку событий формовых компонентов с v-model на новый синтаксис model-value.
  5. Пересмотреть пользовательские стили, особенно если они использовали SCSS-переменные Quasar: заменить их на CSS-переменные и новые утилитарные классы.

Breaking changes в Quasar чаще всего направлены на унификацию API, упрощение темы и улучшение поддержки современных инструментов сборки. Игнорирование этих изменений может привести к неработающим компонентам, некорректной стилизации и ошибкам при сборке проекта.

Оглавление