Сохранение и загрузка конфигурации

В Kepler.gl состояние визуализации строится вокруг единого объекта конфигурации, который описывает весь проект: слои, фильтры, состояние камеры, стили карты и параметры взаимодействия. Этот объект обычно называют config, и он является основой для сохранения и последующего восстановления визуализации.

Конфигурация делится на три ключевых блока:

  • visState — данные, слои, фильтры, интерактивные настройки
  • mapState — положение карты, zoom, pitch, bearing
  • mapStyle — стилизация базовой карты

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

Основной объект конфигурации

Полная конфигурация Kepler.gl имеет следующий логический вид:

{
  version: "v1",
  config: {
    visState: { ... },
    mapState: { ... },
    mapStyle: { ... }
  }
}

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

visState: данные, слои и фильтры

Блок visState содержит всю аналитическую часть визуализации:

  • загруженные датасеты
  • набор слоёв (layers)
  • активные фильтры (filters)
  • взаимодействия (interactionConfig)

Пример структуры:

visState: {
  datasets: {
    dataId: {
      data: [],
      info: {
        id: "dataId",
        label: "Dataset"
      }
    }
  },
  layers: [
    {
      id: "layer1",
      type: "point",
      config: {
        dataId: "dataId",
        columns: {
          lat: "lat",
          lng: "lng"
        },
        isVisible: true
      }
    }
  ],
  filters: [
    {
      id: "filter1",
      dataId: "dataId",
      name: "time",
      type: "timeRange",
      value: [1620000000, 1625000000]
    }
  ]
}

Ключевые особенности visState

  • layers определяют визуальное представление данных
  • filters позволяют динамически ограничивать данные
  • datasets содержат исходные таблицы
  • связь между слоями и данными осуществляется через dataId

mapState: положение и камера

Блок mapState отвечает за географическое положение и параметры камеры:

mapState: {
  latitude: 55.751244,
  longitude: 37.618423,
  zoom: 10,
  pitch: 45,
  bearing: 0,
  dragRotate: true
}

Значение параметров

  • latitude / longitude — центр карты
  • zoom — масштаб
  • pitch — наклон камеры
  • bearing — поворот карты
  • dragRotate — разрешение вращения

Этот блок критичен для сохранения «ракурса» визуализации, особенно в аналитических проектах, где важно восстановить точное положение обзора.

mapStyle: оформление карты

Блок mapStyle управляет визуальным стилем базовой карты:

mapStyle: {
  styleType: "dark",
  visibleLayerGroups: {
    label: true,
    road: true,
    border: false,
    building: true,
    water: true
  }
}

Основные элементы

  • styleType — базовая тема (dark, light, satellite и др.)
  • visibleLayerGroups — управление слоями подложки
  • mapStyles — кастомные стили Mapbox (если подключены)

Сохранение конфигурации

Сохранение состояния обычно выполняется через доступ к store приложения Kepler.gl.

Получение конфигурации из состояния Redux

Kepler.gl использует Redux как основное хранилище состояния:

const savedConfig = store.getState().keplerGl.map.config;

Однако более корректный способ — использовать селекторы:

const config = state.keplerGl.map.visState;
const mapState = state.keplerGl.map.mapState;
const mapStyle = state.keplerGl.map.mapStyle;

После этого данные собираются в единый объект:

const fullConfig = {
  version: "v1",
  config: {
    visState: config,
    mapState,
    mapStyle
  }
};

Экспорт в JSON

Для хранения или передачи конфигурации используется сериализация:

const json = JSON.stringify(fullConfig);
localStorage.setItem("keplerConfig", json);

Альтернативно конфигурация может быть отправлена на сервер:

fetch("/api/save-map", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(fullConfig)
});

Загрузка конфигурации

Загрузка состояния выполняется через восстановление Redux-состояния или через dispatch действий Kepler.gl.

Восстановление из localStorage

const saved = localStorage.getItem("keplerConfig");
const config = JSON.parse(saved);

Далее конфигурация применяется через action:

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

store.dispatch(addDataToMap({
  datasets: [],
  config: config.config,
  options: {
    centerMap: true,
    readOnly: false
  }
}));

Восстановление через addDataToMap

Основной механизм загрузки в Kepler.gl — это действие addDataToMap.

dispatch(addDataToMap({
  datasets: [
    {
      info: {
        id: "dataId",
        label: "Dataset"
      },
      data: rawData
    }
  ],
  config: savedConfig.config,
  options: {
    keepExistingConfig: false,
    centerMap: true
  }
}));

Поведение при загрузке

  • datasets заменяют или дополняют существующие данные
  • config восстанавливает слои и фильтры
  • options.centerMap возвращает камеру в сохранённое положение

Частичная загрузка конфигурации

В ряде случаев требуется восстановить только часть состояния.

Только положение карты

dispatch(updateMapState({
  latitude: config.mapState.latitude,
  longitude: config.mapState.longitude,
  zoom: config.mapState.zoom
}));

Только слои

dispatch(updateLayerConfig({
  config: config.visState.layers
}));

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

Версионирование конфигурации

Поле version играет ключевую роль при долгосрочном хранении проектов.

{
  version: "v1",
  config: { ... }
}

При изменении структуры Kepler.gl версия позволяет:

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

Миграция старых конфигураций

При обновлении версии библиотеки может потребоваться трансформация конфигурации:

function migrateConfig(oldConfig) {
  if (!oldConfig.version) {
    return {
      version: "v1",
      config: oldConfig
    };
  }
  return oldConfig;
}

Сохранение конфигурации слоями (advanced)

В сложных приложениях конфигурация может сохраняться поэтапно:

  • сначала visState
  • затем mapState
  • затем mapStyle

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

const saveVisState = JSON.stringify(state.visState);
const saveMapState = JSON.stringify(state.mapState);
const saveMapStyle = JSON.stringify(state.mapStyle);

Работа с несколькими картами

Kepler.gl поддерживает несколько экземпляров карт в одном приложении. В этом случае конфигурация хранится отдельно для каждого instanceId:

state.keplerGl = {
  map1: { ... },
  map2: { ... }
};

Сохранение требует указания конкретного идентификатора:

const config = state.keplerGl.map1.config;

Восстановление состояния без данных

Иногда необходимо восстановить только визуальную часть без датасетов:

dispatch(addDataToMap({
  datasets: [],
  config: savedConfig.config,
  options: {
    readOnly: true
  }
}));

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

Обработка ошибок при загрузке

При восстановлении конфигурации часто возникают несоответствия:

  • отсутствующие поля
  • изменённые структуры слоёв
  • несовместимые фильтры

Базовая защита:

try {
  const config = JSON.parse(saved);
  dispatch(addDataToMap(config));
} catch (e) {
  console.error("Invalid Kepler.gl config");
}

Дополнительно полезно валидировать структуру visState перед применением.

Производительность при сохранении больших конфигураций

При работе с крупными датасетами:

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

Рекомендуется:

  • использовать IndexedDB вместо localStorage
  • сжимать JSON (gzip / lz-string)
  • разделять конфигурацию и данные
import LZString from "lz-string";

const compressed = LZString.compressToUTF16(JSON.stringify(config));
localStorage.setItem("keplerConfig", compressed);

Совместимость конфигураций между окружениями

Конфигурация Kepler.gl может использоваться:

  • в браузере
  • в серверной генерации (SSR)
  • в аналитических пайплайнах

Главное требование — сохранение структуры visState/mapState/mapStyle, независимо от среды исполнения.

Оглавление