Кастомизация UI

Интерфейс Kepler.gl построен поверх связки React + Redux и разделён на три ключевых слоя: состояние визуализации (visState), состояние карты (mapState) и UI-состояние (uiState). Именно uiState определяет, какие элементы интерфейса отображаются, как они выглядят и в каком режиме работает панель управления.

Основная особенность архитектуры заключается в том, что интерфейс не отделён от состояния приложения — он является его производной. Любая кастомизация UI фактически сводится к управлению конфигурацией стора, пропсами компонента KeplerGl и расширением редьюсеров.

Управление видимостью интерфейсных элементов

Kepler.gl предоставляет механизм тонкой настройки отображения панелей и контролов через uiState. Этот объект управляет состоянием видимости всех основных UI-компонентов: боковой панели, фильтров, легенды, тулбаров и модальных окон.

Пример базовой структуры:

const uiState = {
  currentModal: null,
  activeSidePanel: null,
  readOnly: false,
  mapControls: {
    visibleLayers: true,
    mapLegend: true,
    toggle3d: true,
    splitMap: false
  }
};

Ключевой принцип: отсутствие элемента в UIState не означает его отключение — важно явно управлять флагами видимости.

Конфигурация через visState и влияние на UI

Хотя visState формально отвечает за данные и слои, он напрямую влияет на интерфейс. Например, наличие фильтров, типы визуализаций и доступные элементы управления зависят от структуры данных внутри visState.

const visState = {
  layers: [],
  filters: [],
  interactionConfig: {
    tooltip: {
      enabled: true
    },
    brush: {
      size: 0.5,
      enabled: false
    }
  }
};

UI Kepler.gl динамически перестраивается в зависимости от количества слоёв, фильтров и включённых интеракций. Это означает, что кастомизация интерфейса часто происходит косвенно — через данные, а не напрямую через UI-компоненты.

Интеграция KeplerGl в React и точка кастомизации UI

Основной компонент библиотеки — KeplerGl. Именно через него передаются все конфигурации, включая стиль интерфейса и начальное состояние.

import KeplerGl from 'kepler.gl';

<KeplerGl
  id="map"
  width={width}
  height={height}
  mapboxApiAccessToken={MAPBOX_TOKEN}
  uiState={uiState}
  mapStyle={mapStyle}
  initialUiState={uiState}
/>

Ключевые точки кастомизации:

  • uiState — управление интерфейсом
  • mapStyle — визуальный стиль карты
  • width / height — компоновка контейнера
  • appState через Redux — глобальное управление

Скрытие и модификация панелей интерфейса

Kepler.gl допускает отключение стандартных панелей через конфигурацию UI. Наиболее часто изменяются:

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

Пример скрытия элементов:

const uiState = {
  readOnly: false,
  mapControls: {
    visibleLayers: false,
    mapLegend: false,
    toggle3d: false
  },
  sidePanel: {
    open: false
  }
};

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

Кастомные темы и стилизация интерфейса

UI Kepler.gl визуально опирается на тему Mapbox и собственные стили компонентов React. Изменение внешнего вида достигается через переопределение CSS и внедрение кастомной темы приложения.

Основные точки стилизации:

  • классы .kepler-gl контейнера
  • CSS-модули внутри панели управления
  • глобальные стили приложения

Пример переопределения:

.kepler-gl {
  font-family: Inter, sans-serif;
  background-color: #0b0f1a;
}

.kepler-gl .side-panel {
  border-right: 1px solid #1f2937;
}

.kepler-gl .map-control-button {
  border-radius: 6px;
}

Важно учитывать, что внутренняя структура классов может меняться между версиями, поэтому стабильная кастомизация чаще строится через обёртку компонентов, а не прямой CSS-инжекшн.

Расширение интерфейса через Redux

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

Базовый способ интеграции:

import { createStore, combineReducers, applyMiddleware } from 'redux';
import keplerGlReducer from 'kepler.gl/reducers';

const reducers = combineReducers({
  keplerGl: keplerGlReducer
});

const store = createStore(reducers, {}, applyMiddleware());

Расширение UI достигается через модификацию initialState редьюсера:

const customizedReducer = keplerGlReducer.initialState({
  uiState: {
    readOnly: false,
    currentModal: null
  }
});

Таким образом можно задавать поведение интерфейса ещё до инициализации компонента.

Динамическое управление UI через actions

Kepler.gl предоставляет набор Redux actions, позволяющих изменять интерфейс в рантайме.

Примеры:

  • открытие/закрытие панели
  • переключение режимов карты
  • управление модальными окнами
import { toggleSidePanel, wrapTo } from 'kepler.gl/actions';

dispatch(wrapTo('map', toggleSidePanel('layer')));

Ключевая особенность — необходимость оборачивания действий через wrapTo, поскольку Kepler.gl поддерживает несколько инстансов карты.

Кастомные компоненты интерфейса

Одним из наиболее мощных механизмов кастомизации является замена стандартных React-компонентов.

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

Пример расширения:

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

const customComponents = injectComponents([
  [LayerPanelHeaderFactory, CustomLayerHeader]
]);

Таким образом можно заменить:

  • заголовки панелей
  • элементы управления слоями
  • кнопки экспорта
  • фильтры

Управление стилем карты как часть UI

UI Kepler.gl тесно связан с системой стилей Mapbox. Выбор темы карты влияет на восприятие интерфейса в целом, поскольку панели и визуализация накладываются поверх карты.

Пример настройки:

const mapStyle = {
  styleType: 'dark',
  topLayerGroups: {},
  visibleLayerGroups: {
    label: true,
    road: true,
    border: false,
    building: true
  }
};

Изменение styleType автоматически перестраивает цветовую схему интерфейса и контраст элементов управления.

Локализация интерфейса

UI Kepler.gl поддерживает многоязычность через систему локалей. Переключение языка влияет на все текстовые элементы панели.

const locale = {
  locale: 'ru',
  messages: {
    layer: 'Слои',
    filter: 'Фильтры'
  }
};

Локализация часто используется совместно с кастомными UI-компонентами, чтобы обеспечить единый стиль интерфейса.

Ограничение функционала через read-only режим

Режим readOnly превращает Kepler.gl в визуализатор без возможности редактирования данных. Это влияет на весь интерфейс:

  • скрываются кнопки редактирования слоёв
  • отключаются фильтры
  • блокируется добавление данных
const uiState = {
  readOnly: true
};

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

Управление модальными окнами и контекстными элементами

UI Kepler.gl включает систему модальных окон для загрузки данных, экспорта и настроек. Управление ими осуществляется через currentModal:

const uiState = {
  currentModal: 'addData'
};

Доступные модальные состояния определяют, какие окна могут быть активированы без изменения кода компонентов.

Кастомизация тулбаров и контролов карты

Элементы управления картой (zoom, rotation, pitch, fullscreen) также входят в UI слой и могут быть скрыты или заменены.

const mapControls = {
  fullscreenButton: false,
  geocoder: true,
  splitMap: false
};

При необходимости можно заменить стандартные контролы на кастомные компоненты Mapbox GL, интегрированные в React-дерево Kepler.gl.

Оглавление