Архитектура Kepler.gl построена вокруг однонаправленного потока
данных и централизованного состояния на базе Redux. Любое изменение
карты, наборов данных или визуальных слоёв проходит через слой действий
(actions), редьюсеров и подписок. Поверх этого слоя предоставляется
система событий и «хуков», позволяющая интегрировать внешнюю логику в
жизненный цикл карты.
Ключевая особенность модели — отсутствие классических DOM-событий.
Вся интерактивность выражается через:
- callback-пропсы React-компонента KeplerGl
- подписки на Redux store
- обработку actions Kepler.gl
- декстопные и map-view события deck.gl, инкапсулированные в слои
React-компонент
KeplerGl и событийные пропсы
Основная точка интеграции — компонент KeplerGl. Он выступает
контейнером, внутри которого создаётся и управляется карта.
onStateChange
Срабатывает при любом изменении состояния приложения Kepler.gl.
Внутреннее состояние включает:
- datasets
- visState (слои, фильтры, взаимодействия)
- mapState (viewport, zoom, pitch, bearing)
- mapStyle
Сигнатура обычно отражает новое состояние и тип вызванного
действия.
Типовые сценарии:
- синхронизация состояния с внешним Redux store
- сохранение конфигурации карты
- аудит пользовательских действий
Особенность: частота вызовов высокая, особенно при интерактивных
изменениях фильтров и viewport.
onViewStateChange
Отдельный канал для изменений камеры карты:
- центр координат
- масштаб (zoom)
- наклон (pitch)
- вращение (bearing)
Этот callback часто используется для:
- синхронизации нескольких карт
- связывания карты с внешними UI-компонентами (ползунки,
таймлайны)
- кастомной логики ограничения перемещения
В отличие от общего onStateChange, этот callback изолирован и не
содержит информации о слоях или данных.
onMapClick и взаимодействия
Kepler.gl не всегда напрямую экспонирует низкоуровневые DOM события
карты, но взаимодействие с объектами реализуется через deck.gl
picking-механику.
События клика по объектам включают:
- координаты точки
- выбранный объект (feature)
- слой (layer)
- индекс данных
Типичные сценарии:
- раскрытие кастомных попапов
- загрузка связанных данных
- построение drill-down аналитики
Redux как основной механизм
событий
Внутренняя архитектура Kepler.gl полностью опирается на Redux store.
Любое событие в системе представлено action-объектом.
Основные категории actions
mapState actions
- обновление viewport
- изменение масштаба
- изменение центра карты
visState actions
- добавление/удаление слоёв
- фильтрация данных
- обновление конфигурации визуализации
- взаимодействие с легендой
dataset actions
- добавление новых источников данных
- обновление таблиц
- удаление наборов данных
uiState actions
- управление интерфейсными панелями
- переключение модальных окон
- управление состоянием tooltip и popover
Подписка на store позволяет реализовать глобальную событийную
систему, независимую от React-слоя.
Подписка на store
и наблюдение за изменениями
Redux store Kepler.gl может использоваться как единый источник
событий через subscribe-механизм.
При каждом dispatch происходит:
- вычисление нового состояния
- сравнение с предыдущим состоянием
- уведомление подписчиков
Типовой паттерн:
- отслеживание изменения datasets для синхронизации с backend
- логирование изменений visState
- сохранение mapState в local storage
Особенность Kepler.gl заключается в том, что состояние может быть
глубоко вложенным, поэтому эффективные подписки часто строятся через
селекторы (selectors), минимизирующие лишние вычисления.
События слоёв (Layer
interactions)
Каждый слой Kepler.gl основан на deck.gl и наследует его модель
взаимодействия.
Hover события
Срабатывают при наведении курсора на объект слоя.
Передаваемая информация:
- объект данных
- позиция курсора
- индекс данных
- слой-источник
Используется для:
- отображения tooltip
- динамического выделения объектов
- контекстной подсветки
Click события
Обработка клика по геометрии слоя:
- точки (scatterplot layer)
- полигоны (geojson layer)
- линии (path layer)
- hexagon grid
Результат:
- выбранный объект
- координаты
- метаданные слоя
Selection events
Некоторые слои поддерживают множественный выбор:
- brush selection
- polygon selection
- bounding box selection
Событие выбора влияет на visState и может изменять фильтрацию данных
в реальном времени.
События фильтров (Filters
lifecycle)
Фильтры в Kepler.gl являются реактивными элементами visState. Каждое
изменение фильтра порождает событие изменения состояния.
Типы фильтров
- числовые диапазоны
- временные фильтры
- категориальные фильтры
Событийная модель
При изменении фильтра происходит:
- пересчёт набора отображаемых данных
- триггер обновления слоёв
- dispatch action в Redux
Фильтры часто используются как источник временных событий для
аналитики:
- изменение диапазона дат
- интерактивное сужение выборки
- динамическое агрегирование
События dataset lifecycle
Добавление и управление данными является отдельным жизненным
циклом.
Добавление dataset
При импорте данных происходит цепочка событий:
- парсинг данных
- создание table schema
- генерация column metadata
- интеграция в visState
Обновление dataset
Любое изменение данных вызывает:
- перерасчёт слоёв
- пересборку фильтров
- обновление легенды
Удаление dataset
Удаление инициирует каскадное очищение:
- удаление слоёв, использующих dataset
- очистка фильтров
- обновление UI состояния
Middleware как
расширение событийной системы
Redux middleware в Kepler.gl позволяет перехватывать actions до
попадания в reducers.
Основные сценарии:
- логирование всех событий карты
- синхронизация с внешними API
- трансформация данных перед сохранением
- реализация аналитических трекеров
Middleware получает доступ к:
- action
- текущему state
- next dispatch функции
Это позволяет строить полноценную event-driven архитектуру поверх
Kepler.gl.
События mapStyle и
визуального оформления
Изменение стиля карты (mapStyle) также является частью событийной
модели.
Сюда входят:
- переключение базовой карты
- изменение тем (dark/light)
- настройка слоёв подложки
- кастомные tile-слои
Каждое изменение вызывает обновление mapState и частичный re-render
всех визуальных слоёв.
Взаимодействие с timeline
и анимацией
Kepler.gl поддерживает временные данные и анимацию через фильтры
времени.
Событийная модель включает:
- изменение текущего временного шага
- автоплей анимации
- синхронизацию временных окон с данными
Каждый тик анимации представляет собой отдельное состояние visState,
что фактически создаёт поток событий во времени.
Синхронизация нескольких
карт
При работе с несколькими экземплярами Kepler.gl события используются
для синхронизации:
- viewport sync (mapState)
- shared dataset updates
- coordinated filtering
Типовой подход:
- один store как источник истины
- подписки на изменения mapState
- проксирование actions между экземплярами
Расширение
событийной модели через кастомные actions
Kepler.gl допускает внедрение пользовательских actions, расширяющих
стандартный набор событий.
Примеры:
- загрузка данных из нестандартных источников
- кастомная агрегация
- интеграция с внешними геосервисами
Кастомные actions проходят тот же путь:
dispatch → middleware → reducer → state update → подписчики
Производительность
событийной системы
Высокая частота событий требует оптимизации:
- батчинг dispatch операций
- мемоизация селекторов
- ограничение частоты onStateChange через throttling
- минимизация пересчётов visState
Особенно критичны:
- события drag viewport
- hover events
- фильтры с непрерывным изменением
Структурная
роль событий в архитектуре Kepler.gl
События в Kepler.gl выполняют функцию связующего слоя между:
- визуализацией (deck.gl)
- состоянием (Redux)
- пользовательским взаимодействием (React callbacks)
- внешними системами (middleware, API)
Эта модель позволяет рассматривать карту как поток состояний, где
каждое взаимодействие преобразуется в детерминированное изменение store
и последующее обновление визуального слоя.