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

Gridstack.js предоставляет гибкий механизм работы с виджетами в сетке. Виджет в Gridstack — это элемент DOM, обычно <div>, который может быть перемещаемым, изменяемым по размеру и динамически управляемым через API библиотеки. Каждый виджет характеризуется набором атрибутов: x, y, width, height, а также параметрами поведения, такими как locked, resizable и autoPosition.

<div class="grid-stack">
  <div class="grid-stack-item" gs-w="4" gs-h="2" gs-x="0" gs-y="0">
    <div class="grid-stack-item-content">Виджет 1</div>
  </div>
  <div class="grid-stack-item" gs-w="2" gs-h="2" gs-x="4" gs-y="0">
    <div class="grid-stack-item-content">Виджет 2</div>
  </div>
</div>
  • gs-w, gs-h — ширина и высота виджета в ячейках сетки.
  • gs-x, gs-y — координаты верхнего левого угла виджета.

Инициализация и базовые методы

Инициализация сетки осуществляется через конструктор GridStack.init:

const grid = GridStack.init({
  cellHeight: 100,
  float: true,
  animate: true
});
  • cellHeight — фиксированная высота ячеек.
  • float — разрешает перекрытие виджетов во время перемещения.
  • animate — включает анимацию при перемещении и изменении размера.

Добавление и удаление виджетов

Динамическое добавление виджетов выполняется через метод addWidget:

grid.addWidget(
  `<div class="grid-stack-item" gs-w="3" gs-h="2">
     <div class="grid-stack-item-content">Новый виджет</div>
   </div>`,
  { x: 0, y: 2 }
);

Удаление виджета:

const widget = document.querySelector('.grid-stack-item');
grid.removeWidget(widget);
  • Метод addWidget принимает как HTML-код виджета, так и объект с настройками (x, y, width, height).
  • removeWidget полностью удаляет виджет из сетки и DOM.

Перемещение и изменение размера виджетов

Gridstack.js позволяет управлять положением виджета программно:

const item = grid.getCellFromPixel({ left: 50, top: 100 });
grid.update(item.el, { x: 2, y: 1, w: 4, h: 2 });
  • update изменяет размеры и координаты виджета без необходимости пересоздавать элемент.
  • getCellFromPixel возвращает объект виджета, находящегося в указанных координатах пикселей.

Для блокировки перемещения и изменения размера используется свойство locked:

grid.update(widget, { locked: true });

События виджетов

Gridstack.js поддерживает широкий набор событий, связанных с виджетами:

  • added — срабатывает при добавлении нового виджета.
  • removed — срабатывает при удалении виджета.
  • change — вызывается при изменении размеров или позиции.
  • dragstart / dragstop — при начале и окончании перетаскивания.
  • resizestart / resizestop — при начале и окончании изменения размера.

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

grid.on('change', function(event, items) {
  items.forEach(item => {
    console.log(`Виджет ${item.el.innerText} перемещён в (${item.x}, ${item.y})`);
  });
});

Настройка поведения виджетов

Перетаскивание и ресайзинг можно включать или отключать для отдельных виджетов:

grid.makeWidget(widget); // Делает элемент виджетом Gridstack
grid.resizable(widget, false); // Отключает изменение размера
grid.draggable(widget, { handle: '.drag-handle' }); // Включает перетаскивание только по указанной области
  • makeWidget — инициализация DOM-элемента как виджета сетки.
  • draggable и resizable принимают опции для тонкой настройки поведения.

Сохранение и восстановление состояния сетки

Состояние сетки можно получить через метод save:

const serializedData = grid.save();
console.log(serializedData);
  • save возвращает массив объектов с параметрами всех виджетов (x, y, w, h, id и пользовательские атрибуты).

Для восстановления состояния используется load:

grid.removeAll(); // Очистка сетки
grid.load(serializedData); // Восстановление предыдущего состояния

Группировка и управление слоями виджетов

Gridstack.js позволяет управлять z-index виджетов и их перекрытием. Для этого используются методы move и события drag:

grid.on('dragstart', function(event, el) {
  el.style.zIndex = 100; // Поднимаем виджет над остальными
});
grid.on('dragstop', function(event, el) {
  el.style.zIndex = '';
});
  • Контроль слоя полезен при создании интерфейсов с наложением окон или панелей.

Программное управление сеткой

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

  • removeAll — удаление всех виджетов.
  • batchUpdate — временное отключение перерасчета сетки для групповых изменений:
grid.batchUpdate();
grid.update(widget1, { x: 0, y: 0 });
grid.update(widget2, { x: 4, y: 0 });
grid.commit(); // Применяет все изменения одновременно
  • commit применяет все изменения после batchUpdate, предотвращая лишние пересчёты и повышая производительность.

Расширенные возможности

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

const nestedGrid = GridStack.init({ cellHeight: 50 }, widget.querySelector('.grid-stack'));
  • Вложенные сетки наследуют методы родительской сетки (addWidget, removeWidget, update) и позволяют строить гибкие интерфейсы с множеством уровней виджетов.

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

Оглавление