Типы данных и интерфейсы

В Gridstack.js управление сеткой и виджетами осуществляется через определённые структуры данных, которые задают размеры, положение и свойства каждого элемента. Основными типами данных являются:

  • GridStackNode – описывает отдельный виджет в сетке. Содержит следующие ключевые свойства:

    • x, y – координаты виджета на сетке (по осям колонок и строк).
    • w, h – ширина и высота виджета в единицах сетки.
    • id – уникальный идентификатор виджета.
    • autoPosition – булевое значение, указывающее, должна ли сетка автоматически размещать элемент.
    • minWidth, maxWidth, minHeight, maxHeight – ограничения размеров виджета.
    • locked – блокировка перемещения или изменения размеров.
    • content – произвольный HTML или текст, который будет содержимым виджета.

  • GridStackOptions – набор конфигурационных параметров для инициализации сетки:

    • cellHeight – высота строки в пикселях или как функция для динамических размеров.
    • column – количество колонок сетки.
    • float – разрешает свободное перемещение виджетов без жесткой привязки к строкам.
    • animate – включает анимацию при перемещении или изменении размеров виджетов.
    • disableOneColumnMode – запрет режима одной колонки на мобильных устройствах.
    • resizable, draggable – объекты с настройками для изменения размеров и перетаскивания виджетов, включая handles, start, stop и resize события.
    • margin и cellHeight могут быть числовыми значениями или строками с CSS-единицами.

  • GridStackEventHandler – интерфейс для обработки событий:

    • События added, removed, change, dragstart, dragstop, resizestart, resizestop.
    • Каждый обработчик получает список GridStackNode объектов, которые изменились, и объект GridStack, где произошло событие.

Интерфейсы для взаимодействия с сеткой

Gridstack.js предоставляет богатый API, позволяющий управлять сеткой программно. Основные методы и интерфейсы:

  • GridStack – основной класс сетки:

    • addWidget(el: HTMLElement, options?: GridStackNode) – добавление нового виджета с настройками.
    • removeWidget(el: HTMLElement) – удаление виджета по элементу.
    • update(el: HTMLElement, options: Partial<GridStackNode>) – обновление параметров существующего виджета.
    • batchUpdate() / commit() – обертка для массового изменения виджетов без перерисовки после каждого изменения.
    • getGridItems(): GridStackNode[] – возвращает массив всех виджетов текущей сетки.
    • engine.nodes – внутренний массив всех узлов сетки для прямого доступа.

  • Draggable & Resizable interfaces:

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

      • handles – массив строк с указанием сторон, где активны маркеры изменения размеров.
      • start, stop, drag, resize – коллбэки для событий, вызываемые в момент действий пользователя.

  • Options для вложенных сеток:

    • Gridstack поддерживает вложенные сетки, каждая из которых имеет собственный объект GridStackOptions.
    • Вложенные сетки наследуют column, cellHeight, margin, но могут переопределять их локально.

Форматы данных для сериализации

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

  • save(): GridStackNode[] – возвращает массив объектов GridStackNode, пригодный для сохранения на сервер или в localStorage.
  • load(nodes: GridStackNode[]) – восстанавливает состояние сетки по массиву узлов.
  • Структура GridStackNode позволяет сохранять и дополнительные свойства, например customData, что делает возможным перенос виджетов между сетками без потери информации.

Взаимодействие с DOM и атрибутами

Каждый виджет в сетке представлен HTML-элементом с набором data-атрибутов, которые дублируют свойства GridStackNode:

  • data-gs-x, data-gs-y – позиция в сетке.
  • data-gs-width, data-gs-height – размеры виджета.
  • data-gs-min-width, data-gs-max-width, data-gs-min-height, data-gs-max-height – ограничения размеров.
  • Эти атрибуты позволяют инициализировать сетку из статической разметки без программного создания объектов.

Особенности типизации и TypeScript

Gridstack.js поставляется с полноценными типами для TypeScript:

  • GridStackNode, GridStackOptions, GridStackEventHandler уже описаны, что позволяет автодополнение и строгую проверку типов.
  • Использование Partial<GridStackNode> при обновлении виджетов упрощает изменение отдельных параметров без необходимости указывать все поля.
  • Возможность расширения интерфейсов через customData позволяет хранить бизнес-логику или привязывать данные виджетов к серверной модели.

Связь данных и поведения

Gridstack.js строит сетку на основе двухуровневой модели:

  1. Node-модель – хранит координаты, размеры и свойства виджетов.
  2. DOM-элементы – визуальная реализация, синхронизированная с Node-моделью.

Все изменения через API (добавление, удаление, перетаскивание) обновляют Node-модель, а затем синхронизируются с DOM. Аналогично, изменение data-атрибутов на DOM автоматически отражается на Node-модели при вызове grid.makeWidget(el).

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

Оглавление