Overlay типы

Overlay (наложение) — это объект, отображаемый поверх карты. Overlay позволяет визуально расширять базовую карту дополнительными данными, графикой, пользовательскими элементами интерфейса и географическими объектами.

В Google Maps JavaScript API существует несколько типов наложений:

  • Marker (маркеры)
  • InfoWindow (информационные окна)
  • Polyline (линии)
  • Polygon (полигоны)
  • Rectangle (прямоугольники)
  • Circle (окружности)
  • GroundOverlay (растровые изображения)
  • Custom Overlay через OverlayView
  • Data Layer (слой данных)

Все эти элементы располагаются поверх карты и участвуют в её визуальном представлении.

Архитектура Overlay

Большинство overlay-объектов наследуют общую концепцию:

  1. Создание объекта.
  2. Настройка параметров.
  3. Привязка к карте.
  4. Управление отображением.
  5. Удаление с карты.

Общий шаблон выглядит следующим образом:

const overlay = new google.maps.SomeOverlay({
    // параметры
});

overlay.setMap(map);

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

overlay.setMap(null);

После вызова объект остаётся в памяти, но перестаёт отображаться.

Marker как Overlay

Маркер является самым распространённым типом наложения.

const marker = new google.maps.Marker({
    position: {
        lat: 55.7558,
        lng: 37.6176
    },
    map: map,
    title: "Москва"
});

Маркер отображается поверх всех базовых слоёв карты.

Скрытие маркера

marker.setMap(null);

Повторное отображение

marker.setMap(map);

Polyline

Polyline представляет последовательность соединённых сегментов.

const path = [
    { lat: 55.75, lng: 37.61 },
    { lat: 55.76, lng: 37.62 },
    { lat: 55.77, lng: 37.64 }
];

const polyline = new google.maps.Polyline({
    path: path,
    strokeColor: "#FF0000",
    strokeOpacity: 1,
    strokeWeight: 3
});

polyline.setMap(map);

Основные параметры

Параметр Назначение
path Массив координат
strokeColor Цвет линии
strokeWeight Толщина
strokeOpacity Прозрачность
geodesic Геодезическая линия

Пример геодезической линии:

const polyline = new google.maps.Polyline({
    path,
    geodesic: true
});

В этом случае линия учитывает кривизну Земли.

Polygon

Polygon используется для отображения замкнутых областей.

const polygon = new google.maps.Polygon({
    paths: [
        { lat: 55.76, lng: 37.60 },
        { lat: 55.78, lng: 37.65 },
        { lat: 55.73, lng: 37.67 }
    ],
    strokeColor: "#0000FF",
    fillColor: "#0000FF",
    fillOpacity: 0.3
});

polygon.setMap(map);

Настройки полигона

const polygon = new google.maps.Polygon({
    paths: coordinates,
    strokeColor: "#0000FF",
    strokeWeight: 2,
    strokeOpacity: 0.8,
    fillColor: "#00AAFF",
    fillOpacity: 0.4
});

Polygon с отверстиями

Google Maps поддерживает внутренние вырезы.

const polygon = new google.maps.Polygon({
    paths: [
        outerPath,
        innerPath
    ]
});

Структура:

Внешний контур
┌──────────┐
│          │
│  ┌────┐  │
│  │    │  │
│  └────┘  │
│          │
└──────────┘

Внутренний контур

Внутренняя область становится прозрачной.

Rectangle

Rectangle создаёт прямоугольную область по географическим границам.

const rectangle = new google.maps.Rectangle({
    bounds: {
        north: 55.80,
        south: 55.70,
        east: 37.70,
        west: 37.50
    },
    fillColor: "#00FF00",
    fillOpacity: 0.25
});

rectangle.setMap(map);

Редактируемый прямоугольник

const rectangle = new google.maps.Rectangle({
    bounds,
    editable: true
});

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

Circle

Circle отображает окружность вокруг заданной точки.

const circle = new google.maps.Circle({
    center: {
        lat: 55.7558,
        lng: 37.6176
    },
    radius: 5000,
    fillColor: "#FF0000",
    fillOpacity: 0.3
});

circle.setMap(map);

Параметры окружности

Параметр Описание
center Центр
radius Радиус в метрах
fillColor Цвет заливки
strokeColor Цвет границы
editable Возможность редактирования

GroundOverlay

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

Пример

const imageBounds = {
    north: 55.80,
    south: 55.70,
    east: 37.70,
    west: 37.50
};

const overlay = new google.maps.GroundOverlay(
    "overlay.png",
    imageBounds
);

overlay.setMap(map);

Изображение автоматически масштабируется под указанные координаты.

Использование прозрачности

GroundOverlay поддерживает изменение прозрачности.

overlay.setOpacity(0.5);

Полностью прозрачное изображение:

overlay.setOpacity(0);

Полностью непрозрачное:

overlay.setOpacity(1);

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

Каждый overlay имеет параметр zIndex.

const polygon = new google.maps.Polygon({
    paths,
    zIndex: 10
});

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

marker.setZIndex(1000);

Это особенно важно при большом количестве объектов.

События Overlay

Практически все наложения поддерживают обработчики событий.

Клик по полигону

polygon.addListener("click", (event) => {
    console.log(event.latLng.toJSON());
});

Наведение курсора

polygon.addListener("mouseover", () => {
    console.log("Наведение");
});

Уход курсора

polygon.addListener("mouseout", () => {
    console.log("Курсор ушёл");
});

Редактируемые Overlay

Для ряда объектов можно включить режим редактирования.

Polygon

const polygon = new google.maps.Polygon({
    paths,
    editable: true
});

Polyline

const polyline = new google.maps.Polyline({
    path,
    editable: true
});

Circle

const circle = new google.maps.Circle({
    center,
    radius: 1000,
    editable: true
});

После включения режима появляются управляющие точки.

Перетаскиваемые Overlay

Многие объекты можно перемещать мышью.

const marker = new google.maps.Marker({
    position,
    draggable: true,
    map
});

Для фигур:

const polygon = new google.maps.Polygon({
    paths,
    draggable: true
});

Получение изменённых координат

После редактирования полигона можно считать новые вершины.

const path = polygon.getPath();

for (let i = 0; i < path.getLength(); i++) {
    const point = path.getAt(i);

    console.log(
        point.lat(),
        point.lng()
    );
}

OverlayView

OverlayView является базовым классом для создания пользовательских наложений.

Он предоставляет полный контроль над отображением элементов поверх карты.

Для реализации требуется определить три метода:

onAdd()
draw()
onRemove()

Создание собственного Overlay

Класс

class CustomOverlay extends google.maps.OverlayView {
    constructor(position) {
        super();

        this.position = position;
        this.div = null;
    }

    onAdd() {
        this.div = document.createElement("div");

        this.div.style.position = "absolute";
        this.div.style.background = "white";
        this.div.style.padding = "10px";

        const panes = this.getPanes();

        panes.overlayLayer.appendChild(this.div);
    }

    draw() {
        const projection = this.getProjection();

        const point =
            projection.fromLatLngToDivPixel(
                this.position
            );

        this.div.style.left = point.x + "px";
        this.div.style.top = point.y + "px";
    }

    onRemove() {
        this.div.remove();
    }
}

Добавление пользовательского Overlay

const overlay =
    new CustomOverlay(
        new google.maps.LatLng(
            55.7558,
            37.6176
        )
    );

overlay.setMap(map);

После привязки к карте автоматически вызываются методы жизненного цикла.

Жизненный цикл OverlayView

1. Создание объекта

const overlay =
    new CustomOverlay(position);

2. Добавление на карту

overlay.setMap(map);

Вызывается:

onAdd()

3. Отрисовка

draw()

Метод может вызываться многократно:

  • масштабирование карты;
  • перемещение карты;
  • изменение размеров контейнера.

4. Удаление

overlay.setMap(null);

Вызывается:

onRemove()

Pane-слои OverlayView

OverlayView предоставляет набор слоёв.

const panes = this.getPanes();

Доступны:

Pane Назначение
mapPane Базовый слой
overlayLayer Фигуры
markerLayer Маркеры
overlayMouseTarget Интерактивные элементы
floatPane Информационные окна

Пример:

panes.floatPane.appendChild(
    this.div
);

Элемент окажется поверх большинства объектов карты.

Работа с проекцией карты

Для преобразования координат используется объект Projection.

const projection =
    this.getProjection();

Преобразование географической точки:

const pixel =
    projection.fromLatLngToDivPixel(
        latLng
    );

Обратное преобразование:

const latLng =
    projection.fromDivPixelToLatLng(
        pixel
    );

Это позволяет строить сложные пользовательские интерфейсы поверх карты.

Анимация пользовательского Overlay

Поскольку OverlayView использует обычный DOM, доступны любые средства браузера.

this.div.animate(
    [
        {
            transform: "scale(0)"
        },
        {
            transform: "scale(1)"
        }
    ],
    {
        duration: 300
    }
);

Можно применять:

  • CSS-анимации;
  • Canvas;
  • SVG;
  • Web Animations API;
  • сторонние библиотеки.

Массовое управление Overlay

Часто требуется работать с большими наборами объектов.

const overlays = [];

Добавление:

overlays.push(marker);
overlays.push(polygon);
overlays.push(circle);

Скрытие всех объектов:

overlays.forEach(item => {
    item.setMap(null);
});

Показ:

overlays.forEach(item => {
    item.setMap(map);
});

Удаление:

overlays.length = 0;

Производительность при большом количестве Overlay

При работе с тысячами объектов возникают проблемы производительности.

Основные рекомендации:

  • использовать кластеризацию маркеров;
  • минимизировать количество DOM-элементов;
  • избегать лишних вызовов draw();
  • удалять невидимые объекты;
  • использовать Data Layer для больших наборов данных;
  • применять Canvas или WebGL для сложной визуализации;
  • группировать операции обновления.

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

Data Layer как специализированный Overlay

Data Layer представляет отдельный слой для геоданных.

map.data.addGeoJson(data);

Стилизация:

map.data.setStyle({
    fillColor: "blue",
    strokeWeight: 2
});

Data Layer автоматически создаёт необходимые overlay-объекты и обеспечивает более эффективную работу с большими объёмами географической информации по сравнению с ручным созданием множества Polygon и Polyline.

Сравнение основных Overlay

Тип Назначение
Marker Точечный объект
Polyline Маршрут или линия
Polygon Замкнутая область
Rectangle Прямоугольная зона
Circle Радиус вокруг точки
GroundOverlay Растровое изображение
OverlayView Пользовательское наложение
Data Layer Работа с GeoJSON и наборами объектов

Overlay-система Google Maps JavaScript API образует фундамент визуального слоя карты и позволяет отображать как стандартные географические объекты, так и полностью кастомные интерфейсные компоненты, интегрированные в механизм рендеринга карты.

Оглавление