Различия в API

Mapbox GL JS строится вокруг императивной модели управления картой, где ключевой объект Map выступает центральной точкой взаимодействия. Вокруг него концентрируются все операции: создание источников данных, управление слоями, подписка на события и модификация состояния рендера. При этом API сохраняет чёткое разделение между конфигурацией стиля и динамическими изменениями во время исполнения.

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

Инициализация карты и жизненный цикл

Объект карты создаётся через конструктор Map, который принимает объект конфигурации. В API различаются подходы к обработке жизненного цикла:

• синхронная инициализация объекта
• асинхронная загрузка стиля и ресурсов
• событие load как точка готовности для работы со слоями

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

Работа со стилями

API стилей представляет собой декларативную модель, основанную на спецификации Style Specification. Стиль — это JSON-структура, описывающая:

• источники данных (sources)
• слои визуализации (layers)
• свойства рендера (light, fog, terrain и др.)

Различие API заключается в том, что стиль можно:

• задавать при инициализации карты
• заменять целиком через setStyle
• модифицировать частично через addLayer, removeLayer, setPaintProperty, setLayoutProperty

Переход между стилями не является мгновенной операцией с точки зрения внутреннего рендера: происходит пересборка графа слоёв и переинициализация WebGL контекста.

Источники данных (Sources API)

Источники данных в API разделены по типам:

• geojson
• vector
• raster
• image
• video
• raster-dem

Различие API проявляется в способе обновления источников. Для GeoJSON используется метод setData, который позволяет обновлять данные без пересоздания источника. Векторные и растровые источники, напротив, зависят от тайловой структуры и обновляются через изменение URL-шаблонов или параметров.

Существенным отличием является наличие строгой связи между источником и слоями: слой не может существовать без привязанного source, что фиксируется на уровне API и проверяется во время выполнения.

Слойная модель и управление визуализацией

Слой в API представляет собой отдельную единицу визуализации, описывающую:

• тип рендера (fill, line, circle, symbol, heatmap и др.)
• источник данных
• фильтрацию данных
• стилизацию (paint properties)
• компоновку (layout properties)

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

Изменение свойств слоя происходит через отдельные методы:

• setPaintProperty
• setLayoutProperty

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

Событийная модель

API событий построено на подписочной модели. Объект карты поддерживает события:

• загрузки (load, idle)
• взаимодействия (click, mousemove, drag)
• состояния рендера (render, resize)

Различие заключается в том, что события привязаны не только к DOM, но и к WebGL-сцене. Например, координаты клика вычисляются относительно географической проекции, а не пиксельной сетки.

Дополнительно присутствует слой абстракции hit-testing, который позволяет определять попадание курсора в географические объекты через методы queryRenderedFeatures и querySourceFeatures.

Координатная система и проекции

API использует Web Mercator как базовую проекцию. Это накладывает ограничения на геометрические вычисления и влияет на работу с расстояниями и площадями.

Различие API заключается в том, что географические координаты (lng, lat) используются как основная единица, тогда как экранные координаты (x, y) являются производными и вычисляются через матрицы трансформации.

При этом доступны методы:

• project — перевод координат в экранные
• unproject — обратное преобразование

Эти методы являются ключевыми для построения пользовательских интерактивных слоёв поверх карты.

Рендеринг и WebGL слой

Рендеринг в Mapbox GL JS осуществляется через WebGL, что радикально отличает API от Canvas- или DOM-ориентированных библиотек.

Основные отличия API рендера:

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

API не предоставляет прямого доступа к WebGL-контексту, но допускает расширение через пользовательские слои (CustomLayerInterface), где разработчик управляет жизненным циклом WebGL объектов.

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

Состояние карты включает:

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

API различает мгновенные и анимированные изменения. Например, методы setCenter и setZoom изменяют состояние без анимации, тогда как flyTo и easeTo используют интерполяцию.

Различие API заключается в том, что все трансформации описываются как непрерывные функции, а не дискретные шаги, что позволяет синхронизировать визуальные переходы с рендером.

Расширяемость и интеграция

API предоставляет несколько уровней расширения:

• пользовательские контролы (IControl)
• пользовательские слои (CustomLayerInterface)
• взаимодействие с внешними библиотеками визуализации

Mapbox строит архитектуру API таким образом, чтобы ядро оставалось минимальным, а расширения подключались поверх него без модификации внутреннего рендера.

Различие API в этом контексте проявляется в строгом контракте между ядром и расширениями: любые пользовательские компоненты должны соответствовать жизненному циклу карты и не нарушать WebGL pipeline.

Управление ресурсами и производительностью

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

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

Различие API заключается в том, что разработчик не управляет памятью напрямую, но может влиять на производительность через параметры источников и слоёв, такие как maxzoom, minzoom, tileSize, buffer.

Безопасность и токены доступа

Доступ к API требует использования access token, который передаётся при инициализации карты. Это фундаментальное отличие от открытых библиотек рендеринга карт.

Модель безопасности включает:

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

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