Breaking changes

Unpoly, как фронтенд-фреймворк для прогрессивного улучшения веб-приложений, постоянно развивается. При обновлениях могут появляться breaking changes — изменения, которые нарушают совместимость с предыдущими версиями. Понимание этих изменений критически важно при обновлении приложений на Unpoly.

Изменения в API up.layer

В старых версиях доступ к слоям выполнялся через up.layer.get(), возвращавший объект слоя. Начиная с версии 2.x:

  • Метод up.layer.get() теперь возвращает null, если слой не найден. Ранее возвращался пустой объект.
  • Методы up.layer.open() и up.layer.close() требуют теперь явного указания селектора слоя или объекта конфигурации. Если передавался простой идентификатор, поведение стало строгим и вызовет ошибку при некорректном значении.

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

up.layer.open({
  url: '/posts/1',
  target: '#post-layer'
});

Ранее можно было написать:

up.layer.open('/posts/1', '#post-layer');

Теперь это приведет к исключению.

События и их обработчики

Механизм событий up.on также претерпел изменения:

  • События up:layer:opened и up:layer:closed больше не вызываются для скрытых или предварительно загруженных слоев.
  • Синтаксис именования событий строго проверяется: вместо 'up:layer:opened' допустим только 'up.layer:opened'.
  • Старые глобальные колбеки типа up.onLayerOpen(callback) удалены. Необходимо использовать новую форму:
up.on('up.layer:opened', (event) => {
  console.log(event.layer);
});

Изменения в поведении up.render

Метод up.render с версии 2.x имеет следующие ключевые изменения:

  • Параметр animation теперь по умолчанию отключён. Старые приложения, где не задавался animation, могут потерять плавные переходы.
  • При использовании up.render с селектором, который не существует в DOM, метод больше не создаёт автоматически контейнер. Необходимо явно создать элемент или использовать существующий селектор.
  • Параметр focus теперь не выполняет автоматическое смещение курсора на первый вводный элемент формы. Для восстановления старого поведения нужно передавать { focus: true } явно.

Пример нового вызова:

up.render('#comments', {
  url: '/posts/1/comments',
  animation: 'fade',
  focus: true
});

Работа с формами и up.submit

Unpoly всегда обеспечивал AJAX-поддержку форм. В новых версиях изменения затронули:

  • up.submit больше не выполняет автоматическую сериализацию файлов через FormData при старом синтаксисе. Нужно явно указывать { files: true }:
up.submit('#upload-form', { files: true });
  • Методы success и error теперь передаются через объект конфигурации, а не через позиционные аргументы:
up.submit('#form', {
  url: '/posts',
  success: (response) => console.log('OK', response),
  error: (response) => console.log('Ошибка', response)
});

Изменения в селекторах и целевых элементах

Старые версии Unpoly позволяли использовать нестрогие селекторы, например, '#layer, .extra'. Теперь:

  • Использование нескольких селекторов в одном параметре target приводит к исключению.
  • Селектор должен однозначно указывать на один контейнер. Если нужно обновить несколько элементов, требуется отдельный вызов up.render для каждого.

Настройки конфигурации

Глобальная конфигурация up.options претерпела следующие изменения:

  • up.options.animation теперь может быть только false или строкой с именем анимации ('fade', 'slide'). Старые boolean-параметры вроде { animation: true } больше не поддерживаются.
  • up.options.scroll больше не принимает числовое смещение. Теперь поддерживаются только значения 'top', 'center', 'bottom' или функция, возвращающая координату.

Резюме основных проблем при обновлении

  1. Методы up.layer стали строгими в аргументах и возвращаемых значениях.
  2. События переименованы, глобальные колбеки удалены.
  3. up.render и up.submit требуют явного указания параметров, ранее задававшихся по умолчанию.
  4. Селекторы и целевые элементы должны быть однозначными.
  5. Конфигурационные опции имеют более строгие типы и значения.

Эти изменения требуют внимательной проверки существующего кода при переходе на новые версии Unpoly, чтобы избежать неожиданных ошибок и некорректного поведения интерфейса.

Оглавление