Генерация встраиваемого кода

Архитектура встраивания и роль конфигурации

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

  • описание слоёв (layers)
  • состояние камеры (mapState)
  • пользовательские стили (mapStyle)
  • набор источников данных (datasets)
  • параметры взаимодействия (interactionConfig)

Этот набор формирует единый JSON-конфиг, который используется как основа для последующего встраивания в JavaScript-приложение или статический HTML-документ.

Ключевым принципом является отделение данных от визуального представления: визуализация не хранит «жёстко закодированную» карту, а восстанавливает её из состояния.

Сериализация состояния карты

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

{
  "version": "v1",
  "config": {
    "visState": {
      "layers": [],
      "filters": []
    },
    "mapState": {
      "latitude": 59.93,
      "longitude": 30.31,
      "zoom": 10,
      "bearing": 0,
      "pitch": 0
    },
    "mapStyle": {
      "styleType": "dark"
    }
  }
}

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

Встраивание через React-компонент KeplerGl

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

Базовая структура выглядит следующим образом:

import KeplerGl from 'kepler.gl';
import { useDispatch } from 'react-redux';
import { addDataToMap } from 'kepler.gl/actions';

const MapContainer = () => {
  const dispatch = useDispatch();

  const datasets = {
    data: sampleData,
    info: {
      label: 'Dataset'
    }
  };

  const config = {
    visState: {
      layers: [],
      filters: []
    },
    mapState: {
      latitude: 55.75,
      longitude: 37.61,
      zoom: 10
    },
    mapStyle: {
      styleType: 'dark'
    }
  };

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

  return (
    <KeplerGl
      id="map"
      width={800}
      height={600}
    />
  );
};

В этом сценарии встраиваемый код представляет собой комбинацию Redux-действий и JSON-конфигурации, которая восстанавливает карту в нужном состоянии.

Генерация встроенного HTML-представления

Помимо React-интеграции, Kepler.gl поддерживает генерацию автономного HTML-файла, который можно использовать как полностью независимый встраиваемый артефакт.

Такой подход основан на упаковке:

  • JavaScript-бандла Kepler.gl
  • сериализованных данных
  • конфигурации состояния

Пример логики генерации HTML:

import { exportToHtml } from 'kepler.gl';

const html = exportToHtml({
  datasets: [dataset],
  config: mapConfig,
  width: 1200,
  height: 800
});

Результатом является HTML-документ, содержащий:

  • встроенный React-бандл
  • инициализацию состояния карты
  • загрузку данных в runtime
  • контейнер для рендера WebGL

Такой файл может быть размещён на любом статическом хостинге без серверной логики.

Встраивание через URL-конфигурацию

Kepler.gl поддерживает механизм шаринга состояния через URL, где весь конфиг кодируется и передаётся в виде параметра.

Структура такого подхода:

  • сериализация config в JSON
  • сжатие (compression)
  • кодирование в base64 или аналогичный формат
  • вставка в query string

Пример логики:

import { encode } from 'kepler.gl/dist/utils';

const encodedConfig = encode(mapConfig);

const shareUrl = `https://kepler.gl/demo?map=${encodedConfig}`;

При загрузке страницы приложение:

  1. декодирует строку
  2. восстанавливает JSON
  3. инициализирует Redux-store
  4. рендерит карту

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

Инъекция данных в встраиваемый код

Генерация embed-кода требует строгого разделения данных и конфигурации. Данные передаются в формате dataset-объектов:

const dataset = {
  data: rawGeoJson,
  info: {
    label: 'Points Layer',
    id: 'points'
  }
};

При генерации embed-кода данные объединяются с конфигурацией слоя:

const embedPayload = {
  datasets: [dataset],
  config: mapConfig
};

При этом важно учитывать:

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

Автоматическая генерация конфигурации слоёв

Kepler.gl позволяет автоматически формировать слои на основе структуры данных. При генерации embed-кода это используется для упрощения конфигурации.

Алгоритм включает:

  1. анализ колонок датасета
  2. определение географических полей
  3. выбор типа слоя (point, arc, heatmap, hexagon)
  4. создание базового слоя конфигурации

Пример результата:

const autoLayerConfig = {
  layers: [
    {
      id: 'point-layer',
      type: 'point',
      config: {
        dataId: 'dataset_1',
        columns: {
          lat: 'latitude',
          lng: 'longitude'
        }
      }
    }
  ]
};

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

Встраивание в статические веб-страницы

Статический embed-код обычно включает минимальный HTML-контейнер и подключение Kepler.gl-бандла.

Структура:

<div id="kepler-map"></div>

<script src="kepler.gl.bundle.js"></script>

<script>
  const config = window.__KEPLER_CONFIG__;

  keplerGl.renderToDOM({
    id: 'kepler-map',
    data: window.__DATASET__,
    config: config
  });
</script>

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

Управление версиями embed-конфигураций

Встраиваемый код чувствителен к изменениям структуры состояния. Для обеспечения совместимости используется поле версии:

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

При генерации embed-кода учитываются следующие факторы:

  • обратная совместимость слоёв
  • миграция структуры фильтров
  • обновления mapState
  • изменения в API визуализации

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

Динамическая генерация embed-кода на сервере

В серверной генерации embed-кода формируется полный пакет конфигурации, включающий:

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

Пример серверной функции:

function buildKeplerEmbed(data) {
  const dataset = normalizeData(data);

  const config = generateConfig(dataset);

  return {
    html: exportToHtml({ datasets: [dataset], config }),
    config
  };
}

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

Оптимизация embed-кода для производительности

При генерации встраиваемого кода учитываются ограничения WebGL и браузерного рендеринга:

  • уменьшение количества точек через агрегацию
  • кэширование tile-слоёв
  • ограничение глубины фильтров
  • отключение лишних интерактивных событий

Конфигурация может включать параметры оптимизации:

const performanceConfig = {
  animation: false,
  visState: {
    interactionConfig: {
      tooltip: { enabled: true }
    }
  }
};

Эти параметры напрямую влияют на стабильность встроенной карты в сторонних приложениях.

Инкапсуляция embed-кода в модули JavaScript

Для повторного использования embed-код часто упаковывается в отдельный модуль:

export const keplerEmbed = {
  dataset,
  config,
  init(target) {
    return renderKeplerGl({
      id: target,
      datasets: [this.dataset],
      config: this.config
    });
  }
};

Такой подход обеспечивает переносимость между проектами и упрощает интеграцию в различные фронтенд-архитектуры.

Оглавление