Deprecated функции

Понятие устаревания API

В процессе развития библиотек пользовательского интерфейса неизбежно происходят изменения в архитектуре компонентов, API и способах конфигурации. В экосистеме Vuetify устаревшими (deprecated) считаются функции, компоненты или параметры, которые сохраняются в библиотеке временно для обеспечения обратной совместимости, но уже не рекомендуются к использованию и будут удалены в будущих версиях.

Устаревание позволяет разработчикам постепенно мигрировать кодовую базу без резких изменений. Обычно такие элементы сопровождаются предупреждениями в консоли и соответствующими пометками в документации.

Основные причины устаревания:

  • изменение архитектуры библиотеки
  • оптимизация производительности
  • унификация API
  • устранение неоднозначного поведения
  • переход на более современный синтаксис

Механизм работы deprecated API

При использовании устаревших функций библиотека может:

  • выводить предупреждение в консоль
  • поддерживать старый синтаксис через внутренние адаптеры
  • автоматически преобразовывать старые параметры в новые
  • оставлять поддержку только в одной основной версии

Типичное предупреждение в консоли выглядит следующим образом:

[Vuetify] 'v-list-tile' is deprecated, use 'v-list-item' instead

Такие сообщения сигнализируют о необходимости обновления кода.

Устаревшие компоненты

v-list-tile → v-list-item

Одним из наиболее известных изменений стало удаление компонента v-list-tile, который использовался в старых версиях.

Старый синтаксис:

<v-list>
  <v-list-tile>
    <v-list-tile-title>Item</v-list-tile-title>
  </v-list-tile>
</v-list>

Новый синтаксис:

<v-list>
  <v-list-item>
    <v-list-item-title>Item</v-list-item-title>
  </v-list-item>
</v-list>

Причины изменения:

  • упрощение структуры компонентов
  • повышение читаемости
  • унификация названий

v-toolbar-side-icon → v-app-bar-nav-icon

Ранее для отображения кнопки меню использовался компонент v-toolbar-side-icon.

Старый код:

<v-toolbar>
  <v-toolbar-side-icon @click="drawer = !drawer"></v-toolbar-side-icon>
</v-toolbar>

Актуальная версия:

<v-app-bar>
  <v-app-bar-nav-icon @click="drawer = !drawer"></v-app-bar-nav-icon>
</v-app-bar>

Изменение связано с переходом от v-toolbar к более универсальному компоненту v-app-bar.

v-content → v-main

Компонент v-content был заменён на v-main.

Старый вариант:

<v-app>
  <v-content>
    <router-view></router-view>
  </v-content>
</v-app>

Современный вариант:

<v-app>
  <v-main>
    <router-view></router-view>
  </v-main>
</v-app>

Это изменение отражает переработку системы layout-компонентов.

Устаревшие свойства (props)

flat → variant=“text”

Свойство flat в некоторых компонентах кнопок было заменено более гибкой системой вариантов.

Старый код:

<v-btn flat>Button</v-btn>

Новый подход:

<v-btn variant="text">Button</v-btn>

Преимущества нового API:

  • единая система вариантов
  • расширяемость
  • лучшая совместимость с темами

dense → density

Параметр dense использовался для уменьшения вертикальных отступов.

Старый синтаксис:

<v-list dense>
</v-list>

Новый синтаксис:

<v-list density="compact">
</v-list>

Новая система плотности поддерживает несколько значений:

  • default
  • comfortable
  • compact

hide-details → messages / error-messages

В старых версиях hide-details использовался для скрытия вспомогательного текста в полях ввода.

Пример:

<v-text-field hide-details></v-text-field>

В новых версиях управление деталями осуществляется через систему сообщений:

<v-text-field
  :messages="[]"
></v-text-field>

или

<v-text-field
  :error-messages="errors"
></v-text-field>

Устаревшие слоты

В ранних версиях Vuetify использовалась система именованных слотов с устаревшим синтаксисом.

Старый вариант:

<template slot="activator">

Современный синтаксис Vue:

<template v-slot:activator>

или сокращённая форма:

<template #activator>

Такие изменения связаны не столько с Vuetify, сколько с эволюцией Vue.

Устаревшие события

Некоторые события были переименованы или заменены.

input → update:modelValue

Во многих компонентах событие input заменено на стандарт v-model нового поколения.

Старый вариант:

<v-text-field
  :value="name"
  @input="name = $event"
></v-text-field>

Новый подход:

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

или явное событие:

<v-text-field
  :model-value="name"
  @update:modelValue="name = $event"
></v-text-field>

Устаревшие стили и классы

Некоторые CSS-классы больше не поддерживаются.

Пример устаревшего класса:

hidden-xs-only

Новый подход основан на более универсальной системе display utilities:

d-none d-sm-flex

Такая система:

  • соответствует современным стандартам CSS
  • унифицирует responsive-утилиты
  • делает код более предсказуемым

Стратегии миграции

Постепенное обновление

При работе с крупными проектами обновление рекомендуется выполнять поэтапно:

  1. обновление версии Vuetify
  2. анализ предупреждений консоли
  3. замена deprecated компонентов
  4. проверка layout-компонентов
  5. тестирование интерфейса

Использование официальных migration guide

Каждый крупный релиз Vuetify сопровождается руководством по миграции, где перечислены:

  • удалённые компоненты
  • переименованные props
  • изменённые события
  • новые архитектурные решения

Автоматические инструменты

Для некоторых переходов могут использоваться:

  • codemods
  • ESLint правила
  • IDE-подсказки
  • поиск и замена по проекту

Например:

v-list-tile → v-list-item
v-content → v-main
dense → density="compact"

Риски использования deprecated функций

Использование устаревших возможностей приводит к ряду проблем:

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

Новые версии библиотеки могут полностью удалить поддержку старых API.

Снижение производительности

Внутренние адаптеры, поддерживающие старый код, могут замедлять работу компонентов.

Усложнение поддержки проекта

Команда разработчиков вынуждена поддерживать устаревший синтаксис.

Повышенный риск ошибок

Некоторые deprecated функции могут работать нестабильно или частично.

Обнаружение устаревшего кода

Наиболее распространённые методы:

Предупреждения консоли

Vuetify автоматически сообщает о deprecated элементах.

[Vuetify] v-content is deprecated, use v-main

Статический анализ

Инструменты:

  • ESLint
  • TypeScript
  • IDE анализаторы

Поиск по документации

Deprecated элементы обычно помечаются специальными метками:

@deprecated

или

⚠ Deprecated

Политика версионирования Vuetify

Vuetify придерживается принципов Semantic Versioning:

MAJOR.MINOR.PATCH

Где:

MAJOR

  • возможное удаление deprecated API

MINOR

  • добавление новых функций
  • начало процесса устаревания

PATCH

  • исправления ошибок

Таким образом, deprecated функции обычно удаляются только в следующем major-релизе.

Практические рекомендации при работе с deprecated API

Не добавлять устаревшие функции в новый код

Даже если они ещё поддерживаются.

Регулярно обновлять зависимости

Это позволяет обнаруживать устаревшие элементы на раннем этапе.

Использовать современный синтаксис Vue

Особенно:

  • v-model
  • v-slot
  • Composition API

Следить за changelog

Изменения API публикуются в каждом релизе.

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

Обновление layout

Старый вариант:

<v-app>
  <v-content>
    <router-view/>
  </v-content>
</v-app>

Новый вариант:

<v-app>
  <v-main>
    <router-view/>
  </v-main>
</v-app>

Обновление списков

Старый код:

<v-list-tile>
  <v-list-tile-content>
    <v-list-tile-title>Item</v-list-tile-title>
  </v-list-tile-content>
</v-list-tile>

Новый код:

<v-list-item>
  <v-list-item-title>Item</v-list-item-title>
</v-list-item>

Обновление кнопок

Старый синтаксис:

<v-btn flat color="primary">

Новый синтаксис:

<v-btn variant="text" color="primary">

Эволюция API Vuetify

Развитие Vuetify показывает переход:

Vuetify 1

  • большое количество специализированных компонентов
  • сложная вложенность

Vuetify 2

  • упрощение структуры
  • стандартизация компонентов

Vuetify 3

  • новая архитектура
  • улучшенная система тем
  • переработанная система layout
  • Composition API

В процессе этих изменений значительная часть старого API была помечена как deprecated, а затем полностью удалена.

Оглавление