Экспорт конфигурации в JSON

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

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

Структура состояния Kepler.gl перед экспортом

Перед экспортом необходимо понимать, какие части состояния входят в конфигурацию:

Основные разделы состояния

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

Каждый из этих блоков является частью единого дерева состояния, которое в Redux-хранилище Kepler.gl объединено в объект keplerGl.

Базовый принцип экспорта конфигурации

Экспорт выполняется через извлечение состояния из store и преобразование его в JSON-совместимый объект.

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

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

Полный экспорт состояния карты

Сбор всех частей состояния

const state = store.getState();

const fullConfig = {
  version: "v1",
  config: {
    visState: state.keplerGl.map.visState,
    mapState: state.keplerGl.map.mapState,
    uiState: state.keplerGl.map.uiState,
    mapStyle: state.keplerGl.map.mapStyle
  }
};

Сериализация в JSON

const json = JSON.stringify(fullConfig, null, 2);

Форматирование с отступами позволяет использовать результат для отладки, хранения и последующего восстановления.

Использование встроенных утилит Kepler.gl

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

getConfigToSave

import KeplerGlSchema from 'kepler.gl/schemas';

const config = KeplerGlSchema.save(state.keplerGl.map);

Функция выполняет:

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

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

Каждый экспортированный JSON содержит поле версии схемы:

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

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

Очистка состояния перед экспортом

Внутреннее состояние Kepler.gl содержит временные данные, которые не всегда должны попадать в JSON:

  • состояния drag-and-drop операций
  • временные фильтры UI
  • промежуточные вычисления слоёв
  • кешированные значения взаимодействий

При использовании схемы KeplerGlSchema.save происходит автоматическая фильтрация этих данных. При ручном экспорте требуется явная очистка.

Экспорт только конфигурации карты

В некоторых сценариях требуется сохранить только визуальные параметры без данных слоёв:

const mapConfig = {
  mapState: state.keplerGl.map.mapState,
  mapStyle: state.keplerGl.map.mapStyle
};

Такой экспорт используется для:

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

Экспорт через пользовательские события

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

function exportOnChange() {
  const state = store.getState().keplerGl.map;
  return KeplerGlSchema.save(state);
}

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

Экспорт с фильтрацией слоёв

Для более точного контроля можно исключать отдельные слои:

const filteredLayers = state.keplerGl.map.visState.layers.filter(
  layer => layer.config.dataId !== 'temporary_data'
);

const config = {
  ...state.keplerGl.map,
  visState: {
    ...state.keplerGl.map.visState,
    layers: filteredLayers
  }
};

Это позволяет исключать:

  • тестовые наборы данных
  • временные визуализации
  • вспомогательные слои анализа

Экспорт через пользовательский JSON pipeline

В крупных приложениях экспорт часто интегрируется в пайплайн обработки данных:

function buildExportPayload(store) {
  const state = store.getState().keplerGl.map;

  return {
    meta: {
      createdAt: Date.now(),
      source: "kepler-gl-app"
    },
    keplerConfig: KeplerGlSchema.save(state)
  };
}

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

Сохранение JSON в файл

После формирования JSON объект может быть сохранён локально:

function downloadJSON(data) {
  const blob = new Blob([JSON.stringify(data, null, 2)], {
    type: 'application/json'
  });

  const url = URL.createObjectURL(blob);

  const a = document.createElement('a');
  a.href = url;
  a.download = 'kepler-config.json';
  a.click();

  URL.revokeObjectURL(url);
}

Типичные ошибки при экспорте

Потеря состояния visState

Часто экспортируется только mapState, что приводит к потере слоёв и фильтров.

Несоответствие версий схемы

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

Сериализация функций

Некоторые части состояния могут содержать функции, которые не сериализуются через JSON.stringify, что вызывает ошибки или потерю данных.

Оптимизация размера JSON

При больших наборах данных экспорт может становиться чрезмерно объёмным. Оптимизация достигается за счёт:

  • исключения raw data из слоёв
  • хранения только ссылок на источники данных
  • удаления кешированных вычислений
  • минимизации фильтров

Экспорт в серверные системы хранения

В архитектурах с централизованным хранением конфигурации JSON отправляется на сервер:

async function saveConfig(config) {
  await fetch('/api/kepler-config', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(config)
  });
}

Такая схема используется для:

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

Интеграция с восстановлением состояния

Экспорт JSON напрямую связан с процессом восстановления карты:

  • visState восстанавливает слои и фильтры
  • mapState восстанавливает позицию камеры
  • mapStyle восстанавливает визуальный стиль
  • uiState восстанавливает интерфейс

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

Оглавление