Настройка интерфейса

kepler.gl предоставляет гибкую систему настройки интерфейса, позволяющую управлять отображением панели инструментов, поведением элементов карты, доступностью функций и общей компоновкой UI без необходимости модифицировать исходный код библиотеки. Интерфейс строится поверх архитектуры состояний (Redux-подобной модели), где ключевую роль играет объект конфигурации uiState.

UI в Kepler.gl формируется несколькими слоями состояния:

  • uiState — управление интерфейсом и видимостью компонентов
  • mapState — параметры камеры, масштаб, центр карты
  • visState — визуализация данных и слои
  • config — объединяющий объект для сохранения и восстановления состояния

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

Базовая конфигурация uiState

Типичная структура настройки интерфейса:

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

readOnly

Флаг readOnly блокирует возможность изменения карты. В этом режиме:

  • отключается добавление слоёв
  • запрещается редактирование данных
  • скрываются элементы управления, связанные с изменениями

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

activeSidePanel

Определяет активную боковую панель:

  • null — панель скрыта
  • "layer" — управление слоями
  • "filter" — фильтры
  • "interaction" — настройки взаимодействий
  • "dataset" — управление данными

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

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

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

Боковая панель (Side Panel)

Боковая панель — центральный элемент интерфейса. Управление её состоянием осуществляется через uiState:

uiState: {
  activeSidePanel: "layer"
}

Дополнительно можно ограничить доступ к панели:

uiState: {
  readOnly: true,
  activeSidePanel: null
}

При этом панель полностью скрывается, а карта переходит в режим просмотра.

Отключение панелей

Гибкая конфигурация позволяет скрывать отдельные элементы:

uiState: {
  mapControls: {
    visibleLayers: false,
    mapLegend: false,
    splitMap: false
  }
}

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

Настройка элементов управления картой

Контролы карты задаются через объект mapControls, который управляет видимостью функциональных кнопок.

Основные элементы управления

  • visibleLayers — управление слоями
  • mapLegend — легенда карты
  • toggle3d — переключение 2D/3D режима
  • splitMap — сравнение карт
  • mapDraw — инструмент рисования
  • mapLocale — локализация

Пример конфигурации:

uiState: {
  mapControls: {
    visibleLayers: true,
    mapLegend: true,
    toggle3d: false,
    splitMap: false,
    mapDraw: true,
    mapLocale: true
  }
}

Отключение toggle3d часто используется в аналитических приложениях, где 3D визуализация не требуется.

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

Kepler.gl использует модальные окна для загрузки данных, настройки и экспорта.

uiState: {
  currentModal: "addDataModal"
}

Возможные значения:

  • addDataModal — добавление данных
  • exportImage — экспорт изображения
  • exportData — экспорт датасета
  • settings — настройки

Установка null закрывает любое активное окно.

Настройка взаимодействий интерфейса

Интерактивность карты частично контролируется через mapUI:

uiState: {
  mapUI: {
    showTooltip: true,
    tooltip: {
      enabled: true
    }
  }
}

Tooltip

Tooltip можно полностью отключить:

uiState: {
  mapUI: {
    showTooltip: false
  }
}

Это полезно при статической визуализации или генерации изображений карты.

Глобальные ограничения интерфейса

Режим readOnly

Режим readOnly влияет не только на интерфейс, но и на поведение всей системы:

uiState: {
  readOnly: true
}

Последствия:

  • отключение drag-and-drop загрузки данных
  • скрытие кнопок редактирования слоёв
  • блокировка фильтров

Используется в embed-режимах и публичных дашбордах.

Скрытие всего UI

В некоторых сценариях интерфейс полностью минимизируется:

uiState: {
  readOnly: true,
  mapControls: {
    visibleLayers: false,
    mapLegend: false,
    toggle3d: false,
    splitMap: false,
    mapDraw: false,
    mapLocale: false
  },
  activeSidePanel: null
}

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

Темизация интерфейса

UI Kepler.gl поддерживает базовую настройку темы:

uiState: {
  theme: "dark"
}

Доступные варианты:

  • "dark" — тёмная тема
  • "light" — светлая тема

Тема влияет на:

  • фон интерфейса
  • цвета панелей
  • контраст текста
  • стили всплывающих элементов

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

Язык интерфейса задаётся через locale:

uiState: {
  locale: {
    locale: "ru",
    messages: {}
  }
}

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

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

Пример частичной локализации:

uiState: {
  locale: {
    locale: "ru",
    messages: {
      "tooltip.loading": "Загрузка данных...",
      "button.addData": "Добавить данные"
    }
  }
}

Интеграция UI-конфигурации в приложение

В React-интеграции Kepler.gl конфигурация передаётся через пропсы:

import KeplerGl from 'kepler.gl';

<KeplerGl
  id="map"
  width={800}
  height={600}
  mapboxApiAccessToken={token}
  uiState={uiState}
/>

При использовании Redux:

dispatch(
  addDataToMap({
    datasets,
    options: {
      centerMap: true,
      readOnly: false
    },
    config: {
      uiState
    }
  })
);

Динамическое изменение интерфейса

UI можно изменять во время выполнения:

dispatch(
  updateVisData({
    uiState: {
      activeSidePanel: "filter"
    }
  })
);

Это позволяет:

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

Скрытие брендинга и минимализация UI

Встраиваемые решения часто требуют упрощённого интерфейса:

uiState: {
  mapControls: {
    mapLegend: false,
    visibleLayers: false
  },
  activeSidePanel: null,
  readOnly: true
}

Такой подход превращает Kepler.gl в чистый визуализационный слой без аналитических инструментов.

Поведение интерфейса при масштабировании

UI адаптируется под размеры контейнера, однако часть элементов можно дополнительно ограничить:

  • отключение панели слоёв при малых экранах
  • скрытие легенды
  • фиксация центра карты
uiState: {
  mapControls: {
    mapLegend: false
  }
}

Управление взаимодействием компонентов UI

Каждый элемент интерфейса связан с состоянием приложения. Изменение одной части UI может влиять на другие:

  • открытие панели фильтров влияет на visState
  • включение слоёв обновляет mapState
  • изменение темы влияет на рендер компонентов

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

Ограничение функциональности через UI слой

UI слой используется не только для отображения, но и для ограничения возможностей:

  • отключение экспорта
  • запрет редактирования слоёв
  • скрытие инструментов анализа
uiState: {
  currentModal: null,
  mapControls: {
    mapDraw: false
  },
  readOnly: true
}

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

Оглавление