Polyline: создание линий

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

Полилиния создаётся через конструктор L.polyline, которому передаётся массив координат вида [lat, lng]. Каждая пара представляет одну вершину линии.

const latlngs = [
  [55.751244, 37.618423],
  [55.755826, 37.617300],
  [55.760000, 37.620000]
];

const polyline = L.polyline(latlngs);
polyline.addTo(map);

Координаты должны быть строго в формате широта–долгота. Порядок имеет значение: линия строится последовательно, соединяя точки в том порядке, в котором они заданы.

Основные параметры конфигурации

Полилинии поддерживают набор опций, определяющих внешний вид и поведение линии.

const polyline = L.polyline(latlngs, {
  color: 'blue',
  weight: 4,
  opacity: 0.7,
  smoothFactor: 1.0
}).addTo(map);

Ключевые параметры:

  • color — цвет линии (CSS-значение)
  • weight — толщина линии в пикселях
  • opacity — прозрачность от 0 до 1
  • stroke — включение/отключение обводки
  • lineCap — форма концов линии (round, butt, square)
  • lineJoin — тип соединения сегментов (round, miter, bevel)
  • dashArray — пунктирная линия ('10, 5')
  • smoothFactor — упрощение геометрии при масштабировании
  • noClip — отключение обрезки по границам карты

Пример пунктирной линии:

const dashed = L.polyline(latlngs, {
  color: 'red',
  weight: 3,
  dashArray: '8, 6'
}).addTo(map);

Добавление и удаление с карты

Полилиния является слоем, поэтому добавляется и удаляется стандартными методами слоёв.

polyline.addTo(map);
map.removeLayer(polyline);

Альтернативный вариант:

polyline.remove();

Работа с координатами

После создания линии доступ к её геометрии осуществляется через методы:

const points = polyline.getLatLngs();

Изменение набора точек:

polyline.setLatLngs([
  [55.75, 37.61],
  [55.76, 37.62]
]);

Добавление новой точки требует обновления массива:

const pts = polyline.getLatLngs();
pts.push([55.77, 37.63]);
polyline.setLatLngs(pts);

Получение границ линии

Для автоматического масштабирования карты под полилинию используется bounding box:

const bounds = polyline.getBounds();
map.fitBounds(bounds);

Метод getBounds() возвращает объект прямоугольной области, охватывающей все точки линии.

Стилизация после создания

Внешний вид полилинии можно менять динамически через setStyle.

polyline.setStyle({
  color: 'green',
  weight: 6,
  opacity: 0.9
});

Изменение стиля не требует пересоздания слоя.

События полилинии

Полилинии поддерживают стандартные события взаимодействия:

polyline.on('click', (e) => {
  console.log('Клик по линии', e.latlng);
});

polyline.on('mouseover', () => {
  polyline.setStyle({ color: 'orange' });
});

polyline.on('mouseout', () => {
  polyline.setStyle({ color: 'blue' });
});

Основные события:

  • click — клик по линии
  • mouseover — наведение курсора
  • mouseout — уход курсора
  • contextmenu — контекстное меню
  • add/remove — добавление и удаление слоя

Привязка всплывающих окон и подсказок

Полилиния может содержать интерактивные элементы:

polyline.bindPopup('Маршрут A → B → C');

Также поддерживаются tooltip:

polyline.bindTooltip('Маршрут');

Tooltips отображаются при наведении, popup — по клику.

Геометрия и производительность

При большом количестве точек используется параметр smoothFactor, который влияет на упрощение линии при масштабировании:

L.polyline(latlngs, {
  smoothFactor: 0.5
});

Чем меньше значение, тем более детализированной остаётся линия, но выше нагрузка на рендеринг.

Отключение клиппинга

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

L.polyline(latlngs, {
  noClip: true
});

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

Интеграция с GeoJSON

Полилинии часто создаются через GeoJSON-слой:

L.geoJSON(geojsonData, {
  style: function (feature) {
    return {
      color: 'purple',
      weight: 4
    };
  }
}).addTo(map);

GeoJSON-тип LineString автоматически преобразуется в полилинию, а MultiLineString — в набор линий.

Пример структуры GeoJSON:

const geojsonData = {
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [37.618423, 55.751244],
      [37.617300, 55.755826]
    ]
  }
};

Важно: GeoJSON использует порядок [lng, lat], в отличие от Leaflet.

Манипуляции в реальном времени

Полилинии можно использовать для динамического отображения маршрутов, например при трекинге движения:

setInterval(() => {
  const pts = polyline.getLatLngs();
  pts.push([newLat, newLng]);
  polyline.setLatLngs(pts);
}, 1000);

Для плавного обновления рекомендуется ограничивать количество точек или применять упрощение геометрии.

Управление порядком отображения

Полилинии можно поднимать выше или опускать ниже относительно других слоёв:

polyline.bringToFront();
polyline.bringToBack();

Это важно при наложении нескольких маршрутов или контуров.

Комбинирование с другими слоями

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

L.marker([55.75, 37.61]).addTo(map);
L.polyline(latlngs).addTo(map);
L.polygon(polygonLatLngs).addTo(map);

Так создаются комплексные визуальные представления маршрутов и зон.

Типичные ошибки при работе

  • Перепутан порядок координат (lat/lng вместо lng/lat при GeoJSON)
  • Использование строк вместо числовых координат
  • Передача пустого массива точек
  • Попытка модифицировать getLatLngs() без повторного setLatLngs

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

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

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

Использование для маршрутов

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

const route = L.polyline(routeCoords, {
  color: '#2a9d8f',
  weight: 5
}).addTo(map);

Маршрут может обновляться в реальном времени, дополняясь новыми точками по мере движения объекта.

Оглавление