Breaking changes

В новых версиях Element Plus часто появляются изменения, которые могут нарушить работу существующего кода. Эти изменения, называемые breaking changes, требуют особого внимания при обновлении библиотек и зависимостей. Разберём ключевые аспекты, на которые следует обратить внимание.

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

  1. ElTable и ElTableColumn

    • Ранее допустимые свойства show-overflow-tooltip теперь требуют явного указания типа Boolean.
    • Методы для динамического обновления колонок (setColumnWidth, clearSelection) были пересмотрены. Использование старых методов может вызывать ошибки.
    • Слот default в ElTableColumn теперь обрабатывается иначе: если слоты не определены, таблица не отобразит содержимое ячеек.

  2. ElForm и ElFormItem

    • Свойство rules теперь ожидает массив объектов с обязательным полем trigger. Игнорирование trigger приводит к тому, что валидация не срабатывает.
    • Метод validateField теперь возвращает Promise вместо callback. Старый синтаксис с функцией обратного вызова устарел.
    • Свойство label-width теперь поддерживает только строковые значения с единицами измерения (px, em), числовой формат без единиц больше не применяется.

  3. ElInput

    • v-model больше не поддерживает синтаксис value.sync. Необходимо использовать стандартный v-model с обновлённым синтаксисом Vue 3.
    • Свойство type="textarea" больше не автоматически расширяет поле ввода. Для автоскролла требуется использование autosize с объектом конфигурации { minRows, maxRows }.

Изменения в API

  • useMessage и useNotification

    • Методы closeAll() теперь асинхронные и возвращают Promise.
    • Объекты конфигурации сообщений теперь требуют явного указания type (success, warning, error, info). Ранее это свойство было опциональным.

  • GlobalConfig

    • Глобальная настройка size и zIndex теперь наследуется только компонентами, созданными после установки конфигурации. Компоненты, уже созданные до вызова app.use(ElementPlus, { size, zIndex }), не получают обновления.

  • Компоненты с динамическим рендерингом

    • Методы appendToBody и teleport изменены: теперь они требуют явного указания родителя через teleport prop. Без этого всплывающие окна и модальные окна могут рендериться некорректно.

Изменения в стилях и CSS-переменных

  • Переменные CSS --el-color-primary, --el-border-radius-base изменили свои значения по умолчанию. Если в проекте используются кастомные темы, их нужно пересмотреть.
  • Классы is-disabled, is-active были переработаны для некоторых компонентов (ElButton, ElTabs). Старые селекторы CSS могут не срабатывать.
  • Для компонентов с анимацией (ElCollapse, ElDialog) были обновлены переходы: старые кастомные transition-классы могут работать некорректно.

Практические советы при обновлении

  • Проверка пакета: перед обновлением внимательно изучать CHANGELOG на официальном GitHub репозитории Element Plus.
  • Тестирование всех компонентов: даже если изменения кажутся мелкими, они могут влиять на работу сложных форм и таблиц.
  • Миграция API: переписать устаревшие методы и свойства под новый синтаксис, особенно там, где добавлена асинхронность или обязательные параметры.
  • Рефакторинг CSS: пересмотреть кастомные темы и стили, привязанные к устаревшим классам или переменным.

Особенности версий

  • Начиная с версии 2.3.x, большинство breaking changes связано с полной поддержкой Vue 3 и удалением устаревших Vue 2 паттернов.
  • Версия 2.2.x внесла значительные изменения в валидацию форм и слоты таблиц.
  • Любые патчи после 2.4.0 включают минимальные исправления, но требуют проверки teleport, message и notification API.

Заключение для практического применения

Учитывание breaking changes критично для стабильной работы приложений на Element Plus. Основное внимание следует уделять:

  • Обновлению API компонентов и методов.
  • Проверке всех кастомных стилей и переменных CSS.
  • Корректной миграции слотов и синтаксиса v-model.
  • Асинхронным изменениям в глобальных методах уведомлений и модальных окон.

Правильная работа с breaking changes позволяет избежать внезапных ошибок после обновления и поддерживать проект на современном и стабильном стеке Element Plus.

Оглавление