Переход с предыдущих версий

С переходом с предыдущих версий библиотеки Masonry изменился подход к инициализации и управлению сеткой. Ранее для создания сетки использовался простой вызов конструктора с передачей DOM-элемента и опций, теперь же объект Masonry создаётся через класс, и управление экземпляром осуществляется через его методы.

Пример старого подхода:

$('#grid').masonry({
  itemSelector: '.grid-item',
  columnWidth: 200,
  gutter: 10
});

Новый подход с использованием класса:

import Masonry from 'masonry-layout';

const grid = document.querySelector('#grid');
const masonry = new Masonry(grid, {
  itemSelector: '.grid-item',
  columnWidth: 200,
  gutter: 10
});

Ключевые изменения:

  • Поддержка модульного импорта, что улучшает интеграцию с современными сборщиками (Webpack, Vite).
  • Экземпляр Masonry теперь имеет собственные методы для управления сеткой, такие как layout(), reloadItems(), addItems() и remove().

Управление элементами и динамическая сетка

Ранее добавление и удаление элементов было ограничено использованием jQuery и прямого обновления DOM. В новой версии Masonry предоставляются методы для корректного обновления сетки при изменении содержимого:

// Добавление новых элементов
const items = document.querySelectorAll('.new-grid-item');
masonry.appended(items);

// Удаление элементов
const itemsToRemove = document.querySelectorAll('.grid-item-to-remove');
masonry.remove(itemsToRemove);
masonry.layout();

Особенности нового поведения:

  • Метод appended() автоматически добавляет новые элементы в раскладку сетки без необходимости полностью пересобирать сетку.
  • Метод remove() удаляет элементы и позволяет обновить сетку через вызов layout().
  • Метод reloadItems() позволяет пересчитать все элементы сетки, что необходимо при динамическом изменении размеров или классов элементов.

Изменения в настройках колонок и gutter

В предыдущих версиях columnWidth и gutter можно было задавать напрямую как числовые значения или через CSS-классы. В новой версии возможны следующие подходы:

  • Фиксированная ширина колонок:
const masonry = new Masonry(grid, {
  itemSelector: '.grid-item',
  columnWidth: 200,
  gutter: 20
});
  • Использование элемента для вычисления ширины колонок:
const masonry = new Masonry(grid, {
  itemSelector: '.grid-item',
  columnWidth: '.grid-sizer',
  gutter: '.gutter-sizer'
});

Такой подход позволяет создавать адаптивные сетки, где ширина колонок автоматически подстраивается под размер контейнера. Элементы .grid-sizer и .gutter-sizer задаются только один раз в DOM и не отображаются пользователю, выполняя роль ориентира для расчета размеров.

Поддержка событий

В новой версии Masonry события стали частью экземпляра и поддерживаются через стандартные методы on и off. Пример:

masonry.on('layoutComplete', function(items) {
  console.log('Сетка обновлена, элементов:', items.length);
});

masonry.on('removeComplete', function(items) {
  console.log('Элементы удалены:', items.length);
});

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

  • layoutComplete — срабатывает после завершения перестройки сетки.
  • removeComplete — после удаления элементов.
  • imagesLoaded — при использовании плагина imagesLoaded можно дождаться загрузки всех изображений перед раскладкой.

Работа с изображениями

Ранее Masonry не учитывал задержки загрузки изображений, что часто приводило к смещению элементов. Теперь интеграция с библиотекой imagesLoaded стала стандартной практикой:

import imagesLoaded from 'imagesloaded';

imagesLoaded(grid).on('progress', () => {
  masonry.layout();
});

Преимущества нового подхода:

  • Элементы корректно располагаются после полной загрузки изображений.
  • Исключается проблема «прыжков» сетки при динамическом контенте.

Миграция с jQuery

В предыдущих версиях Masonry тесно интегрировался с jQuery. В новой версии jQuery не является обязательным, что снижает зависимость и облегчает работу в современных проектах. Все методы теперь работают напрямую с DOM-элементами через чистый JavaScript.

Сравнение старого и нового синтаксиса:

Старый Новый
$('#grid').masonry({ ... }); new Masonry(document.querySelector('#grid'), { ... });
$('#grid').masonry('reloadItems') masonry.reloadItems()
$('#grid').masonry('layout') masonry.layout()
$('#grid').masonry('remove', items) masonry.remove(items); masonry.layout();

Практические рекомендации при переходе

  1. Перейти на модульный импорт и использовать класс Masonry вместо глобального объекта.
  2. Заменить все вызовы jQuery-методов Masonry на методы экземпляра.
  3. Проверить работу динамического добавления и удаления элементов через appended() и remove().
  4. При работе с изображениями использовать imagesLoaded для корректной раскладки.
  5. Использовать .grid-sizer и .gutter-sizer для адаптивных сеток и точного контроля ширины колонок.

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

Оглавление