Экспорт карты в HTML

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

Kepler.gl хранит всю конфигурацию карты в структуре состояния приложения. Она состоит из нескольких крупных блоков:

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

Именно этот объект становится ядром экспортируемого HTML:

const MAP_CONFIG = {
  version: 'v1',
  config: {
    visState: { /* слои и фильтры */ },
    mapState: { /* камера */ },
    mapStyle: { /* стиль карты */ }
  }
};

Сохранение этого объекта позволяет полностью восстановить визуализацию в любом окружении, где подключён Kepler.gl.

Сериализация и подготовка конфигурации

Перед формированием HTML важно привести состояние к компактному и переносимому виду. Обычно используется JSON-сериализация:

const serializedConfig = JSON.stringify(MAP_CONFIG);

Полученная строка может быть:

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

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

Базовая структура HTML-документа

Kepler.gl не является standalone-библиотекой без зависимостей, поэтому HTML-экспорт подразумевает подключение React-окружения и сборщика или использование готового бандла.

Минимальная структура страницы включает контейнер:

<div id="app"></div>

и точку входа JavaScript, которая инициализирует приложение.

Инициализация Kepler.gl в веб-странице

В стандартной React-интеграции используется компонент KeplerGl:

import React from 'react';
import ReactDOM from 'react-dom';
import KeplerGl from 'kepler.gl';
import { createStore, combineReducers, applyMiddleware } from 'redux';
import keplerGlReducer from 'kepler.gl/reducers';

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

const store = createStore(reducers);

function App() {
  return (
    <KeplerGl
      id="map"
      width={window.innerWidth}
      height={window.innerHeight}
      mapboxApiAccessToken={MAPBOX_TOKEN}
    />
  );
}

ReactDOM.render(<App />, document.getElementById('app'));

Такой подход формирует основу HTML-страницы, в которую затем подгружается сохранённая конфигурация.

Встраивание сохранённого состояния

После загрузки Kepler.gl необходимо восстановить карту из ранее экспортированного состояния:

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

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

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

Генерация автономного HTML-файла

HTML-экспорт обычно строится как шаблон, в который внедряются:

  • подключение React и ReactDOM
  • подключение Kepler.gl и зависимостей
  • встроенный JSON конфигурации
  • точка инициализации приложения

Пример упрощённого шаблона:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Kepler.gl Export</title>
  <style>
    body { margin: 0; overflow: hidden; }
    #app { width: 100vw; height: 100vh; }
  </style>
</head>
<body>
  <div id="app"></div>

  <script>
    const CONFIG = /* вставка MAP_CONFIG */;
  </script>

  <script src="bundle.js"></script>
</body>
</html>

В реальных сценариях bundle.js собирается через Webpack или Vite и содержит всю логику приложения.

Подход через сборку (Webpack / Vite)

Для полноценного HTML-экспорта часто используется сборка приложения:

// entry.js
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App />, document.getElementById('app'));

Далее конфигурация Kepler.gl встраивается внутрь App:

function App() {
  return (
    <KeplerGl
      id="map"
      width={window.innerWidth}
      height={window.innerHeight}
      mapboxApiAccessToken={TOKEN}
    />
  );
}

При сборке получается единый HTML с подключённым JavaScript-бандлом.

Вариант статического HTML с CDN

В некоторых конфигурациях возможно использование UMD-сборок библиотек. Тогда HTML может включать внешние зависимости:

<script src="https://unpkg.com/react/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>

После чего Kepler.gl подключается через собранный пакет или кастомный бандл.

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

При встраивании данных необходимо учитывать размер:

  • геоданные часто превышают допустимый размер HTML
  • лучше использовать ссылки на внешние JSON или CSV
  • возможно ленивое подгружение через fetch
fetch('/data/points.json')
  .then(res => res.json())
  .then(data => {
    store.dispatch(
      addDataToMap({
        datasets: [{ data, info: { label: 'Points' } }],
        config: MAP_CONFIG.config
      })
    );
  });

Особенности воспроизводимости карты

HTML-экспорт должен учитывать зависимости визуализации:

  • токен Mapbox
  • версия Kepler.gl
  • структура данных
  • совместимость слоёв (point, arc, heatmap, grid)

Несовпадение версий может приводить к изменению отображения даже при одинаковом конфиге.

Минимизированная автономная схема

Полностью автономный HTML-экспорт обычно включает:

  • встроенный JSON конфигурации
  • бандл приложения Kepler.gl
  • локальные или CDN-зависимости
  • инициализацию Redux store
  • восстановление состояния через dispatch

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

Оглавление