Создание и позиционирование оверлеев

Оверлеи в OpenLayers представляют собой механизм наложения произвольных HTML-элементов поверх карты с привязкой к географическим координатам. В отличие от слоёв, работающих с тайлами или векторной графикой внутри canvas/SVG, оверлеи оперируют DOM-элементами и используются для реализации всплывающих окон, тултипов, карточек объектов, пользовательских маркеров и интерактивных панелей.

Оверлей в OpenLayers связывает DOM-элемент с координатой карты и управляет его позиционированием при изменении масштаба, центра или проекции.

Ключевые свойства оверлея:

  • element — HTML-узел, отображаемый поверх карты
  • position — координаты в системе карты (обычно EPSG:3857 или EPSG:4326 с трансформацией)
  • positioning — правило привязки элемента относительно координаты
  • offset — смещение в пикселях
  • stopEvent — блокировка событий карты под оверлеем
  • autoPan — автоматическое смещение карты при выходе оверлея за границы
  • autoPanAnimation — параметры анимации автопанорамирования

Оверлей создаётся как объект, который затем регистрируется в экземпляре карты.

Создание DOM-элемента для оверлея

DOM-структура оверлея формируется вручную, поскольку OpenLayers не навязывает шаблон отображения.

const container = document.createElement('div');
container.className = 'ol-popup';

const content = document.createElement('div');
content.className = 'ol-popup-content';
container.appendChild(content);

const closer = document.createElement('a');
closer.className = 'ol-popup-closer';
closer.href = '#';
container.appendChild(closer);

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

Инициализация оверлея

Создание оверлея выполняется через конструктор Overlay.

import Overlay from 'ol/Overlay.js';

const overlay = new Overlay({
  element: container,
  positioning: 'bottom-center',
  stopEvent: true,
  offset: [0, -10],
  autoPan: true,
  autoPanAnimation: {
    duration: 250
  }
});

После создания объект не отображается до привязки к карте.

Привязка оверлея к карте

Оверлей добавляется в контекст карты как отдельная сущность.

map.addOverlay(overlay);

С этого момента OpenLayers начинает управлять его положением при каждом изменении вида карты.

Установка позиции оверлея

Географическая привязка выполняется через метод setPosition.

overlay.setPosition([lon, lat]);

Координаты должны соответствовать проекции карты. При использовании стандартной Web Mercator часто требуется преобразование:

import { fromLonLat } from 'ol/proj.js';

overlay.setPosition(fromLonLat([37.6173, 55.7558]));

Удаление привязки выполняется передачей undefined:

overlay.setPosition(undefined);

Система позиционирования

Параметр positioning определяет, как HTML-элемент располагается относительно координаты.

Основные режимы:

  • bottom-left
  • bottom-center
  • bottom-right
  • center-left
  • center-center
  • center-right
  • top-left
  • top-center
  • top-right

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

Пример:

positioning: 'top-center'

В этом режиме нижняя часть оверлея «смотрит» на координату, что часто используется для маркеров с всплывающими подсказками.

Смещение оверлея

Параметр offset задаёт пиксельное смещение от точки привязки.

offset: [15, -30]

Первое значение — горизонтальное смещение, второе — вертикальное. Это позволяет компенсировать размеры иконок или визуально отделять всплывающий блок от точки на карте.

Поведение событий (stopEvent)

DOM-элементы оверлея могут перехватывать события мыши. Параметр stopEvent управляет этим поведением.

stopEvent: true

При значении true события кликов и прокрутки внутри оверлея не передаются карте, что предотвращает случайное перемещение карты при взаимодействии с интерфейсом оверлея.

При false взаимодействие с картой сохраняется даже при кликах по элементу.

Автопанорамирование карты

Оверлей может выходить за пределы видимой области. Для предотвращения скрытия содержимого используется autoPan.

autoPan: true

В этом режиме карта автоматически смещается, чтобы оверлей оставался видимым.

Расширенная конфигурация:

autoPanAnimation: {
  duration: 300
}

Движение карты становится плавным, что важно при появлении всплывающих окон в плотных интерфейсах.

Динамическое обновление содержимого

Оверлей обычно используется для отображения информации об объектах карты. Содержимое DOM обновляется вручную:

content.innerHTML = `
  <strong>Объект</strong><br>
  Координаты: ${coord}
`;
overlay.setPosition(coord);

Обновление не требует пересоздания оверлея, что снижает нагрузку на DOM.

Множественные оверлеи

Карты OpenLayers поддерживают любое количество оверлеев одновременно.

map.addOverlay(overlay1);
map.addOverlay(overlay2);
map.addOverlay(overlay3);

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

Управление жизненным циклом

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

map.removeOverlay(overlay);

После удаления DOM-элемент остаётся в памяти и может быть повторно использован или уничтожен вручную.

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

Оверлеи часто используются вместе с событиями карты:

map.on('click', function (event) {
  const coord = event.coordinate;
  overlay.setPosition(coord);
});

Это позволяет реализовать интерактивные всплывающие окна при клике по карте.

Работа с пользовательскими компонентами

DOM-элемент оверлея может включать любые интерфейсные компоненты:

  • формы ввода
  • кнопки управления
  • графики
  • списки объектов
  • медиаконтент

Структура не ограничивается OpenLayers и полностью контролируется разработчиком.

Производительность и оптимизация

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

Типичные приёмы оптимизации:

  • переиспользование DOM-элементов вместо создания новых
  • ограничение количества одновременно видимых оверлеев
  • отключение autoPan при массовых обновлениях
  • минимизация перерисовок innerHTML
  • использование CSS-трансформаций вместо изменения геометрии DOM

Поведение при изменении масштаба и центра

При каждом изменении вида карты OpenLayers пересчитывает экранные координаты оверлея. Преобразование координат выполняется через внутренние функции проекции, после чего DOM-элемент позиционируется через CSS transform.

Это обеспечивает:

  • плавное перемещение без полного пересоздания DOM
  • корректную работу при зуме
  • синхронизацию с векторными и тайловыми слоями

Особенности взаимодействия с проекциями

Если карта использует нестандартную систему координат, позиция оверлея должна быть приведена к проекции карты:

import { transform } from 'ol/proj.js';

overlay.setPosition(
  transform([lon, lat], 'EPSG:4326', 'EPSG:3857')
);

Ошибки в преобразовании координат приводят к смещению оверлея вне ожидаемой области отображения.

Использование оверлеев как маркеров

Хотя для маркеров существуют векторные слои, DOM-оверлеи часто применяются для сложных визуальных маркеров, требующих интерактивности или нестандартной разметки.

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

  • иконка объекта
  • подпись
  • индикаторы состояния
  • интерактивные кнопки

Такой подход позволяет реализовать сложные интерфейсы без работы с canvas или SVG-стилями.

Оглавление