Load и error события

Событие load является ключевым моментом жизненного цикла карты. Оно возникает после того, как экземпляр карты полностью инициализирован и завершил загрузку всех обязательных ресурсов начального состояния: стиля, источников данных и базовой структуры слоёв.

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

Момент возникновения load

Событие срабатывает после выполнения следующих этапов:

  • загружен и применён style JSON
  • инициализированы источники данных (sources)
  • завершена первичная загрузка тайлов, необходимых для начального viewport
  • построена внутренняя структура слоёв
  • завершена подготовка WebGL контекста

Карта считается «готовой к взаимодействию» именно в этот момент.

Подписка на load

import maplibregl from "maplibre-gl";

const map = new maplibregl.Map({
    container: "map",
    style: "https://demotiles.maplibre.org/style.json",
    center: [30.3, 59.9],
    zoom: 10
});

map.on("load", () => {
    map.addSource("points", {
        type: "geojson",
        data: {
            type: "FeatureCollection",
            features: []
        }
    });

    map.addLayer({
        id: "points-layer",
        type: "circle",
        source: "points",
        paint: {
            "circle-radius": 6,
            "circle-color": "#3b82f6"
        }
    });
});

Любые операции, связанные с добавлением слоёв, источников или манипуляцией стилем, должны выполняться после load, иначе возникает риск обращения к неинициализированному состоянию стиля.

Важные особенности load

Однократность события

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

Отличие от style.load

load не следует путать с style.load:

  • style.load — событие уровня стиля, срабатывает при загрузке или смене style JSON
  • load — событие уровня карты, сигнализирует о полной готовности визуального состояния

В типичных сценариях load используется как универсальная точка инициализации.

Влияние асинхронной загрузки тайлов

Даже после load отдельные тайлы могут подгружаться асинхронно при изменении масштаба или перемещении карты. Это означает:

  • load не гарантирует завершение всех возможных сетевых запросов
  • он гарантирует только готовность базовой сцены

Событие error

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

Типы ошибок

На практике error охватывает несколько категорий:

  • ошибки загрузки стиля (style JSON недоступен или некорректен)
  • ошибки источников данных (GeoJSON, vector tiles, raster tiles)
  • сетевые ошибки (HTTP 4xx, 5xx, CORS)
  • ошибки WebGL контекста
  • ошибки парсинга слоёв и выражений стиля

Подписка на error

map.on("error", (e) => {
    console.error("Map error:", e.error);
});

Объект события обычно содержит поле error, в котором находится исходное исключение или диагностическая информация.

Практическая модель обработки ошибок

Логирование сетевых ошибок

map.on("error", (e) => {
    if (e && e.error) {
        console.log("Ошибка карты:", e.error.message);
    }
});

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

Фильтрация некритических ошибок

Некоторые ошибки могут быть нефатальными (например, отсутствие отдельных тайлов):

map.on("error", (e) => {
    const error = e.error;

    if (!error) return;

    if (error.status === 404) {
        return;
    }

    console.warn("Критическая ошибка:", error);
});

Типичные сценарии возникновения error

Недоступный style JSON

Если URL стиля недоступен или возвращает некорректный JSON, карта не сможет завершить инициализацию.

new maplibregl.Map({
    container: "map",
    style: "https://example.com/missing-style.json"
});

Результатом станет событие error с информацией о сетевом сбое.

Ошибки источников данных

GeoJSON с некорректной структурой приводит к ошибкам парсинга:

map.addSource("bad-source", {
    type: "geojson",
    data: "invalid-string"
});

Такие ошибки проявляются сразу после попытки интерпретации источника.

Ошибки WebGL

При проблемах с графическим контекстом (например, потеря контекста GPU) генерируются ошибки рендеринга. Это критические сбои, влияющие на отображение всей карты.

Взаимодействие load и error

События load и error формируют базовый цикл готовности карты:

  • load сигнализирует об успешной инициализации
  • error фиксирует любые отклонения от нормального состояния

При этом error может возникать как до load, так и после него.

Обработка до готовности карты

const map = new maplibregl.Map({ ... });

map.on("error", (e) => {
    console.log("Ошибка до load или после:", e.error);
});

map.on("load", () => {
    console.log("Карта готова");
});

Особенности повторной загрузки стиля

При вызове setStyle происходит частичный перезапуск жизненного цикла:

map.setStyle("https://example.com/new-style.json");

После смены стиля снова возникают:

  • повторная инициализация слоёв
  • повторная загрузка источников
  • повторное событие load

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

Диагностическая структура события error

Внутренняя структура ошибки может включать:

  • message — текст ошибки
  • status — HTTP код
  • url — ресурс, вызвавший сбой
  • type — тип источника (tile, style, sprite)

Пример анализа:

map.on("error", (e) => {
    const err = e.error;

    if (err?.status === 401) {
        console.log("Проблема авторизации при загрузке ресурса");
    }

    if (err?.type === "sprite") {
        console.log("Ошибка загрузки спрайта стиля");
    }
});

Поведение при каскадных ошибках

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

  • отдельные слои могут быть пустыми
  • тайлы могут отображаться частично
  • стилизация может быть нарушена

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

Оглавление