Создание простого маркера

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

Основная точка входа — объект google.maps.Map. Для его создания требуется DOM-элемент и объект конфигурации с параметрами центра и масштаба.

const map = new google.maps.Map(document.getElementById("map"), {
  center: { lat: 55.7558, lng: 37.6173 },
  zoom: 10,
});

Параметр center задаёт координаты центра карты в формате широта/долгота, а zoom определяет уровень приближения. Чем больше значение, тем детальнее отображается территория.

Основы координатной системы

Маркер в Google Maps опирается на географические координаты, представленные в виде объекта:

{ lat: number, lng: number }

Широта (lat) определяет положение по вертикали относительно экватора, долгота (lng) — по горизонтали относительно нулевого меридиана.

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

Создание простого маркера

Базовый маркер создаётся через конструктор google.maps.Marker. В минимальной конфигурации требуется указать позицию и карту, на которой он должен отображаться.

const marker = new google.maps.Marker({
  position: { lat: 55.7558, lng: 37.6173 },
  map: map,
});

После выполнения этого кода на карте появляется стандартный маркер с иконкой по умолчанию.

Параметр map определяет привязку маркера к конкретному экземпляру карты. Если он не указан, маркер создаётся, но не отображается до момента явного добавления через метод setMap.

Привязка маркера к карте

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

const marker = new google.maps.Marker({
  position: { lat: 55.7558, lng: 37.6173 },
});

marker.setMap(map);

Метод setMap позволяет динамически управлять отображением объекта. Передача null в этот метод удаляет маркер с карты без уничтожения самого объекта.

marker.setMap(null);

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

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

Карты редко ограничиваются одним объектом. Добавление нескольких маркеров осуществляется созданием отдельных экземпляров google.maps.Marker.

const locations = [
  { lat: 55.7558, lng: 37.6173 },
  { lat: 55.7510, lng: 37.6180 },
  { lat: 55.7600, lng: 37.6200 },
];

locations.forEach((position) => {
  new google.maps.Marker({
    position,
    map: map,
  });
});

Каждый маркер независим и может иметь собственные параметры отображения, поведения и событий.

Настройка заголовка маркера

Маркер может содержать текстовую подсказку, отображаемую при наведении курсора. Для этого используется свойство title.

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

title не влияет на визуальную иконку, но улучшает информативность интерфейса.

Анимация появления маркера

API поддерживает простую анимацию через свойство animation. Наиболее распространённый вариант — эффект падения.

const marker = new google.maps.Marker({
  position: { lat: 55.7558, lng: 37.6173 },
  map: map,
  animation: google.maps.Animation.DROP,
});

Дополнительно доступна анимация BOUNCE, создающая эффект подпрыгивания, однако она часто используется ограниченно из-за визуальной перегрузки интерфейса.

Анимация может быть изменена в любой момент:

marker.setAnimation(google.maps.Animation.BOUNCE);
marker.setAnimation(null);

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

Стандартный маркер может быть заменён пользовательским изображением. Для этого используется свойство icon.

const marker = new google.maps.Marker({
  position: { lat: 55.7558, lng: 37.6173 },
  map: map,
  icon: "https://example.com/custom-marker.png",
});

Также возможно более детальное описание иконки через объект:

const marker = new google.maps.Marker({
  position: { lat: 55.7558, lng: 37.6173 },
  map: map,
  icon: {
    url: "https://example.com/custom-marker.png",
    scaledSize: new google.maps.Size(40, 40),
  },
});

Параметр scaledSize позволяет контролировать размер отображаемого изображения независимо от исходного разрешения.

Работа с событиями маркера

Маркер поддерживает систему событий, позволяющую реагировать на действия пользователя. Наиболее часто используется событие click.

const marker = new google.maps.Marker({
  position: { lat: 55.7558, lng: 37.6173 },
  map: map,
});

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

События позволяют интегрировать маркеры в интерфейс взаимодействия: открытие информационных окон, изменение состояния элементов, запуск логики маршрутизации.

Информационные окна при клике

Часто маркеры используются совместно с InfoWindow, отображающим дополнительную информацию.

const marker = new google.maps.Marker({
  position: { lat: 55.7558, lng: 37.6173 },
  map: map,
});

const infoWindow = new google.maps.InfoWindow({
  content: "<div>Объект на карте</div>",
});

marker.addListener("click", () => {
  infoWindow.open(map, marker);
});

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

Управление видимостью маркера

Маркер может быть скрыт без удаления с карты через метод setVisible.

marker.setVisible(false);
marker.setVisible(true);

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

Практика работы с коллекциями маркеров

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

const markers = [];

locations.forEach((position) => {
  const marker = new google.maps.Marker({
    position,
    map: map,
  });

  markers.push(marker);
});

Это позволяет выполнять массовые операции:

markers.forEach((marker) => marker.setMap(null));

или

markers.forEach((marker) => marker.setVisible(false));

Ограничения классического Marker

Классический google.maps.Marker постепенно заменяется более современной реализацией AdvancedMarkerElement, которая предоставляет расширенные возможности стилизации и производительности. Однако базовый маркер сохраняется как фундаментальный элемент API и остаётся совместимым с большинством существующих проектов.

Оглавление