Утилитарные методы

Gridstack.js предоставляет мощный набор утилитарных методов, позволяющих работать с сеткой динамически, управлять виджетами и оптимизировать взаимодействие с DOM. Утилитарные функции можно разделить на несколько групп: методы работы с DOM, методы управления виджетами, методы конфигурации и вспомогательные функции для событий.

Работа с DOM

addWidget(el, opts)

Позволяет программно добавить виджет в сетку. Параметры:

  • el — DOM-элемент или HTML-строка с содержимым виджета.

  • opts — объект с настройками:

    • x, y — координаты на сетке.
    • width, height — размеры в ячейках.
    • id — уникальный идентификатор виджета.
    • autoPosition — если true, Gridstack автоматически разместит виджет в первой доступной позиции.

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

grid.addWidget('<div class="grid-stack-item"><div class="grid-stack-item-content">Контент</div></div>', 
               {x:0, y:0, width:3, height:2});

removeWidget(el, detachNode = true)

Удаляет виджет из сетки. Параметр detachNode определяет, удалять ли элемент из DOM или только из структуры сетки. Если передать false, элемент останется в DOM, что удобно для временного перемещения виджета.

grid.removeWidget(widgetEl, false);

makeWidget(el)

Преобразует обычный DOM-элемент в виджет Gridstack без необходимости создавать новый элемент вручную. Используется для динамического преобразования существующих элементов в сетке.

Управление положением и размерами

update(el, opts)

Обновляет позицию и размер виджета после его создания. Позволяет изменять координаты, размеры или идентификатор.

grid.update(widgetEl, {x:1, y:2, width:4, height:3});

resize(el, width, height)

Изменяет размеры виджета без изменения его позиции. Отличие от update — только изменение width и height.

move(el, x, y)

Перемещает виджет в новую позицию на сетке без изменения размеров. Полезно для реализации drag-and-drop или динамического упорядочивания.

Методы конфигурации сетки

batchUpdate()

Открывает блок для пакетного обновления виджетов. Все изменения будут применяться в одном цикле, что повышает производительность при работе с большим количеством элементов.

commit()

Закрывает блок пакетного обновления и применяет все изменения. Обычно используется в паре с batchUpdate().

grid.batchUpdate();
grid.update(widget1, {x:2, y:0});
grid.update(widget2, {x:0, y:1});
grid.commit();

enableMove(enable) / enableResize(enable)

Позволяет включить или отключить возможность перемещения и изменения размеров всех виджетов сетки. Принимает булевое значение.

grid.enableMove(false);
grid.enableResize(true);

Методы для поиска и получения данных

getGridItems()

Возвращает массив всех виджетов сетки с их текущими координатами и размерами. Каждый элемент массива содержит объект с полями: x, y, width, height, el.

getNode(el)

Возвращает внутреннюю структуру виджета Gridstack (GridStackNode), что позволяет анализировать состояние виджета без доступа к DOM.

getCellFromPixel({left, top})

Преобразует координаты в пикселях в координаты ячеек сетки, что полезно при работе с пользовательским drag-and-drop вне стандартного Gridstack.

Вспомогательные функции

isAreaEmpty(x, y, width, height)

Проверяет, свободна ли область сетки для размещения виджета заданного размера. Возвращает true, если пересечений с другими виджетами нет.

compact()

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

save() / load(nodes)

Позволяет сохранять состояние сетки в массив объектов (nodes) и загружать его обратно. Полезно для реализации сохранения конфигурации между сессиями пользователя.

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

Работа с событиями через утилиты

Gridstack.js поддерживает интеграцию с событиями без необходимости подписки напрямую через DOM. Например:

  • on('added', callback) — вызывается после добавления нового виджета.
  • on('removed', callback) — после удаления виджета.
  • on('change', callback) — при изменении позиции или размеров виджетов.
grid.on('change', function(event, items) {
  console.log('Изменились виджеты:', items);
});

Итоговая структура

Использование утилитарных методов позволяет:

  1. Динамически управлять виджетами без прямого вмешательства в DOM.
  2. Контролировать размеры и позиции элементов программно.
  3. Оптимизировать работу с большими сетками через пакетные обновления.
  4. Сохранять и восстанавливать состояние сетки.
  5. Упрощать интеграцию с внешними событиями и пользовательским взаимодействием.

Эти функции формируют ядро программного взаимодействия с Gridstack.js и обеспечивают гибкость при создании интерактивных дашбордов и адаптивных интерфейсов.

Оглавление