Структура объекта config

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

Конфигурация используется для:

  • сохранения состояния проекта;
  • экспорта и импорта карт;
  • восстановления визуализации после перезагрузки приложения;
  • программного создания карт;
  • передачи настроек между различными экземплярами Kepler.gl.

В большинстве случаев конфигурация экспортируется через интерфейс Kepler.gl и представляет собой большой JSON-объект.

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

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

Каждый из разделов отвечает за отдельную часть состояния карты.

Общая структура конфигурации

Полный объект содержит несколько крупных блоков:

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

Описание разделов:

Раздел Назначение
version Версия формата конфигурации
visState Визуализация данных
mapState Состояние карты
mapStyle Стиль подложки карты

Фактически вся визуальная логика находится внутри объекта config.

Поле version

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

Пример:

{
  version: "v1"
}

Kepler.gl использует это значение для корректной интерпретации структуры объекта.

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

Раздел visState

visState содержит информацию обо всех объектах визуализации.

Типичная структура:

{
  visState: {
    filters: [],
    layers: [],
    interactionConfig: {},
    layerBlending: "normal",
    splitMaps: [],
    animationConfig: {}
  }
}

Это самый объёмный раздел конфигурации.

Массив filters

Содержит все фильтры, применённые к данным.

Пример:

filters: [
  {
    dataId: "earthquakes",
    id: "date-filter",
    name: ["date"],
    type: "timeRange",
    value: [
      1577836800000,
      1609459200000
    ]
  }
]

Основные свойства фильтра:

Поле Назначение
dataId Источник данных
id Уникальный идентификатор
name Поле датасета
type Тип фильтра
value Значение фильтра

Типы фильтров

Наиболее распространённые варианты:

type: "range"

Числовой диапазон.

type: "timeRange"

Временной диапазон.

type: "multiSelect"

Множественный выбор значений.

type: "select"

Одиночный выбор.

Массив layers

Содержит описание всех слоёв карты.

Пример:

layers: [
  {
    id: "points-layer",
    type: "point",
    config: {},
    visualChannels: {}
  }
]

Каждый слой включает две основные части:

  • config
  • visualChannels

Структура слоя

Минимальный пример:

{
  id: "layer-1",
  type: "point",
  config: {},
  visualChannels: {}
}

Поле id

Уникальный идентификатор слоя.

id: "cities-layer"

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

Поле type

Определяет тип визуализации.

Примеры:

type: "point"
type: "arc"
type: "line"
type: "grid"
type: "hexagon"
type: "heatmap"
type: "geojson"
type: "trip"

Объект layer.config

Внутри объекта config находятся настройки конкретного слоя.

Пример:

config: {
  dataId: "cities",
  label: "Cities",
  color: [18, 147, 154],
  columns: {},
  isVisible: true,
  visConfig: {}
}

dataId

Связь слоя с набором данных.

dataId: "cities"

Значение должно совпадать с идентификатором загруженного датасета.

label

Отображаемое имя слоя.

label: "Major Cities"

Показывается в панели слоёв.

color

Базовый цвет слоя.

color: [255, 0, 0]

Формат RGB:

[R, G, B]

Например:

[34, 63, 154]

isVisible

Управляет отображением слоя.

isVisible: true

или

isVisible: false

columns

Определяет соответствие колонок данным слоя.

Для точек:

columns: {
  lat: "latitude",
  lng: "longitude"
}

Для дуг:

columns: {
  lat0: "origin_lat",
  lng0: "origin_lng",
  lat1: "dest_lat",
  lng1: "dest_lng"
}

Для линий:

columns: {
  geojson: "_geojson"
}

Объект visConfig

Содержит параметры визуального отображения.

Пример:

visConfig: {
  radius: 20,
  opacity: 0.8,
  filled: true,
  stroked: false
}

Содержимое зависит от типа слоя.

radius

Размер точек.

radius: 10

Чем больше значение, тем крупнее маркеры.

opacity

Прозрачность.

opacity: 0.7

Диапазон:

0 — полностью прозрачный
1 — полностью непрозрачный

filled

Заполнение фигур.

filled: true

stroked

Отрисовка контура.

stroked: true

thickness

Толщина линий.

thickness: 2

Используется для линейных слоёв.

colorRange

Цветовая палитра.

colorRange: {
  name: "Global Warming",
  type: "sequential",
  colors: [
    "#5A1846",
    "#900C3F",
    "#C70039",
    "#E3611C"
  ]
}

Используется тепловыми картами, сетками и агрегированными слоями.

Объект visualChannels

Позволяет связывать визуальные свойства с полями данных.

Пример:

visualChannels: {
  colorField: {
    name: "population",
    type: "integer"
  }
}

colorField

Поле для окраски объектов.

colorField: {
  name: "category",
  type: "string"
}

colorScale

Тип цветовой шкалы.

colorScale: "quantile"

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

"quantile"
"quantize"
"ordinal"

sizeField

Поле для изменения размеров объектов.

sizeField: {
  name: "population",
  type: "integer"
}

sizeScale

Способ масштабирования.

sizeScale: "sqrt"

Другие варианты:

"linear"
"log"
"point"

interactionConfig

Настройки взаимодействия пользователя с картой.

Пример:

interactionConfig: {
  tooltip: {},
  brush: {},
  geocoder: {},
  coordinate: {}
}

tooltip

Управляет всплывающими подсказками.

Пример:

tooltip: {
  enabled: true,
  fieldsToShow: {
    cities: [
      {
        name: "name"
      },
      {
        name: "population"
      }
    ]
  }
}

enabled

Включение подсказок.

enabled: true

fieldsToShow

Поля для отображения.

fieldsToShow: {
  dataset: [
    { name: "city" },
    { name: "country" }
  ]
}

brush

Инструмент пространственного выделения.

brush: {
  enabled: true,
  size: 0.5
}

geocoder

Строка поиска адресов.

geocoder: {
  enabled: true
}

coordinate

Показ координат курсора.

coordinate: {
  enabled: true
}

layerBlending

Режим смешивания слоёв.

Пример:

layerBlending: "additive"

Варианты:

"normal"
"additive"
"subtractive"

splitMaps

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

Пример:

splitMaps: []

При разделённом режиме может содержать несколько представлений карты.

animationConfig

Настройки временной анимации.

Пример:

animationConfig: {
  currentTime: null,
  speed: 1
}

currentTime

Текущая позиция временной шкалы.

currentTime: 1650000000000

speed

Скорость воспроизведения.

speed: 2

Раздел mapState

Содержит состояние камеры карты.

Пример:

mapState: {
  bearing: 0,
  dragRotate: false,
  latitude: 55.7558,
  longitude: 37.6176,
  pitch: 0,
  zoom: 8
}

latitude

Широта центра карты.

latitude: 40.7128

longitude

Долгота центра карты.

longitude: -74.0060

zoom

Масштаб.

zoom: 10

Чем больше значение, тем сильнее приближение.

pitch

Наклон камеры.

pitch: 45

Позволяет получить псевдо-3D представление.

bearing

Поворот карты.

bearing: 90

Измеряется в градусах.

dragRotate

Разрешение вращения карты.

dragRotate: true

isSplit

Флаг режима разделения карты.

isSplit: false

Раздел mapStyle

Определяет визуальный стиль подложки.

Пример:

mapStyle: {
  styleType: "dark",
  visibleLayerGroups: {},
  topLayerGroups: {},
  threeDBuildingColor: [9, 17, 31]
}

styleType

Базовый стиль карты.

Примеры:

styleType: "dark"
styleType: "light"
styleType: "satellite"

visibleLayerGroups

Управление видимостью слоёв подложки.

Пример:

visibleLayerGroups: {
  label: true,
  road: true,
  border: false,
  building: true,
  water: true,
  land: true
}

Каждая группа может быть отдельно включена или отключена.

topLayerGroups

Слои, отображаемые поверх остальных.

Пример:

topLayerGroups: {
  label: true
}

Чаще всего используется для подписей населённых пунктов и дорог.

threeDBuildingColor

Цвет трёхмерных зданий.

threeDBuildingColor: [
  218,
  112,
  191
]

mapStyles

Пользовательские стили карты

Kepler.gl позволяет подключать собственные стили Mapbox.

Пример:

mapStyles: {
  customStyle: {
    id: "custom-style",
    label: "Corporate Style",
    url: "mapbox://styles/company/style-id"
  }
}

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

Полный пример объекта config

const config = {
  version: "v1",
  config: {
    visState: {
      filters: [],
      layers: [
        {
          id: "cities",
          type: "point",
          config: {
            dataId: "cities",
            label: "Cities",
            color: [18, 147, 154],
            columns: {
              lat: "latitude",
              lng: "longitude"
            },
            isVisible: true,
            visConfig: {
              radius: 20,
              opacity: 0.8,
              filled: true
            }
          },
          visualChannels: {
            colorField: null,
            sizeField: null
          }
        }
      ],
      interactionConfig: {
        tooltip: {
          enabled: true
        }
      },
      layerBlending: "normal",
      splitMaps: [],
      animationConfig: {
        speed: 1
      }
    },
    mapState: {
      latitude: 55.7558,
      longitude: 37.6176,
      zoom: 8,
      bearing: 0,
      pitch: 0
    },
    mapStyle: {
      styleType: "dark",
      visibleLayerGroups: {
        label: true,
        road: true,
        water: true
      }
    }
  }
};

Данный объект полностью описывает состояние визуализации: источник данных, настройки слоёв, параметры отображения, текущее положение камеры и внешний вид картографической подложки. Благодаря этому config выступает универсальным механизмом сериализации и восстановления проектов Kepler.gl, позволяя хранить всю конфигурацию карты в одном JSON-документе.

Оглавление