GridStack.js: конструктор дашбордов и 6 живых примеров
Соберите рабочую панель прямо в статье: аналитика, задачи, заметки и мониторинг. 6 сценариев, 9 типов виджетов, перетаскивание, адаптивная сетка и экспорт JSON.
После отдельных UI-компонентов возникает следующий вопрос: как собрать из них удобный рабочий экран? Один пользователь хочет видеть задачи сверху, другому важнее диаграмма, третьему нужна большая заметка и минимум второстепенных блоков.
GridStack.js решает задачу перестраиваемой раскладки: виджеты можно перетаскивать, изменять в размерах, добавлять и удалять, а положение сохранять и восстанавливать. Библиотека написана на TypeScript, не требует jQuery и подходит для разных фронтенд-стеков (репозиторий GridStack).
В этой статье можно проверить не только движение прямоугольников. Ниже собраны шесть сценариев и девять типов виджетов: общие фильтры, задачи с пересчётом прогресса, заметки, учебный мониторинг и конструктор с экспортом.
Все показатели и события в мастерской учебные. Она не подключена к аналитике, WordPress-записям, задачам или серверам вашего сайта; изменения живут в памяти вкладки, пока вы не скачаете JSON.
Что делает GridStack, а что нужно написать самому
GridStack управляет геометрией: координатами, размерами, столкновениями блоков и адаптацией к числу колонок. Методы addWidget, update, removeWidget, save и load позволяют связать сетку с вашим интерфейсом (API GridStack).
Содержимое карточек, источники данных, фильтры и бизнес-логика остаются приложению. В наших примерах диаграмма, список задач и прогресс написаны отдельно; GridStack даёт им возможность занимать нужное место на экране, но не рассчитывает показатели за них.
- Раскладка: где находится блок и сколько ячеек занимает.
- Данные: текст заметки, выполненные задачи, выбранный период.
- Отображение: как конкретный виджет показывает эти данные.
Такое разделение полезно при сохранении проекта. Вместо произвольного HTML достаточно хранить тип виджета, стабильный ID, настройки и координаты; при восстановлении приложение само создаёт разрешённые компоненты.
Живая мастерская: соберите свой рабочий экран
Выберите сценарий и выполните задание над панелью. Для перемещения тяните блок за заголовок, для изменения размеров используйте нижний правый угол; кнопка «Развернуть» увеличивает мастерскую без сброса содержимого.
Если перетаскивание неудобно, нажмите заголовок виджета и задайте его координаты и размеры в настройках. Стрелки на сфокусированном заголовке перемещают блок, а Enter переводит к редактору; на телефоне каталог и настройки находятся под сеткой.
Кнопки «Отменить» и «Повторить» относятся к действиям в мастерской, а не к истории браузера. В памяти хранится до 30 изменений; для переноса проекта между устройствами скачайте JSON, а затем откройте его в мастерской.
Шесть сценариев применения
Аналитика сайта: один фильтр, несколько представлений
Переключите период с семи на тридцать дней. Сводное число, столбчатая диаграмма и таблица источников изменятся вместе: они используют одно состояние фильтра, а не три независимых набора кнопок.
Затем увеличьте диаграмму, уменьшите заметку или удалите ненужную таблицу. Так можно проверить идею персональной аналитической панели, не подключая реальные данные и не смешивая работу сетки с интеграцией API.
Панель проекта: задачи связаны с прогрессом
Отметьте завершённую задачу и посмотрите, как изменится процент готовности. Добавление новой задачи увеличивает общее количество, поэтому процент может уменьшиться: это нормальное следствие расчёта, а не декоративная анимация.
Список и прогресс можно расположить рядом либо один под другим. Несколько виджетов задач используют один массив, а каждое окно заметки хранит свой текст отдельно.
Редакционный план: бриф, этапы и справочные ссылки
Отредактируйте бриф публикации, отметьте этапы подготовки и измените расположение блоков. После экспорта JSON содержит и текст, и задачи, и раскладку: восстановление не ограничивается пустыми карточками.
Такой интерфейс можно использовать как прототип рабочего места автора или редактора. Для реальной совместной работы понадобятся серверное хранение, права доступа и правила разрешения конфликтов; в этой демонстрации их нет.
Мониторинг: событие меняет статус и журнал
Нажмите «Смоделировать сбой»: учебный поиск получит статус ошибки, а журнал покажет событие. Затем восстановите сервис и убедитесь, что новый статус виден сразу в рабочей панели.
В этом сценарии нет тайного опроса настоящего сервера: все события запускаются кнопками. Он показывает организацию интерфейса, в котором статус, история и заметка оператора находятся на одном экране.
Попробовать учебный мониторинг
Рабочий стол: собственный набор полезных блоков
Добавьте вторую заметку из каталога и назовите её «На следующую неделю». Выберите удобные размеры, внесите текст и сохраните набор: новая заметка независима от первой, но использует тот же механизм раскладки.
Кнопка «Зафиксировать раскладку» отключает случайные перемещения и изменение размеров. Это именно режим сетки, не запрет редактирования данных: задачи и текст внутри блоков остаются доступными.
Пустая сетка: конструктор с нуля
Выберите «С нуля» и добавьте первый блок. Затем дополните его связанными виджетами: например, список задач и прогресс, показатели и диаграмма либо состояние сервиса и журнал.
Мастерская ограничивает набор двадцатью блоками. Это наше ограничение для понятного публичного примера, а не заявленный предел самой библиотеки.
Быстрый старт и версия примера
Мастерская использует GridStack 14.1.0. В релизе этой версии есть изменения перетаскивания между сетками, автопрокрутки и исправления взаимодействий; версия закреплена в исходниках, чтобы пример не зависел от случайного обновления CDN (релиз 14.1.0).
npm install gridstack@14.1.0Подключите JavaScript и CSS библиотеки, создайте контейнер сетки и загрузите несколько блоков. Классы grid-stack, grid-stack-item и grid-stack-item-content участвуют в работе раскладки; при создании через API внутреннюю структуру генерирует библиотека (инициализация GridStack).
import { GridStack } from 'gridstack';
import 'gridstack/dist/gridstack.min.css';
const grid = GridStack.init({
column: 12,
cellHeight: 72,
margin: 6
}, document.querySelector('.grid-stack'));
grid.load([
{ id: 'summary', x: 0, y: 0, w: 6, h: 4, content: 'Сводка' },
{ id: 'notes', x: 6, y: 0, w: 6, h: 4, content: 'Заметки' }
]);Это минимальное знакомство с сеткой, а не полная реализация дашборда. Готовый проект мастерской содержит рендеринг виджетов, данные, историю, проверку импортируемых файлов и CSS; его можно скачать из блока «Код и готовый проект».
Как связать сетку с интерфейсом
Основной ключ в наших примерах: id. Сетка знает положение блока с этим ID, а приложение находит по нему тип виджета, заголовок и данные; переименование заголовка не ломает связь.
const widgets = [
{
id: 'note-1',
kind: 'note',
title: 'План публикации',
note: 'Проверить примеры перед публикацией',
x: 0, y: 0, w: 6, h: 4
}
];Для собственного содержимого предусмотрен GridStack.renderCB. В мастерской этот callback вызывает наш рендерер по ID, а не принимает произвольную HTML-разметку из импортированного файла (renderCB и создание виджетов).
GridStack.renderCB = (container, node) => {
renderWidget(container, node.id);
};События завершения перетаскивания и изменения размера удобно использовать для фиксации действия пользователя. Общий change также может появляться при программных изменениях, поэтому запись истории стоит отделить от служебной перестройки интерфейса (события и методы сетки).
Адаптивность: сохранять читаемость, а не только геометрию
У GridStack есть настройка columnOpts для адаптивного числа колонок. В мастерской при ширине сетки до 600 пикселей используется одна колонка: измеряется контейнер, поэтому правило действует и в узкой статье, и в режиме телефона (параметры GridStackOptions).
columnOpts: {
breakpoints: [{ w: 600, c: 1 }]
}Одной перестройки колонок недостаточно. Внутри виджета нужны перенос длинного текста, доступные кнопки и прокрутка содержимого, если пользователь сделал карточку слишком маленькой; эти детали в мастерской реализованы на уровне нашего CSS.
Проверьте переключатель «Просмотр»: сначала выберите телефон, затем верните ширину страницы. Экспорт запрашивает двенадцатиколоночную раскладку через параметр column метода save, чтобы не подменять её текущим одноколоночным представлением (сохранение раскладки).
Сохранение, импорт и безопасность
GridStack умеет сериализовать раскладку через save и восстановить её через load, сопоставляя блоки по ID. Данные вашего приложения нужно добавить к этому объекту отдельно (save и load).
const geometry = grid.save(false, false, undefined, 12);
// false: не сохраняем HTML содержимого.
// 12: запрашиваем раскладку для двенадцати колонок.
const project = {
schema: 1,
widgets: mergeGeometryAndWidgetData(geometry),
shared: { period, tasks, incident }
};В нашей мастерской импорт проходит несколько проверок. При ошибке текущая панель остаётся на месте, а сообщение объясняет причину.
- Размер: файл не больше 200 КБ, до 20 виджетов и 30 задач.
- Схема: версия проекта, известный сценарий и разрешённый тип каждого блока.
- Геометрия: целые координаты и размеры в допустимом диапазоне.
- Текст: ограниченная длина заголовков, задач и заметок; символы HTML экранируются перед отображением.
- Идентификаторы: уникальные ID, без которых восстановление стало бы неоднозначным.
Эти проверки относятся к нашему формату примера, не заменяют серверную валидацию в реальном продукте. Если панель хранится на сервере, добавьте проверку владельца проекта, разрешённых полей, ограничений объёма и доступа к источникам данных.
Управление без перетаскивания
Drag-and-drop удобен не всем, особенно на маленьком экране или при точной настройке. Поэтому рядом с сеткой есть обычная форма: название, колонка, строка, ширина и высота; она вызывает тот же update, который работает с геометрией блока (метод update).
На заголовках доступны клавиатурные действия, для форм есть подписи, а результаты импорта и изменений показываются текстом. Это полезная основа, но не обещание полной сертификации доступности: конкретный продукт нужно проверять с его содержимым и вспомогательными технологиями.
Следите и за режимом просмотра. В нашем варианте закрепление сетки запрещает перестановку, но намеренно не превращает заметки и задачи в поля только для чтения; для такого режима нужна отдельная логика приложения.
Когда GridStack подходит, а когда хватит CSS Grid
GridStack стоит попробовать, если пользователь должен самостоятельно менять рабочий экран: переставлять виджеты, регулировать их размер и сохранять набор. Библиотека также поддерживает несколько сеток и вложенные сетки, хотя эти возможности не включены в данную мастерскую (возможности проекта).
Если композиция фиксированная, начните с обычной CSS-вёрстки: интерактивный движок не нужен только ради нескольких колонок. А если блоки представляют этапы процесса со связями, полезнее посмотреть наш материал о Drawflow, где задача другая: редактирование нод и соединений.
Код GridStack распространяется под MIT; при распространении библиотеки необходимо сохранять уведомление об авторских правах и текст лицензии. В архиве мастерской они включены рядом с исходниками (лицензия GridStack).
Начните с одного полезного сценария: выберите набор, измените данные, перестройте панель и восстановите её из JSON. Если после этого понятно, как такой экран помогает пользователю, можно переходить к интеграции реальных данных.
Вернуться к мастерской или изучить исходный проект. Все шесть сценариев можно проверить прямо на этой странице.
