Пропсы и их назначение

Kepler.gl построен как React-компонент с сильной зависимостью от входных параметров, через которые задаётся как поведение карты, так и структура данных, визуализация и взаимодействие с состоянием приложения. Пропсы здесь выполняют роль единого интерфейса управления всеми слоями системы: от подключения Mapbox до синхронизации состояния с внешним хранилищем.

Базовые пропсы компонента KeplerGl

Компонент KeplerGl принимает минимальный набор обязательных параметров, без которых отрисовка карты невозможна.

mapboxApiAccessToken Ключевой пропс, обеспечивающий доступ к Mapbox. Без него невозможно загрузить базовые тайлы и стили карты.

id Уникальный идентификатор инстанса Kepler.gl. Используется для изоляции нескольких карт в одном приложении и для привязки состояния в Redux-структуре Kepler.gl.

width / height Размеры контейнера карты. Поддерживается как фиксированная числовая величина, так и динамическое управление через внешние измерения контейнера. Эти пропсы напрямую влияют на рендер WebGL-сцены Deck.gl.

Пропсы данных (data layer)

Kepler.gl работает с данными через структурированные датасеты, которые описывают таблицы, поля и географические координаты.

data

Пропс data — один из центральных в архитектуре Kepler.gl. Он принимает массив или объект датасетов, каждый из которых содержит:

  • fields — описание колонок (тип, имя, формат)
  • rows — массив значений
  • name — имя набора данных

Внутри Kepler.gl данные преобразуются в внутренний формат visState, где формируются слои, фильтры и агрегаты.

datasets

Альтернативный способ передачи данных. Используется, когда требуется загрузка нескольких источников одновременно с явной структурой:

  • info — метаданные (название, описание)
  • data — сами строки и поля
  • version — версия схемы

Использование datasets предпочтительно при интеграции с серверной загрузкой или динамическим импортом CSV/JSON.

Пропсы состояния визуализации

Kepler.gl разделяет состояние на несколько логических частей: mapState, visState, mapStyle, uiState. Эти пропсы позволяют сделать компонент контролируемым.

mapState

Отвечает за положение камеры и параметры отображения карты:

  • latitude / longitude — центр карты
  • zoom — уровень приближения
  • bearing — поворот
  • pitch — наклон камеры

Передача mapState позволяет полностью управлять положением карты извне, превращая Kepler.gl в controlled-компонент.

visState

Один из самых сложных объектов состояния. Содержит:

  • слои (layers)
  • фильтры (filters)
  • взаимодействия (interactionConfig)
  • всплывающие окна (tooltips)
  • выбранные элементы

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

mapStyle

Определяет визуальный стиль карты:

  • стиль Mapbox (streets, dark, light и др.)
  • кастомные стили JSON
  • конфигурация слоёв карты (базовые, подписи, дороги)

Kepler.gl использует этот пропс для интеграции с Mapbox Style Specification.

uiState

Отвечает за интерфейсные элементы:

  • видимость панелей
  • состояние фильтров UI
  • режимы взаимодействия
  • настройки всплывающих окон

Этот пропс часто используется для кастомизации интерфейса без изменения логики данных.

Пропсы управления состоянием (callbacks)

Kepler.gl предоставляет набор callback-функций для синхронизации состояния с внешним приложением.

onLoad

Вызывается при полной инициализации Kepler.gl. Используется для:

  • первичной загрузки данных
  • синхронизации состояния
  • подключения внешних источников

onStateChange

Основной callback для отслеживания изменений состояния. Срабатывает при любом изменении:

  • фильтров
  • слоёв
  • стиля карты
  • взаимодействий пользователя

Позволяет реализовать внешний store или сохранять состояние в backend.

onViewStateChange

Специализированный callback для изменения положения камеры карты. Используется для:

  • синхронизации нескольких карт
  • создания связанных представлений (linked views)
  • анимации переходов между точками

Контроль и неконтролируемый режим

Kepler.gl может работать в двух режимах:

Неконтролируемый режим

Состояние полностью управляется внутри библиотеки. Пропсы используются только для инициализации.

Особенности:

  • проще интеграция
  • минимальная связка с Redux
  • ограниченный внешний контроль

Контролируемый режим

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

  • mapState
  • visState
  • mapStyle
  • uiState

Особенности:

  • полный внешний контроль
  • возможность синхронизации с Redux / MobX
  • сложная архитектура приложения

Пропсы интеграции с Redux

Kepler.gl изначально проектировался с глубокой интеграцией Redux, поэтому многие пропсы тесно связаны с состоянием store.

getState

Функция, позволяющая Kepler.gl получать состояние из внешнего хранилища. Используется при кастомной интеграции Redux, когда структура store отличается от стандартной.

dispatch / actions (через контекст)

Хотя напрямую не всегда передаются как пропсы, действия Kepler.gl зависят от внешнего dispatch, который управляет:

  • добавлением данных
  • обновлением слоёв
  • изменением фильтров

Производственные пропсы и оптимизация

throttleUpdate

Используется для ограничения частоты обновления состояния. Особенно важно при:

  • большом количестве данных
  • частых изменениях камеры
  • потоковой визуализации

debounceInterval

Задаёт задержку для группировки обновлений состояния, снижая нагрузку на React и WebGL.

Пропсы конфигурации приложения

appName

Имя приложения, отображаемое в интерфейсе Kepler.gl. Используется также в логировании и сохранении пресетов.

version (через конфигурацию)

Позволяет учитывать совместимость состояния между разными версиями Kepler.gl, особенно при загрузке сохранённых конфигураций.

Особенности передачи сложных структур через пропсы

Kepler.gl активно использует сериализуемые структуры. Это накладывает ограничения:

  • функции не должны передаваться в state-пропсы
  • данные должны быть JSON-совместимыми
  • объекты visState должны сохранять строгую структуру

При нарушении этих условий возможны ошибки гидратации состояния или некорректный рендер слоёв.

Взаимосвязь пропсов и внутреннего состояния

Каждый ключевой пропс имеет прямое отображение во внутренней Redux-модели:

  • mapState → mapState reducer
  • visState → visState reducer
  • mapStyle → mapStyle reducer
  • uiState → uiState reducer

Изменение пропсов инициирует соответствующие actions, что делает Kepler.gl гибридом controlled/uncontrolled архитектуры.

Паттерны использования пропсов в реальных приложениях

Типичная архитектура интеграции включает:

  • хранение visState в Redux store
  • обновление mapState через onViewStateChange
  • загрузку datasets через API
  • контроль uiState для кастомных интерфейсов
  • использование id для мульти-карт сценариев

Такой подход позволяет строить аналитические панели, гео-дашборды и интерактивные системы визуализации с синхронизированными представлениями данных.

Оглавление