Data события

Архитектура MapLibre GL JS построена вокруг непрерывного цикла загрузки, обработки и отрисовки геоданных. В основе этого цикла лежит поток событий, отражающих состояние стиля, источников данных, тайлов и процесса рендеринга. События, связанные с данными, позволяют отслеживать жизненный цикл загрузки географических слоёв, управлять состоянием интерфейса и синхронизировать внешние процессы с внутренним состоянием карты.

Общая модель потока данных

Процесс отображения карты проходит несколько стадий:

  • загрузка стиля (style)
  • инициализация источников (sources)
  • загрузка тайлов и данных (tiles)
  • подготовка к отрисовке (render)
  • стабилизация состояния (idle)

Каждая стадия сопровождается соответствующими событиями, которые формируют основу наблюдаемой реактивной модели.

События загрузки стиля

styledata

Событие styledata возникает при изменениях в структуре стиля карты. Это может включать:

  • добавление или удаление слоёв
  • изменение источников данных
  • обновление layout или paint свойств
  • динамическое переключение стиля

Сигнал отражает факт того, что внутренняя модель стиля была пересобрана или модифицирована.

map.on('styledata', (e) => {
    const style = map.getStyle();
    console.log('Изменение стиля:', style.layers.length);
});

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

styledataloading

Событие styledataloading срабатывает перед тем, как новые данные стиля начинают загружаться или пересобираться.

Фаза загрузки включает:

  • получение нового style JSON
  • обновление источников
  • пересборку зависимостей слоёв
map.on('styledataloading', () => {
    console.log('Начало загрузки стиля');
});

Это событие отражает старт критической фазы обновления визуальной модели.

События источников данных

sourcedataloading

Событие sourcedataloading сигнализирует о начале загрузки данных конкретного источника (source).

Источниками могут быть:

  • vector tiles
  • raster tiles
  • GeoJSON
  • image sources
  • video sources
map.on('sourcedataloading', (e) => {
    console.log('Источник загружается:', e.sourceId);
});

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

sourcedata

Событие sourcedata отражает изменения состояния источника данных. Оно вызывается:

  • при загрузке новых тайлов
  • при обновлении GeoJSON
  • при завершении загрузки части данных
map.on('sourcedata', (e) => {
    if (e.isSourceLoaded) {
        console.log('Источник полностью загружен:', e.sourceId);
    }
});

Ключевым свойством события является isSourceLoaded, показывающее завершённость загрузки конкретного источника.

События данных карты

dataloading

Событие dataloading возникает при начале загрузки любых данных, участвующих в рендеринге карты.

Оно охватывает:

  • тайлы векторных слоёв
  • растровые изображения
  • GeoJSON обновления
  • данные источников
map.on('dataloading', () => {
    console.log('Началась загрузка данных карты');
});

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

data

Событие data фиксирует изменения в состоянии данных карты. Оно может возникать многократно в процессе одного кадра рендеринга.

Типичные случаи:

  • загрузка тайла завершена
  • данные источника обновлены
  • произошла частичная или полная синхронизация данных
map.on('data', (e) => {
    console.log('Тип события данных:', e.dataType);
    console.log('Источник:', e.sourceId);
});

Поле dataType может принимать значения:

  • source
  • style
  • tile

Событие играет роль универсального уведомления о любых изменениях в data pipeline.

События завершения загрузки

idle

Событие idle возникает, когда карта завершает все активные процессы:

  • отсутствуют загружающиеся тайлы
  • нет ожидающих запросов
  • завершены все анимации рендеринга
map.on('idle', () => {
    console.log('Карта находится в стабильном состоянии');
});

Состояние idle часто используется как индикатор готовности карты к взаимодействию или следующему циклу обновления данных.

События рендеринга, связанные с данными

render

Событие render срабатывает при каждом кадре отрисовки карты.

Хотя оно не является строго data-событием, оно тесно связано с обновлением данных, поскольку каждый рендер может быть вызван:

  • поступлением новых тайлов
  • изменением источника
  • пересчётом стиля
map.on('render', () => {
    const zoom = map.getZoom();
    console.log('Рендер кадра, zoom:', zoom);
});

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

Взаимодействие событий в жизненном цикле данных

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

  1. dataloading — начинается загрузка данных
  2. sourcedataloading — активируется конкретный источник
  3. data — поступают промежуточные обновления
  4. sourcedata — фиксируется состояние источника
  5. data — финальное обновление после синхронизации
  6. idle — завершение всех процессов

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

Обработка ошибок, связанных с данными

error

Событие error сигнализирует о сбоях в процессе загрузки или обработки данных.

Причины могут включать:

  • недоступность tile server
  • ошибки парсинга GeoJSON
  • некорректный style JSON
  • проблемы с сетевыми запросами
map.on('error', (e) => {
    console.log('Ошибка карты:', e.error);
});

Хотя error не относится строго к data-событиям, он является частью того же потока, так как большинство ошибок возникают в процессе загрузки данных.

Фильтрация событий по источникам

Многие события поддерживают фильтрацию по sourceId, что позволяет отслеживать состояние конкретных данных.

map.on('sourcedata', (e) => {
    if (e.sourceId === 'cities') {
        console.log('Обновление источника cities');
    }
});

Такой подход особенно важен при работе с множеством слоёв и разнородных источников, где каждый поток данных имеет независимую жизненную логику.

Асинхронная природа data-событий

Data-события в MapLibre GL JS не следуют строгой линейной последовательности. Они:

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

Это делает систему событий реактивной, а не детерминированной.

Тайловая модель и data-события

Векторные и растровые тайлы являются основным источником data-событий. При изменении viewport происходит:

  • определение необходимых тайлов
  • загрузка недостающих фрагментов
  • обновление кэша
  • триггер событий dataloading и data

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

Согласование состояния карты

Состояние карты считается согласованным, когда:

  • все источники завершили загрузку
  • отсутствуют активные tile request
  • стиль стабилен
  • отсутствуют pending update операции

Событие idle является финальным маркером этого состояния и завершает цикл data pipeline до следующего изменения входных параметров карты.

Оглавление