Параметры маркера

Параметры маркера в Google Maps Platform JavaScript API определяют внешний вид, поведение и взаимодействие объекта Marker на карте. Конфигурация передаётся в виде объекта при создании маркера и напрямую влияет на его отображение, событийную модель и производительность.

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

const marker = new google.maps.Marker({
  position: { lat: 40.7128, lng: -74.0060 },
  map: map
});

Объект параметров включает набор свойств, каждое из которых отвечает за конкретный аспект поведения маркера.

position — координаты размещения

position определяет географическое положение маркера на карте. Это обязательный параметр для отображения.

Поддерживаются два формата:

  • объект { lat: number, lng: number }
  • экземпляр google.maps.LatLng
position: { lat: 55.751244, lng: 37.618423 }
position: new google.maps.LatLng(55.751244, 37.618423)

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

map — привязка к карте

Параметр map определяет, на какой объект карты будет добавлен маркер.

map: map

Если значение не указано, маркер создаётся, но не отображается до вызова:

marker.setMap(map);

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

marker.setMap(null);

title — всплывающая подсказка

title задаёт текст, который отображается при наведении курсора.

title: "Центральная точка"

Используется для улучшения доступности и быстрого понимания значения маркера без дополнительных UI-элементов.

icon — кастомизация внешнего вида

Параметр icon управляет визуальным представлением маркера.

Строковый URL

icon: "https://example.com/icon.png"

Объект с настройками

icon: {
  url: "https://example.com/icon.png",
  scaledSize: new google.maps.Size(32, 32)
}

SVG или символы

icon: {
  path: google.maps.SymbolPath.CIRCLE,
  scale: 6,
  fillColor: "#FF0000",
  fillOpacity: 1,
  strokeWeight: 1
}

Использование кастомных иконок позволяет адаптировать маркеры под визуальный стиль интерфейса или тип данных.

label — текстовая метка

label добавляет краткую текстовую подпись поверх маркера.

label: "A"

Также поддерживается объектная форма:

label: {
  text: "A",
  color: "white",
  fontSize: "12px"
}

Ограничение: label предназначен для коротких строк, обычно один символ или число.

draggable — перетаскивание маркера

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

draggable: true

При включении активируются события:

  • dragstart
  • drag
  • dragend

Пример обработки:

marker.addListener("dragend", (event) => {
  console.log(event.latLng.toString());
});

animation — анимация появления

Параметр animation задаёт поведение маркера при добавлении.

Доступные значения:

  • google.maps.Animation.DROP
  • google.maps.Animation.BOUNCE
animation: google.maps.Animation.DROP

Анимация часто используется для визуального выделения новых объектов на карте.

zIndex — управление слоями

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

zIndex: 1000

Чем больше значение, тем выше приоритет отрисовки.

Это особенно важно при плотном размещении объектов в одной географической зоне.

visible — управление отображением

Параметр visible определяет, отображается ли маркер на карте.

visible: true

Скрытие без удаления:

marker.setVisible(false);

В отличие от setMap(null), маркер сохраняет состояние и может быть быстро восстановлен.

opacity — прозрачность маркера

opacity регулирует степень прозрачности маркера.

opacity: 0.7

Значения варьируются от 0 (полностью прозрачный) до 1 (полностью непрозрачный).

clickable — взаимодействие с кликами

Параметр clickable включает или отключает обработку кликов.

clickable: true

При значении false маркер становится визуальным элементом без интерактивности.

cursor — поведение курсора

cursor задаёт стиль курсора при наведении.

cursor: "pointer"

Используется для улучшения UX при интерактивных слоях карты.

shape — зона активного клика

Параметр shape задаёт область, в пределах которой маркер считается кликабельным.

shape: {
  coords: [1, 1, 1, 20, 18, 20, 18, 1],
  type: "poly"
}

Используется редко, преимущественно при сложных кастомных иконках.

optimized — оптимизация рендеринга

optimized управляет способом отрисовки маркеров.

optimized: true

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

При false каждый маркер отрисовывается отдельно, что полезно при сложных анимациях или кастомных элементах.

Событийная модель в связке с параметрами

Параметры маркера напрямую влияют на доступные события:

marker.addListener("click", () => {
  console.log("Маркер нажат");
});

Изменение параметров во время выполнения:

marker.setIcon(newIcon);
marker.setLabel("B");
marker.setDraggable(false);

Комплексная конфигурация маркера

const marker = new google.maps.Marker({
  position: { lat: 48.8566, lng: 2.3522 },
  map: map,
  title: "Paris",
  icon: {
    url: "/icons/marker.png",
    scaledSize: new google.maps.Size(40, 40)
  },
  label: {
    text: "P",
    color: "#ffffff"
  },
  draggable: true,
  animation: google.maps.Animation.DROP,
  zIndex: 10,
  opacity: 0.9,
  clickable: true,
  cursor: "pointer",
  optimized: true
});

Такой набор параметров формирует полностью управляемый маркер, интегрированный в инфраструктуру Google Maps Platform и адаптированный под интерактивные картографические интерфейсы.

Оглавление