Breaking changes

Библиотека Masonry для JavaScript известна своей гибкой системой построения сеток, однако при переходе между версиями разработчики сталкиваются с breaking changes, влияющими на совместимость и поведение кода. Эти изменения могут затрагивать как методы и API, так и обработку параметров и событий.

1. Изменения в инициализации

Ранее Masonry позволял инициализировать сетку следующим образом:

var msnry = new Masonry('.grid', {
  itemSelector: '.grid-item',
  columnWidth: 200,
  gutter: 10
});

В новых версиях:

  • Обязательные параметры могут быть переименованы. Например, columnWidth теперь рекомендуется указывать через элемент или функцию, а не только через число.
  • Передача строкового селектора вместо DOM-элемента иногда больше не поддерживается, требуется использовать document.querySelector или непосредственно элемент:
var grid = document.querySelector('.grid');
var msnry = new Masonry(grid, {
  itemSelector: '.grid-item',
  columnWidth: '.grid-sizer'
});
  • Использование старого метода Masonry.data() для получения экземпляра теперь может работать иначе, так как внутренняя структура хранения экземпляров была переработана.

2. Изменения в событиях

События layoutComplete, removeComplete, appendComplete теперь имеют другой порядок аргументов или обновлен способ их подписки. Пример старого синтаксиса:

msnry.on('layoutComplete', function(items) {
  console.log('Layout finished for', items.length, 'items');
});

В новых версиях необходимо учитывать:

  • Аргумент items теперь может быть массивом объектов с другими свойствами.
  • Некоторые события были удалены или заменены на новые, например, imagesLoaded интеграция изменилась.

3. Работа с динамическим контентом

До изменений часто использовался подход:

var elems = document.querySelectorAll('.new-items');
msnry.appended(elems);

Теперь для корректного отображения динамических элементов требуется:

  • Убедиться, что новые элементы полностью загружены (особенно изображения).
  • Использовать методы appended и layout в правильной последовательности:
imagesLoaded(newElems, function() {
  msnry.appended(newElems);
  msnry.layout();
});
  • Старые вызовы reloadItems() и layout() могут работать иначе, изменив внутреннее распределение элементов.

4. Изменения в API методов

Некоторые методы претерпели существенные изменения:

Метод (старый) Метод (новый) / изменение Примечание
reloadItems() Теперь рекомендуется использовать addItems() Более гибкая работа с новыми элементами
remove() Аргументы теперь требуют DOM-элемент, а не селектор Изменена обработка коллекций элементов
layout() Поддерживает дополнительные опции с новыми версиями Влияние на анимацию и пересчёт размеров

5. Параметры конфигурации

Ряд параметров был переименован или изменил тип значения:

  • fitWidth – сохраняет прежнее название, но поведение по умолчанию изменилось на false.
  • gutter – теперь допускает указание не только числа, но и строки с единицами CSS ('10px').
  • transitionDuration – значения типа 0 или undefined теперь трактуются иначе: для полного отключения анимации рекомендуется явно указать '0s'.

6. Совместимость с другими библиотеками

Ранее Masonry нередко использовался совместно с imagesLoaded и jQuery:

  • Поддержка jQuery плагина теперь частично устарела: рекомендуется использовать нативные методы.
  • Интеграция с imagesLoaded требует отдельного импорта и точного контроля загрузки изображений, иначе порядок элементов после layout может нарушаться.

7. Изменения в CSS-классификации

  • Внутренние классы masonry-item, masonry-column могут изменяться между версиями.
  • Стили сетки и отступов необходимо проверять после обновления, так как Masonry может переставлять элементы с учётом новых алгоритмов.

8. Рекомендации по миграции

  • Проверять документацию текущей версии на предмет удалённых методов и событий.
  • Использовать строгую типизацию и явное указание DOM-элементов.
  • Тестировать динамическое добавление и удаление элементов с учетом полной загрузки контента.
  • Проверять визуальные результаты после каждого изменения конфигурации, особенно для параметров columnWidth, gutter, fitWidth и transitionDuration.

9. Итоговые особенности breaking changes

  • API методов часто меняется, включая layout(), remove(), reloadItems().
  • События могут иметь другой формат аргументов или изменённый порядок вызова.
  • Конфигурационные параметры переименованы или изменили типы значений.
  • Динамические элементы требуют новой последовательности действий для корректного отображения.
  • Совместимость с jQuery и другими библиотеками частично ограничена, рекомендуется использовать нативные методы.

Эти изменения критичны при обновлении Masonry на новые версии и напрямую влияют на стабильность и визуальную консистентность сеток.

Оглавление