Базовая конфигурация

Для работы с Gridstack.js необходимо подключить библиотеку к проекту. Существует два основных способа: через CDN или установкой через npm/yarn.

CDN-подключение:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gridstack/dist/gridstack.min.css" />
<script src="https://cdn.jsdelivr.net/npm/gridstack/dist/gridstack-h5.js"></script>

Установка через npm:

npm install gridstack

После установки через npm необходимо импортировать модули в проект:

import { GridStack } from 'gridstack';
import 'gridstack/dist/gridstack.min.css';

Это создаёт доступ к основным классам и методам библиотеки.

Создание сетки

Gridstack.js оперирует сетками (grid) и виджетами (widgets). Сетка — это контейнер, в котором располагаются виджеты. Для инициализации сетки используется метод GridStack.init(options, container).

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

Основные параметры инициализации:

  • column – количество колонок в сетке (по умолчанию 12).
  • margin – отступ между виджетами в пикселях.
  • disableOneColumnMode – отключает автоматический переход в одну колонку при узком экране.
  • float – разрешает виджетам свободно перемещаться вверх и вниз (по умолчанию false).
  • staticGrid – если true, виджеты становятся неподвижными, без возможности перетаскивания и изменения размеров.

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

Виджет — это элемент сетки, который можно перетаскивать и изменять его размеры. Для создания виджета используется метод addWidget(el, options).

grid.addWidget(
  `<div class="grid-stack-item" gs-x="0" gs-y="0" gs-width="4" gs-height="2">
     <div class="grid-stack-item-content">Виджет 1</div>
   </div>`
);

Опции виджета:

  • x и y – координаты в сетке.
  • width и height – размеры виджета в колонках и строках.
  • autoPosition – если true, виджет автоматически разместится в первой доступной позиции.
  • id – уникальный идентификатор виджета для дальнейшей манипуляции.
  • minWidth, maxWidth, minHeight, maxHeight – ограничения на размер.

Использование атрибутов gs-x, gs-y, gs-width, gs-height в HTML-структуре позволяет задавать позицию и размер виджета прямо в разметке.

Перетаскивание и изменение размеров

Gridstack.js поддерживает drag-and-drop и динамическое изменение размеров.

Включение/отключение перетаскивания:

grid.enableMove(true); // включить
grid.enableMove(false); // отключить

Включение/отключение изменения размеров:

grid.enableResize(true); // включить
grid.enableResize(false); // отключить

Можно задать ограничения для изменения размеров:

grid.update(widget, { minWidth: 2, maxWidth: 6, minHeight: 1, maxHeight: 3 });

События

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

  • added – когда виджет добавлен в сетку.
  • removed – когда виджет удалён.
  • change – когда виджет перемещён или изменён размер.
  • dragstart, drag, dragstop – этапы перетаскивания.
  • resizestart, resize, resizestop – этапы изменения размеров.

Пример подписки на событие:

grid.on('change', function(event, items) {
  items.forEach(item => {
    console.log(`Виджет ${item.id} изменён: x=${item.x}, y=${item.y}`);
  });
});

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

Gridstack.js умеет автоматически перестраивать сетку под разные размеры экрана.

  • oneColumnModeDomSort – определяет порядок виджетов при переходе в одноколоночный режим.
  • minWidth – ширина окна, при которой активируется одноколоночный режим.
const grid = GridStack.init({
  column: 12,
  minWidth: 768,
  oneColumnModeDomSort: true
});

При меньшей ширине виджеты автоматически выстраиваются в один столбец с сохранением логического порядка.

Управление состоянием сетки

Gridstack.js позволяет сохранять и восстанавливать состояние сетки:

Сохранение состояния:

const serializedData = grid.save();
console.log(serializedData);

Восстановление состояния:

grid.load(serializedData);

Структура данных включает координаты, размеры и уникальные идентификаторы виджетов, что позволяет полностью восстановить расположение после перезагрузки страницы.

Настройка внешнего вида виджетов

Каждый виджет имеет элемент с классом grid-stack-item-content. Внутри него можно размещать любую разметку: текст, изображения, кнопки.

Пример стилизации:

.grid-stack-item-content {
  background-color: #4CAF50;
  color: white;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: bold;
}

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

Итоговые рекомендации по базовой конфигурации

  • Начинается с подключения библиотеки и инициализации сетки.
  • Виджеты можно добавлять через HTML или JS с полным набором параметров.
  • События позволяют отслеживать изменения и управлять интерактивностью.
  • Адаптивность обеспечивается встроенными опциями, включая одноколоночный режим.
  • Состояние сетки можно сохранять и восстанавливать для динамических приложений.

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

Оглавление