MapLibre GL JS изначально проектировалась как форк Mapbox GL JS до версии 1.x, что определило ключевую особенность её API — высокий уровень совместимости с оригинальной спецификацией Mapbox GL JS. Эта совместимость стала фундаментом для миграции существующих проектов и одновременно источником ограничений, связанных с сохранением обратной совместимости и постепенной эволюцией архитектуры.
Основная идея совместимости заключается в том, что MapLibre GL JS реализует тот же публичный API-интерфейс, что и Mapbox GL JS v1.x:
Mapsources и layersload, click,
mousemove и др.)Эта модель позволяет рассматривать MapLibre GL JS как замену «drop-in replacement» в большинстве проектов, где ранее использовался Mapbox GL JS до изменения лицензии.
Ключевая особенность архитектуры — разделение между:
Такое разделение позволило сохранить стабильность интерфейсов при изменениях внутренней реализации.
Одним из самых устойчивых элементов совместимости является поддержка спецификации стилей.
Стиль карты в MapLibre GL JS представляет собой JSON-объект следующей структуры:
{
"version": 8,
"sources": { ... },
"layers": [ ... ],
"glyphs": "...",
"sprite": "..."
}Поддерживаемые элементы:
vector, raster,
geojson, image, video)fill, line, symbol,
circle, heatmap, fill-extrusion,
raster, hillshade)==, !=, >,
<, in, all,
any)Совместимость на уровне стиля означает, что большинство карт, созданных под Mapbox, могут быть загружены без изменений:
const map = new maplibregl.Map({
container: 'map',
style: 'https://example.com/style.json'
});Однако существуют нюансы:
Основной класс Map является центральной точкой API и
сохраняет структуру:
const map = new maplibregl.Map({
container: 'map',
style: 'style.json',
center: [0, 0],
zoom: 2
});Поддерживаются ключевые параметры:
containerstylecenterzoombearingpitchhashinteractiveattributionControlИзменения по сравнению с Mapbox GL JS v1:
Система источников данных является одним из наиболее стабильных компонентов API.
Поддерживаемые типы:
map.addSource('tiles', {
type: 'vector',
tiles: ['https://example.com/{z}/{x}/{y}.pbf']
});map.addSource('points', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: []
}
});map.addSource('raster', {
type: 'raster',
tiles: ['https://example.com/tiles/{z}/{x}/{y}.png'],
tileSize: 256
});Особенности совместимости:
setData() для GeoJSON полностью совместимsetData работает без
измененийСлои остаются ключевой частью API и полностью соответствуют модели Mapbox GL JS v1.
Добавление слоя:
map.addLayer({
id: 'cities',
type: 'circle',
source: 'points',
paint: {
'circle-radius': 6,
'circle-color': '#ff0000'
}
});Типы слоёв:
filllinecirclesymbolrasterheatmapfill-extrusionhillshadeСовместимость поведения:
minzoom и maxzoom работают идентичноОтличия:
Событийная система MapLibre GL JS сохраняет структуру событий Mapbox:
map.on('load', () => {
console.log('map loaded');
});
map.on('click', 'cities', (e) => {
console.log(e.features);
});Поддерживаемые события:
load, render,
idleclick, mousemove,
mouseenter, mouseleavemove, zoom,
rotate, pitchОсобенности:
Expression API — одна из наиболее сложных частей совместимости.
Пример:
'circle-color': [
'case',
['>', ['get', 'population'], 1000000],
'#ff0000',
'#0000ff'
]Поддерживаются:
get)interpolate)case)to-number,
to-string)Особенности совместимости:
API камеры:
map.flyTo({
center: [10, 10],
zoom: 5,
speed: 1.2
});Поддерживаемые методы:
jumpToeaseToflyTofitBoundsСовместимость:
Встроенные контролы:
NavigationControlScaleControlAttributionControlFullscreenControlПример:
map.addControl(new maplibregl.NavigationControl());Совместимость:
IControlЭкосистема Mapbox GL JS имела множество плагинов, которые частично перешли в MapLibre.
Основные категории:
Совместимость зависит от:
Проблемные зоны:
internal API Mapbox GL JSИнициализация MapLibre GL JS чаще требует более явного контроля над ресурсами:
Пример проблемного кейса:
Внутренний рендеринг основан на WebGL, что обеспечивает:
Отличия:
Типичная миграция с Mapbox GL JS:
замена пакета:
mapbox-gl → maplibre-glудаление access token:
// больше не требуется
mapboxgl.accessToken = '...';Особое внимание:
Несмотря на высокую степень совместимости, существуют системные ограничения:
Эти ограничения формируют естественную границу эволюции API, где MapLibre GL JS развивается независимо, сохраняя при этом стабильную базовую модель Mapbox GL JS v1.x.