Изменения в API

Gridstack.js с каждой версией подвергается значительным изменениям в API, направленным на повышение гибкости, удобства использования и совместимости с современными фреймворками. В последних версиях разработчики сосредоточились на переработке методов управления сеткой, улучшении событийной модели и введении нового подхода к работе с виджетами.

Инициализация и конфигурация сетки

Ранее инициализация сетки осуществлялась через прямое создание экземпляра GridStack() или через jQuery:

$('.grid-stack').gridstack(options);

В новых версиях рекомендуемый способ — использование класса GridStack.init():

import { GridStack } from 'gridstack';

const grid = GridStack.init({
  column: 12,
  cellHeight: 80,
  margin: 10
});

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

  • Убрана полная зависимость от jQuery. Теперь библиотека работает нативно через ES6-модули.
  • Опции конфигурации централизованы и расширены. Появились новые параметры: float, animate, minRow, maxRow.
  • Метод GridStack.init() возвращает экземпляр сетки, который можно хранить для дальнейшей работы.

Управление виджетами

Добавление и удаление элементов стало более гибким. Ранее методы выглядели так:

grid.addWidget(el, x, y, width, height);
grid.removeWidget(el);

Сейчас API предлагает:

const widget = grid.addWidget({
  x: 0, y: 0, width: 4, height: 2,
  content: '<div class="grid-stack-item-content">Пример</div>'
});

grid.removeWidget(widget.el);

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

  • Метод addWidget возвращает объект GridItem, содержащий ссылку на элемент el и внутренние свойства позиции и размеров.
  • Добавлена поддержка передачи HTML-контента напрямую через параметр content.
  • Удаление виджетов теперь гарантирует корректное обновление внутреннего состояния сетки.

События и колбэки

Ранее события отслеживались через jQuery:

$('.grid-stack').on('change', function(event, items) {
  console.log(items);
});

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

grid.on('change', function(event, items) {
  console.log(items);
});

grid.on('added', function(event, items) {
  console.log('Добавлены виджеты:', items);
});

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

  • Полная поддержка событий added, removed, change, dragstart, dragstop, resizestart, resizestop.
  • Каждый обработчик получает массив объектов GridItem, что упрощает работу с позициями и размерами.
  • Возможность отключать анимацию и отслеживание событий через опцию animate при инициализации.

Обновление позиций и размеров

Методы update() и resize() получили расширенные возможности. Пример обновления виджета:

widget.update({x: 2, y: 1, width: 6, height: 3});

Новые возможности:

  • Можно обновлять сразу несколько параметров через объект.
  • Изменения автоматически пересчитывают сетку и вызывают событие change.
  • Поддержка анимации при изменении позиции через глобальную настройку animate.

Методы сериализации и восстановления состояния

Для сохранения состояния сетки введены новые методы save() и load():

const state = grid.save();
grid.load(state);

Особенности:

  • Метод save() возвращает массив объектов GridItem, содержащий позицию, размер и идентификатор каждого виджета.
  • Метод load() восстанавливает сетку с предыдущими настройками.
  • Позволяет реализовать функционал drag-and-drop с сохранением состояния между перезагрузками страницы.

Поддержка мобильных устройств и адаптивность

Новые версии API расширяют возможности адаптивного дизайна:

  • Метод column() позволяет динамически менять количество колонок в зависимости от ширины экрана:
grid.column(6);
  • Появилась поддержка autoCellHeight для автоматического подбора высоты ячеек.
  • Опция disableOneColumnMode позволяет отключать мобильный режим по необходимости.

Новые утилитарные методы

  • compact() — оптимизация сетки, автоматическое сжатие виджетов.
  • batchUpdate() / commit() — группировка изменений для предотвращения лишних перерисовок.
  • engine.nodes — доступ к внутреннему массиву виджетов, теперь публичный и безопасный для чтения.

Резюме ключевых изменений

  1. Инициализация через GridStack.init() вместо jQuery.
  2. Методы addWidget и removeWidget возвращают/принимают объекты GridItem.
  3. Новая событийная модель с расширенным набором событий.
  4. Расширенные методы обновления позиций, размеров и сериализации состояния.
  5. Улучшенная поддержка адаптивности и мобильных устройств.
  6. Появление утилитарных методов для оптимизации и управления множественными изменениями.

Эти изменения делают работу с Gridstack.js более модульной, предсказуемой и удобной для интеграции с современными фронтенд-фреймворками, такими как React и Vue.js.

Оглавление