Skip to content

Слои ​

Общее для всех слоёв: addTo(map), remove(), on/off/once там, где у слоя есть события.

TileLayer ✅ ​

ts
new TileLayer({ url, maxNativeZoom?, retina?, maxParallel? })

Растровые XYZ-тайлы. url — шаблон с {z}, {x}, {y} и необязательным {r} (заменяется на @2x для ретины). Выше maxNativeZoom тайлы растягиваются на клиенте. Уже загруженная подложка не исчезает, пока не загрузится новый уровень зума; ошибки загрузки повторяются 3 раза.

ts
map.add(new TileLayer({ url: 'https://tiles.evamaps.ru/v1/light/{z}/{x}/{y}{r}.png' }));

Marker (метка) ✅ ​

ts
new Marker(lngLat, { appearance?, color?, label?, hint?, draggable?, zIndexOffset?, riseOnHover? })
Статус
setLngLat / getLngLat, setColor / getColor✅
setPopup(popup) / getPopup() — балун по клику✅
appearance: 'pin' | 'dot' — капля (по умолчанию, цвет #ff6a2b) или кружок✅
label / setLabel(text) — короткая постоянная подпись рядом с меткой (≤ 24 символа, только текст)✅
hint / setHint(text) — подсказка при наведении (≤ 120 символов, только текст)✅
draggable, события dragstart / drag / dragend✅
событие click✅
zIndexOffset (по умолчанию 0) / setZIndexOffset(offset) / getZIndexOffset() — сдвиг метки в стопке относительно других меток✅
riseOnHover (по умолчанию false) — временно поднимать метку поверх остальных при наведении или фокусе✅
ts
const marker = new Marker([37.6173, 55.7558], { color: '#e53935', draggable: true })
  .setPopup(new Popup().setText('Наш офис'))
  .addTo(map);

marker.on('dragend', () => console.log(marker.getLngLat()));
ts
new Popup({ autoPan?, autoPanPadding? })
Статус
setText(text) — только текст, без HTML✅
setLink(href) — ссылка, только http(s)✅
setContent(node: Node) — доверенная разметка разработчика, DOM-узлом✅
openBalloon() / close() / toggle()✅
autoPan (по умолчанию true) / autoPanPadding (по умолчанию [20, 20] px) — если балун не помещается в видимую область, карта плавно подвигается с этим отступом✅

setText не принимает HTML-строку намеренно — это защита от XSS, когда текст метки приходит из пользовательских данных (адрес, имя клиента). Если разметка нужна и вы доверяете её источнику (например, собираете сами на сервере), передайте готовый DOM-узел в setContent(node).

ts
popup.setText('Обычный текст, безопасно даже из пользовательского ввода');

const node = document.createElement('div');
node.textContent = 'Своя разметка — только когда вы сами её строите';
popup.setContent(node);

Polyline, Polygon, Circle ✅ ​

ts
new Polyline(lngLats, { color, weight, opacity })
new Polygon(rings, { color, weight, fillColor, fillOpacity })
new Circle(center, radiusMeters, { color, weight, fillColor, fillOpacity })

Рисуются в SVG; метки на карте всегда отображаются поверх фигур. Корректно работают через антимеридиан (180°, например у Чукотки) — не рисуются «через весь мир».

GeoJSONLayer ✅ ​

ts
new GeoJSONLayer(geojson, { style?, pointToMarker? })

Преобразует geometry-типы GeoJSON в слои карты: Point → Marker, LineString → Polyline, Polygon → Polygon, а также Multi* и GeometryCollection.

ts
const layer = new GeoJSONLayer(geojson, {
  style: (feature) => ({ color: feature.properties.color ?? '#2f6fed' }),
}).addTo(map);

ClusterLayer ✅ ​

ts
new ClusterLayer(points, { radius?, maxClusterZoom?, color?, pointStyle?, clusterStyle?, spiderfy? })

Группирует близкие точки в кластеры, клик по кластеру приближает карту. Событие pointClick срабатывает по клику на отдельную (некластеризованную) точку. Работает и через 180° долготы — объекты по обе стороны от антимеридиана (например, у Чукотки) группируются вместе, если рядом географически. На экран выводится только видимое, поэтому 10 000 точек и больше не тормозят.

ОпцияПо умолчанию
radius60Размер ячейки группировки в пикселях
maxClusterZoom18С этого зума точки показываются по отдельности
color#1a73e8Цвет кластеров и точек
pointStyle(index)—{ color?, icon? } — вид точки по её индексу в массиве. icon как у метки: { url, size, anchor? }
clusterStyle(indices)—{ color?, size?, className? } — вид кластера по его точкам
spiderfytrueКластер, который дальше не приблизить, по клику раскладывается вокруг центра
ts
const nodes = [/* { lngLat: [37.6, 55.75], online: true, name: '…' }, … */];
const cluster = new ClusterLayer(nodes.map((n) => n.lngLat), {
  pointStyle: (i) => ({ color: nodes[i].online ? '#2b8a3e' : '#777' }),
  clusterStyle: (ids) => ({
    color: ids.some((i) => nodes[i].online) ? '#2b8a3e' : '#777',
    className: ids.length > 50 ? 'big' : undefined,
  }),
}).addTo(map);

cluster.on('pointClick', ({ index, lngLat }) => {
  new Popup().setLngLat(lngLat).setText(nodes[index].name).openOn(map);
});

Методы: setData(points), refresh() (перечитать pointStyle и clusterStyle, например после смены статусов), getPoints(), unspiderfy().

PointsLayer ✅ ​

ts
new PointsLayer(points, { radius?, color?, opacity?, pointStyle?, interactive? })

Тысячи точек одной картинкой: зоны покрытия, треки, показания датчиков. Аналог L.circleMarker с canvas-рендерером Leaflet. Радиус — в пикселях экрана, от зума не зависит.

ОпцияПо умолчанию
radius4Радиус точки в пикселях
color#1a73e8Цвет, можно rgba(…)
opacity1Прозрачность всего слоя
pointStyle(index)—{ color?, radius? } для отдельной точки
interactivefalseКлик по точке шлёт pointClick { lngLat, index }
ts
const colors = { strong: 'rgb(0,200,80)', weak: 'rgb(255,120,0)' };
new PointsLayer(points.map((p) => p.lngLat), {
  radius: 4,
  opacity: 0.45,
  pointStyle: (i) => ({ color: colors[points[i].status] }),
}).addTo(map);

Точки одного цвета и радиуса рисуются вместе, поэтому полупрозрачные точки одного цвета не темнеют там, где накрывают друг друга. Методы: setData(points), refresh(), setOpacity(opacity), getPoints(), pointAt(point) — индекс точки под пикселем карты или -1.

Показать и спрятать слой ​

layer.addTo(map) и layer.remove() можно вызывать сколько угодно раз: подписки on(…) сохраняются. Проверить, на карте ли слой, — map.hasLayer(layer).

Нашли ошибку в документации? Напишите нам