Класс Popup в Leaflet представляет собой механизм отображения всплывающих информационных окон на карте. Popup используется для показа контекстной информации, привязанной к координате, маркеру или любому другому слою. Он может открываться как в ответ на событие пользователя, так и программно, и является одним из базовых интерактивных элементов библиотеки.
Popup реализован как отдельный слой (Layer), наследующий базовую
функциональность от L.Layer, что позволяет ему
интегрироваться в систему управления слоями карты, добавляться и
удаляться динамически, а также взаимодействовать с событиями карты.
Popup может быть создан напрямую через конструктор
L.popup:
const popup = L.popup();При создании допускается передача опций, определяющих поведение и внешний вид:
const popup = L.popup({
maxWidth: 300,
minWidth: 50,
autoPan: true,
closeButton: true,
autoClose: true,
className: 'custom-popup'
});Основные параметры:
Popup может также создаваться неявно через методы других объектов, например маркеров.
Popup можно открыть напрямую на карте:
popup
.setLatLng([55.751244, 37.618423])
.setContent('Москва')
.openOn(map);Метод openOn(map) добавляет popup на карту и
автоматически удаляет ранее открытый popup, если включена опция
autoClose.
Альтернативный способ — использование addTo(map):
popup
.setLatLng([55.751244, 37.618423])
.setContent('Географическая точка')
.addTo(map);Разница заключается в том, что openOn управляет
единственным активным popup, тогда как addTo ведёт себя как
обычный слой.
Наиболее распространённый сценарий — привязка popup к маркеру:
const marker = L.marker([55.751244, 37.618423]).addTo(map);
marker.bindPopup('Информация о точке');Метод bindPopup связывает popup с объектом слоя. При
клике на маркер popup открывается автоматически.
Можно передавать HTML:
marker.bindPopup(`
<strong>Объект</strong><br>
Описание точки на карте
`);Также допустима передача функции:
marker.bindPopup(() => {
return 'Динамически сформированный текст';
});Метод bindPopup поддерживает вторым аргументом
опции:
marker.bindPopup('Текст', {
maxWidth: 200,
className: 'info-popup'
});Эти параметры переопределяют глобальные настройки popup для конкретного объекта.
Popup можно открыть вручную:
marker.openPopup();Или через карту:
map.openPopup(popup);Также доступен вариант с координатами:
map.openPopup('Сообщение', [55.75, 37.61]);Этот способ удобен для быстрых уведомлений без предварительного создания объекта popup.
Popup поддерживает динамическое изменение содержимого через
setContent:
popup.setContent('Новое содержимое');Содержимое может быть:
Пример с DOM:
const div = document.createElement('div');
div.innerHTML = '<h3>Заголовок</h3><p>Текст</p>';
popup.setContent(div);Popup привязан к координате через setLatLng:
popup.setLatLng([55.76, 37.64]);При изменении позиции popup автоматически перерисовывается и, при
включённом autoPan, карта смещается для сохранения
видимости окна.
Popup поддерживает набор событий жизненного цикла:
Пример обработки:
map.on('popupopen', (e) => {
console.log('Popup открыт:', e.popup);
});События позволяют синхронизировать popup с внешними интерфейсами, загружать данные или изменять состояние приложения.
Popup рендерится как DOM-элемент с классом
leaflet-popup. Основная структура:
Через className можно добавлять пользовательские
стили:
const popup = L.popup({
className: 'dark-popup'
});CSS:
.dark-popup .leaflet-popup-content-wrapper {
background: #222;
color: #fff;
}Изменение оформления позволяет адаптировать popup под дизайн интерфейса.
Опция autoPan управляет тем, будет ли карта
автоматически смещаться при открытии popup, чтобы он полностью помещался
в видимой области.
При включённом режиме Leaflet вычисляет смещение и вызывает плавную анимацию сдвига карты.
L.popup({
autoPan: true,
autoPanPadding: [20, 20]
});autoPanPadding задаёт отступы от краёв карты.
Leaflet допускает наличие нескольких popup, однако поведение зависит от способа открытия:
openOn(map) — гарантирует только один активный
popupaddTo(map) — позволяет множественное отображениеПри работе с несколькими окнами важно учитывать перекрытие и z-index, который управляется автоматически.
Popup часто сравнивается с tooltip, однако имеет более тяжёлую структуру и предназначен для расширенного контента. Tooltip используется для кратких подсказок, popup — для структурированной информации.
Popup может содержать формы, изображения, списки и интерактивные элементы, тогда как tooltip ограничен текстовым представлением.
Popup поддерживает полноценный DOM, включая обработчики событий:
marker.bindPopup(`
<button id="btn">Нажать</button>
`);
marker.on('popupopen', () => {
document.getElementById('btn').addEventListener('click', () => {
console.log('Клик внутри popup');
});
});Такой подход требует аккуратного управления событиями, поскольку popup пересоздаётся при каждом открытии.
Popup может быть удалён через:
map.removeLayer(popup);или через закрытие:
map.closePopup();При привязке к объекту:
marker.unbindPopup();После отвязки popup больше не открывается при взаимодействии с маркером.
Динамическая генерация содержимого часто применяется при работе с API:
marker.bindPopup((layer) => {
const latlng = layer.getLatLng();
return `Координаты: ${latlng.lat}, ${latlng.lng}`;
});Функция вызывается в момент открытия, что позволяет подставлять актуальные данные.
Popup автоматически пересчитывает своё положение при изменении масштаба или перемещении карты. Это обеспечивается привязкой к географической точке, а не к экранным координатам.
При сильных изменениях масштаба Leaflet пересчитывает позиционирование стрелки popup для корректного визуального указания на объект.
Popup имеет ряд архитектурных особенностей:
При большом количестве popup рекомендуется контролировать их жизненный цикл вручную для предотвращения перегрузки DOM.
Внутренне popup проходит стадии:
Эта модель обеспечивает синхронность отображения с географическими данными и событиями интерфейса карты.