KeplerGl компонент

Kepler.gl представляет собой высокопроизводительную библиотеку для геовизуализации, построенную на базе Mapbox GL и deck.gl, и распространяемую как React-компонент с внутренним управлением состоянием через Redux. Встраивание компонента KeplerGl в приложение означает интеграцию полноценного визуального движка, способного отображать миллионы геоточек и выполнять агрегации данных в реальном времени (docs.kepler.gl).

KeplerGl экспортируется как стандартный React-компонент, который подключается в JSX-структуру приложения. Его основная задача — рендер интерактивной карты с наложением слоёв данных, фильтрами и визуальными конфигурациями. Компонент требует обязательного подключения Mapbox токена, поскольку базовая подложка карты строится на Mapbox GL.

Минимальная структура подключения выглядит следующим образом:

import KeplerGl from '@kepler.gl/components';

const Map = ({ width, height, token }) => (
  <KeplerGl
    id="map"
    width={width}
    height={height}
    mapboxApiAccessToken={token}
  />
);

Идентификатор id играет ключевую роль: он связывает конкретный экземпляр компонента с соответствующей частью состояния Redux. При наличии нескольких карт в одном приложении каждый экземпляр обязан иметь уникальный id, иначе произойдёт конфликт состояния.

Архитектура интеграции через Redux

KeplerGl не является изолированным UI-компонентом. Он полностью зависит от Redux-хранилища, где хранится:

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

Для корректной работы требуется подключение редьюсера kepler.gl:

import { combineReducers, createStore, applyMiddleware } from 'redux';
import keplerGlReducer from '@kepler.gl/reducers';
import { taskMiddleware } from 'react-palm/tasks';

const rootReducer = combineReducers({
  keplerGl: keplerGlReducer,
});

const store = createStore(rootReducer, {}, applyMiddleware(taskMiddleware));

Middleware react-palm используется для обработки асинхронных задач и побочных эффектов, связанных с загрузкой и обработкой данных внутри KeplerGl.

Связь компонента с состоянием

Каждый экземпляр KeplerGl обращается к своему сегменту Redux-дерева:

state.keplerGl[props.id]

Это означает, что изменение id фактически переключает источник данных, визуализации и настроек.

Дополнительно можно указать функцию getState, если редьюсер интегрирован не в корень состояния:

<KeplerGl
  id="map"
  getState={state => state.visualization.keplerGl}
/>

Это критически важно при интеграции в сложные приложения с несколькими слоями состояния.

Загрузка данных в KeplerGl

Компонент сам по себе не отображает данные без их явной передачи через action addDataToMap. Данные должны быть структурированы как dataset с метаданными:

import { addDataToMap } from '@kepler.gl/actions';

dispatch(
  addDataToMap({
    datasets: {
      info: {
        label: 'Dataset',
        id: 'data_1'
      },
      data: rawData
    },
    option: {
      centerMap: true
    }
  })
);

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

Внутренние состояния KeplerGl

Состояние KeplerGl можно условно разделить на три основные части:

visState

Отвечает за:

  • датасеты;
  • фильтры;
  • слои визуализации;
  • взаимодействия пользователя с данными.

mapState

Содержит параметры карты:

  • координаты центра;
  • zoom;
  • pitch и bearing;
  • ограничения отображения.

uiState

Управляет интерфейсом:

  • открытие панелей;
  • состояние модальных окон;
  • режимы отображения.

Эта структура делает KeplerGl не просто картографическим компонентом, а полноценной визуальной системой поверх Redux.

Конфигурация внешнего вида

KeplerGl поддерживает настройку темы интерфейса через проп theme или через styled-components ThemeProvider. Это позволяет переопределять стили панели, текста и элементов управления.

const theme = {
  sidePanelBg: '#ffffff',
  titleTextColor: '#000000',
  sidePanelHeaderBg: '#f7f7f7'
};

<KeplerGl
  id="map"
  width={800}
  height={600}
  theme={theme}
/>

При использовании ThemeProvider стили распространяются глобально на все компоненты KeplerGl внутри дерева React.

Депенденси-инъекция и кастомизация компонентов

Одной из ключевых особенностей KeplerGl является система внедрения компонентов. Она позволяет заменять внутренние UI-элементы без изменения исходного кода библиотеки.

import { injectComponents, PanelHeaderFactory } from '@kepler.gl/components';

const CustomHeader = () => <div>Custom header</div>;

const KeplerGlCustom = injectComponents([
  [PanelHeaderFactory, () => CustomHeader]
]);

После этого стандартный заголовок панели будет заменён на кастомный компонент.

Работа с несколькими экземплярами

При использовании нескольких карт на одной странице важно соблюдать изоляцию состояния. Каждый компонент должен иметь уникальный id, иначе все действия (загрузка данных, фильтры, стили) будут применяться ко всем экземплярам одновременно.

<KeplerGl id="mapA" />
<KeplerGl id="mapB" />

Каждый из них будет иметь собственный независимый state slice в Redux.

Поток данных внутри компонента

Типичный жизненный цикл данных выглядит следующим образом:

  1. Создание датасета вне компонента.
  2. Диспатч addDataToMap.
  3. Обработка данных в visState.
  4. Генерация слоёв deck.gl.
  5. Рендеринг через WebGL.
  6. Обновление UI при взаимодействии пользователя.

Эта цепочка обеспечивает реактивное обновление визуализации без ручного управления рендерингом.

Особенности рендеринга

KeplerGl использует deck.gl для WebGL-рендеринга, что позволяет:

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

React-компонент здесь выполняет роль управляющего слоя, а не прямого рендерера графики.

Расширяемость через Redux actions

Любое взаимодействие с картой осуществляется через actions:

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

Это делает KeplerGl предсказуемым с точки зрения архитектуры: любое изменение состояния можно отследить через Redux flow.

Использование getState и нестандартных архитектур

В крупных приложениях KeplerGl часто интегрируется не в корневой Redux store. В таких случаях используется функция getState, которая указывает путь к состоянию компонента внутри глобального дерева.

Это позволяет встроить KeplerGl в:

  • модульные системы;
  • микрофронтенды;
  • существующие Redux-архитектуры без рефакторинга.

Структура KeplerGl как React-компонента опирается на сочетание Redux-архитектуры, WebGL-рендеринга и декларативного UI, что делает его не просто картографическим виджетом, а полноценным визуальным движком внутри React-приложений.

Оглавление