Класс Tooltip

Класс Tooltip в Leaflet предназначен для отображения всплывающих подсказок, привязанных к карте или её слоям. Подсказка представляет собой компактный HTML-блок, который появляется при взаимодействии с объектом карты или при наведении курсора. В отличие от Popup, Tooltip обычно менее навязчив и используется для кратких текстовых обозначений.

Tooltip в Leaflet является расширением базового класса DivOverlay. Это означает, что подсказка:

  • рендерится как DOM-элемент;
  • может содержать произвольный HTML;
  • позиционируется относительно географической точки или слоя;
  • управляется через стандартные методы жизненного цикла overlay-элементов.

Подсказки не создаются напрямую через new L.Tooltip(), хотя это возможно, но чаще используются через методы bindTooltip у слоёв.

Создание Tooltip через bindTooltip

Основной способ работы с подсказками — привязка к объекту слоя.

marker.bindTooltip("Простая подсказка");

Такой вызов автоматически создаёт экземпляр Tooltip и связывает его с маркером. Подсказка будет отображаться при наведении курсора.

Прямое создание Tooltip

Низкоуровневое создание позволяет более тонко управлять поведением:

const tooltip = L.tooltip({
    direction: "top",
    offset: [0, -10],
    opacity: 0.9
})
.setContent("Динамическая подсказка");

Далее подсказка может быть добавлена к карте:

tooltip.setLatLng([51.505, -0.09]).addTo(map);

Основные опции Tooltip

direction

Определяет положение подсказки относительно точки привязки.

Возможные значения:

  • top
  • bottom
  • left
  • right
  • center
  • auto

При auto Leaflet автоматически выбирает направление, минимизируя выход за границы карты.

offset

Смещение подсказки относительно точки привязки:

offset: [10, -20]

Первое значение — горизонтальное смещение, второе — вертикальное.

opacity

Контролирует прозрачность:

opacity: 0.7

permanent

Если установлено в true, подсказка отображается постоянно:

marker.bindTooltip("Всегда видимая подсказка", {
    permanent: true
});

sticky

Опция sticky делает подсказку “следующей” за курсором:

marker.bindTooltip("Следует за курсором", {
    sticky: true
});

interactive

Позволяет взаимодействовать с содержимым Tooltip (клики, выделение текста):

interactive: true

Без этой опции все события проходят сквозь подсказку на карту.

className

Позволяет задавать CSS-класс для кастомизации:

className: "custom-tooltip"

Методы класса Tooltip

setContent

Изменение содержимого:

tooltip.setContent("Новый текст");

Поддерживается HTML:

tooltip.setContent("<b>Жирный текст</b>");

setLatLng

Обновление позиции:

tooltip.setLatLng([51.51, -0.1]);

getContent

Получение текущего содержимого:

const content = tooltip.getContent();

getLatLng

Возвращает координаты привязки:

const latlng = tooltip.getLatLng();

addTo / remove

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

tooltip.addTo(map);
tooltip.remove();

Привязка Tooltip к слоям

Tooltip может быть связан с любым пространственным объектом:

Маркеры

L.marker([51.5, -0.09])
    .bindTooltip("Маркер в Лондоне")
    .addTo(map);

Полилинии

L.polyline([
    [51.5, -0.1],
    [51.51, -0.12]
]).bindTooltip("Маршрут");

Полигоны

L.polygon([
    [51.509, -0.08],
    [51.503, -0.06],
    [51.51, -0.047]
]).bindTooltip("Область");

Поведение Tooltip при событиях

По умолчанию Tooltip открывается при mouseover и закрывается при mouseout. Поведение можно контролировать:

marker.bindTooltip("Подсказка", {
    permanent: false,
    direction: "top"
});

Можно также вручную управлять открытием:

marker.openTooltip();
marker.closeTooltip();

События Tooltip

Tooltip поддерживает стандартные события жизненного цикла:

  • tooltipopen
  • tooltipclose

Пример:

marker.on("tooltipopen", function (e) {
    console.log("Tooltip открыт");
});

Стилизация Tooltip

DOM-структура Tooltip содержит корневой элемент с классом:

.leaflet-tooltip

Направление добавляет модификаторы:

  • leaflet-tooltip-top
  • leaflet-tooltip-bottom
  • leaflet-tooltip-left
  • leaflet-tooltip-right

Пример кастомизации:

.custom-tooltip {
    background: #222;
    color: #fff;
    border-radius: 4px;
    padding: 6px 10px;
    font-size: 13px;
    box-shadow: 0 2px 6px rgba(0,0,0,0.3);
}

Динамические Tooltip

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

marker.bindTooltip(() => {
    return "Время: " + new Date().toLocaleTimeString();
});

Или обновление по событию:

marker.on("move", function (e) {
    marker.setTooltipContent("Lat: " + e.latlng.lat);
});

Взаимодействие с Popup

Tooltip и Popup часто используются совместно, но имеют различия:

  • Tooltip — лёгкий, быстрый, часто постоянный или hover-based;
  • Popup — полноценное окно с управлением открытием/закрытием.

Комбинация:

marker.bindTooltip("Кратко").bindPopup("Подробно");

Программное управление привязкой

Tooltip можно перепривязывать:

marker.unbindTooltip();
marker.bindTooltip("Новое содержимое");

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

Tooltip учитывает:

  • границы карты;
  • масштаб;
  • положение слоя;
  • размер контента.

При выходе за границы карты применяется автоматическая корректировка позиции, особенно при direction: "auto".

HTML-контент и безопасность

Tooltip поддерживает HTML, но не выполняет sanitization автоматически:

marker.bindTooltip("<img src='x' />");

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

Производительность

При большом количестве Tooltip на карте:

  • предпочтительнее использовать bindTooltip вместо ручного создания;
  • избегать interactive: true без необходимости;
  • минимизировать сложный HTML внутри подсказок;
  • использовать sticky только для ограниченного числа объектов.

Внутреннее устройство

Tooltip реализует механизм overlay:

  • создаётся DOM-элемент через L.DomUtil.create;
  • позиционируется через трансформации;
  • пересчитывается при событиях zoom и move;
  • добавляется в pane tooltipPane.

Это позволяет интегрировать его в систему слоёв Leaflet без отдельного рендера.

Оглавление