Отладка стилей

Модель стиля и причины типичных ошибок

Система стилей в MapLibre GL JS основана на декларативном JSON-описании, где карта собирается из источников данных, слоёв и визуальных правил. Ошибки в стиле возникают не в виде исключений, а как визуальные артефакты: отсутствующие слои, неверные цвета, «пустая» карта, смещённые подписи.

Ключевые источники проблем:

  • некорректная структура style JSON
  • несоответствие источников (sources) и слоёв (layers)
  • ошибки в выражениях (expressions)
  • отсутствие тайлов или сетевых ресурсов (sprite, glyphs)
  • конфликт порядка слоёв (z-order)
  • несовместимость версий style spec

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

Проверка базовой структуры стиля

Первый уровень диагностики — валидность JSON-структуры стиля. Даже при отсутствии синтаксических ошибок JavaScript, стиль может быть логически некорректным.

Критические элементы:

  • version — должна соответствовать спецификации (обычно 8)
  • sources — все источники должны быть определены до использования
  • layers — каждый слой обязан ссылаться на существующий source
  • sprite и glyphs — должны быть доступны по URL

Типичная ошибка:

  • слой ссылается на source: "roads", которого нет в sources

При этом карта загрузится, но слой будет молча проигнорирован.

Использование консоли и событий карты

Runtime-отладка начинается с событий жизненного цикла карты:

  • load — завершена загрузка стиля
  • styledata — обновление стиля
  • sourcedata — загрузка данных источника
  • error — критические и сетевые ошибки

Регистрация логов:

map.on('error', (e) => {
    console.error('MapLibre error:', e.error);
});

map.on('sourcedata', (e) => {
    console.log('Source data:', e.sourceId, e.isSourceLoaded);
});

Событие error часто содержит недокументированные подсказки: отсутствие тайлов, 404 на sprite, неверный URL glyphs.

Debug-режим и визуальная диагностика

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

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

Типичный режим:

map.showTileBoundaries = true;
map.showCollisionBoxes = true;
map.showPadding = true;

Эти режимы особенно полезны при работе с символами (labels), где проблемы часто связаны с коллизиями и скрытием текста.

Проверка источников данных (sources)

Ошибки в источниках данных приводят к «пустым» слоям без ошибок в UI.

Основные проверки:

  • корректность URL vector tiles
  • доступность CORS
  • правильный type (vector, raster, geojson)
  • совпадение source-layer в vector tiles

Пример типичной ошибки:

"source-layer": "roads"

но внутри тайла слой называется transportation — результат: слой не отображается.

Отладка выполняется через:

  • проверку сетевых запросов в DevTools
  • просмотр содержимого tile через инспектор
  • тестирование URL напрямую

Отладка слоёв (layers)

Слои — основной источник визуальной сложности. Ошибки чаще всего связаны с:

Порядком слоёв

Слои рендерятся строго по порядку в массиве layers. Верхние перекрывают нижние.

Проблема:

  • полигоны перекрывают линии
  • label слой скрыт fill-слоем

Решение — анализ before вставки:

map.addLayer(layer, 'waterway-label');

Видимость слоя

Свойство:

"layout": {
  "visibility": "none"
}

Часто слой существует, но отключён логически. При отладке важно проверять состояние слоя:

map.getLayoutProperty('layer-id', 'visibility');

Минимальный zoom

"minzoom": 10

Если карта на zoom 8 — слой «исчезает» без ошибок.

Отладка выражений (expressions)

Выражения — один из самых частых источников скрытых ошибок.

Примеры проблем:

  • неправильные типы данных
  • обращение к отсутствующим свойствам
  • несовместимые операторы

Типичная ошибка:

["get", "height"]

но в данных height отсутствует.

Результат — значение становится null, стиль деградирует без исключений.

Полезная стратегия — упрощение выражений до базовых:

["get", "property"]

и постепенное расширение логики.

Отладка символов (text, icons)

Символьные слои зависят от двух внешних ресурсов:

  • glyphs (шрифты)
  • sprite (иконки)

Glyphs

Ошибка glyphs приводит к:

  • отсутствию текста
  • квадратам вместо символов

Проверка:

  • URL glyphs должен отдавать .pbf
  • CORS должен разрешать доступ

Sprite

Sprite состоит из:

  • JSON описания
  • PNG атласа

Если JSON загружается, но PNG недоступен — иконки исчезают без ошибок уровня UI.

Сетевые проблемы и кеширование

DevTools Network — основной инструмент диагностики:

Проверяются:

  • 404 на tiles
  • блокировка CORS
  • медленная загрузка tile серверов
  • кешированные старые стили

Особенно критично:

  • сервис-воркеры, возвращающие устаревшие style.json
  • CDN с задержкой обновления sprite

Отладка GeoJSON источников

GeoJSON часто используется для динамических данных.

Проблемы:

  • некорректная геометрия (self-intersection)
  • слишком большие файлы
  • неверный CRS (должен быть WGS84)

Полезно временно упростить слой:

map.getSource('data').setData({
  type: 'FeatureCollection',
  features: []
});

Если слой появляется — проблема в данных.

Проверка рендеринга и производительности

Некоторые ошибки стилей проявляются как:

  • лаги при zoom
  • исчезновение слоёв при pan
  • «мигание» объектов

Причины:

  • перегруженные фильтры (filter)
  • сложные выражения в paint
  • слишком много слоёв символов

Инструменты диагностики:

  • FPS мониторинг
  • tile count inspection
  • layer profiling через упрощение стиля

Изоляция проблем через минимизацию стиля

Методика «нулевого стиля»:

  1. оставить только background
  2. добавить один источник
  3. добавить один слой
  4. постепенно расширять

Это позволяет локализовать:

  • проблемный слой
  • проблемный source
  • конфликт выражений

Частые скрытые ошибки конфигурации

  • несовпадение id слоя и ссылок из before
  • дублирование id слоёв
  • использование устаревших свойств style spec
  • отсутствие scheme: "xyz" для raster tiles
  • неправильный tileSize

Логирование состояния стиля

Полезные методы:

console.log(map.getStyle());
console.log(map.getLayer('layer-id'));
console.log(map.getSource('source-id'));

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

Диагностика обновлений стиля в runtime

При динамическом обновлении:

map.setStyle(newStyle);

возможны проблемы:

  • потеря источников
  • сброс слоёв
  • задержка загрузки glyphs/sprites

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

Отладка коллизий и скрытия текста

Label-слои могут исчезать из-за collision detection.

Проверка:

map.showCollisionBoxes = true;

Если текст есть, но не виден — причина в:

  • плотности подписей
  • приоритете слоёв
  • anchor настройках

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

Фильтры часто становятся источником «пустых» слоёв:

"filter": ["==", "type", "primary"]

Если значение не совпадает с данными — слой пуст.

Отладка:

  • временно удалить filter
  • заменить на ["has", "type"]

Проверка взаимодействия слоёв и источников

Критическая связка:

  • layer → source → source-layer

Любое несоответствие приводит к отсутствию визуализации без явной ошибки.

Метод диагностики:

  • проверить source-layer в тайле
  • сверить с style.json
  • протестировать через упрощённый слой

Инструментальная стратегия локализации ошибок

Практическая последовательность:

  • проверка Network
  • проверка console error
  • отключение слоёв по одному
  • упрощение expressions
  • замена источника на GeoJSON
  • проверка sprite/glyphs отдельно

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

Оглавление