Actions

Система управления состоянием в Kepler.gl построена вокруг модели однонаправленного потока данных, где ключевую роль играют actions (действия). Они представляют собой описания намерений изменить состояние карты: добавить данные, изменить слой, обновить фильтры, перестроить представление или модифицировать параметры визуализации.

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

Базовый принцип работы действий

Каждое действие в Kepler.gl:

  • описывает конкретное изменение состояния
  • является чистым объектом
  • передаётся через dispatch
  • обрабатывается соответствующим reducer’ом

Структура типичного действия:

{
  type: 'ACTION_NAME',
  payload: { ...данные... }
}

В большинстве случаев разработчик не формирует такие объекты вручную, а использует action creators из пакета kepler.gl/actions.

Основные группы действий

Система действий в Kepler.gl логически разделена на несколько областей состояния:

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

Каждая группа управляется собственным набором действий.

Добавление данных в карту

Одно из ключевых действий — загрузка данных.

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

Используется для первичной инициализации или добавления нового датасета:

dispatch(
  addDataToMap({
    datasets: {
      info: {
        label: 'Sample dataset',
        id: 'sample_data'
      },
      data: csvData
    },
    option: {
      centerMap: true,
      readOnly: false
    },
    config: {
      visState: {
        layers: [
          {
            id: 'point-layer',
            type: 'point'
          }
        ]
      }
    }
  })
);

Особенности:

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

Управление слоями (Layers)

Слои являются основой визуализации. Actions позволяют создавать, изменять и удалять их.

Добавление слоя

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

dispatch(addLayer({
  datasetId: 'sample_data',
  config: {
    type: 'hexagon',
    id: 'heatmap-layer'
  }
}));

Обновление слоя

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

dispatch(layerUpdate({
  layerId: 'heatmap-layer',
  config: {
    color: [255, 0, 0],
    radius: 20
  }
}));

Переключение видимости

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

dispatch(toggleLayer('heatmap-layer'));

Работа с фильтрами

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

Добавление фильтра

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

dispatch(addFilter('sample_data'));

Обновление фильтра

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

dispatch(updateFilter('filter_id', {
  value: [10, 50],
  animationWindow: 'free'
}));

Удаление фильтра

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

dispatch(removeFilter('filter_id'));

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

Управление состоянием карты

Состояние карты включает центр, масштаб, наклон и ориентацию.

Обновление viewport

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

dispatch(updateMap({
  latitude: 53.2,
  longitude: 50.1,
  zoom: 10,
  bearing: 0,
  pitch: 45
}));

Автоцентрирование

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

addDataToMap({
  datasets: {...},
  option: {
    centerMap: true
  }
})

Управление датасетами

Удаление датасета

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

dispatch(removeDataset('sample_data'));

Удаление датасета автоматически очищает:

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

Синхронизация состояния визуализации

Kepler.gl разделяет визуальное состояние на независимые блоки, но actions позволяют синхронизировать их.

Обновление visState целиком

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

dispatch(updateVisData({
  datasets: [...],
  config: {
    visState: {
      filters: [],
      layers: []
    }
  }
}));

Используется при:

  • восстановлении сохранённой карты
  • загрузке конфигурации из JSON
  • миграции состояний

Управление стилями карты

MapStyle actions отвечают за визуальное оформление базовой карты.

Обновление стиля

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

dispatch(updateMapStyle({
  styleType: 'dark',
  visibleLayerGroups: {
    label: true,
    road: false,
    border: true
  }
}));

Переключение базовой карты

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

dispatch(setDefaultMapStyle('satellite'));

UI Actions

UI-состояние включает модальные окна, панели и настройки интерфейса.

Открытие панели

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

dispatch(toggleSidePanel('layer'));

Показ модального окна

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

dispatch(openModal('exportData'));

Закрытие интерфейсных элементов

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

dispatch(closeModal());

Композиция действий

Actions в Kepler.gl можно комбинировать для создания сложных сценариев.

Пример загрузки данных с последующей настройкой слоя и фильтра:

dispatch(
  addDataToMap({
    datasets: {...},
    option: {centerMap: true}
  })
);

dispatch(
  addFilter('dataset_id')
);

dispatch(
  layerUpdate({
    layerId: 'layer_1',
    config: {
      opacity: 0.8
    }
  })
);

Такая последовательность формирует детерминированное состояние карты.

Асинхронные сценарии

Хотя actions выглядят синхронными, в реальных приложениях они часто используются вместе с middleware (например, Redux Thunk).

Пример загрузки данных из API:

const loadGeoData = () => async (dispatch) => {
  const response = await fetch('/data/points.geojson');
  const data = await response.json();

  dispatch(
    addDataToMap({
      datasets: {
        info: {id: 'geo', label: 'Geo Data'},
        data
      }
    })
  );
};

Переиспользование конфигураций

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

Экспорт состояния

Состояние Kepler.gl может быть сохранено через mapState, visState и mapStyle, а затем восстановлено:

dispatch(
  addDataToMap(savedConfig)
);

Это делает actions основным механизмом для:

  • версионирования карт
  • шаринга визуализаций
  • восстановления сессий

Взаимодействие actions с Redux-потоком

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

  1. Action creator формирует действие
  2. dispatch отправляет его в store
  3. middleware (если есть) обрабатывает побочные эффекты
  4. reducer обновляет state
  5. React-компоненты Kepler.gl получают обновлённые props

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

Типизация и стабильность

В TypeScript-окружениях actions имеют строгие типы, что позволяет:

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

Типы обычно импортируются из пакета Kepler.gl вместе с actions.

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

Роль actions в расширении Kepler.gl

Actions являются точкой расширения системы. Через них можно:

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

Именно через actions происходит вся управляемая модификация состояния, что делает их центральным механизмом всей архитектуры Kepler.gl.

Оглавление