Создание первой карты

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

Перед использованием необходимо создать проект в Google Cloud Console и включить сервис Google Maps Platform. Для доступа требуется API-ключ, который используется при загрузке скрипта.

Документация доступна по адресу: Google Maps JavaScript API documentation

Подключение библиотеки выполняется через тег script:

<script
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
  async
  defer
></script>

Ключевые параметры:

  • key — API-ключ, связанный с проектом
  • callback — функция инициализации карты
  • async и defer — асинхронная загрузка без блокировки рендера страницы

Подготовка HTML-контейнера

Карта рендерится внутри HTML-элемента с заданными размерами. Отсутствие высоты приводит к тому, что карта не отображается.

<div id="map"></div>

CSS-стили обязательны:

#map {
  height: 500px;
  width: 100%;
}

При работе с адаптивными интерфейсами важно учитывать, что контейнер должен иметь вычисляемую высоту, например через flexbox или vh-единицы.

Инициализация карты

Базовая функция инициализации создаёт объект карты через конструктор google.maps.Map.

function initMap() {
  const center = { lat: 40.748817, lng: -73.985428 };

  const map = new google.maps.Map(document.getElementById("map"), {
    center: center,
    zoom: 12,
  });
}

Параметры:

  • center — координаты центра карты (широта и долгота)
  • zoom — уровень масштабирования (0–21)
  • DOM-элемент — контейнер для рендеринга

Координаты и система представления

Google Maps использует систему WGS84, где:

  • lat — широта
  • lng — долгота

Пример различных значений масштаба:

  • 1–5: континенты
  • 6–10: крупные города
  • 11–15: районы и улицы
  • 16–21: здания и детальная карта

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

Маркер создаётся через google.maps.Marker и привязывается к карте через параметр map.

function initMap() {
  const center = { lat: 40.748817, lng: -73.985428 };

  const map = new google.maps.Map(document.getElementById("map"), {
    center: center,
    zoom: 12,
  });

  const marker = new google.maps.Marker({
    position: center,
    map: map,
    title: "Центральная точка",
  });
}

Маркер поддерживает:

  • подпись title
  • кастомные иконки
  • анимации (DROP, BOUNCE)

Работа с несколькими маркерами

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

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 48.8566, lng: 2.3522 },
    zoom: 5,
  });

  const locations = [
    { lat: 48.8566, lng: 2.3522 },
    { lat: 50.1109, lng: 8.6821 },
    { lat: 41.9028, lng: 12.4964 },
  ];

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

Параметры конфигурации карты

Объект настроек карты позволяет управлять интерфейсом:

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

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

  • mapTypeId:

    • roadmap — стандартная карта
    • satellite — спутник
    • hybrid — гибрид
    • terrain — рельеф

  • disableDefaultUI — отключение стандартных элементов интерфейса

  • zoomControl — управление масштабом

Асинхронная загрузка и callback

Функция initMap должна быть доступна в глобальной области видимости, так как вызывается после загрузки API.

window.initMap = function () {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 35.6895, lng: 139.6917 },
    zoom: 11,
  });
};

При модульной структуре важно явно экспортировать функцию или привязать её к window.

Обработка событий карты

API поддерживает события пользовательского взаимодействия:

map.addListener("click", (event) => {
  console.log(event.latLng.lat(), event.latLng.lng());
});

События:

  • click — клик по карте
  • drag — перемещение карты
  • zoom_changed — изменение масштаба
  • idle — завершение загрузки/перемещения

Добавление информационного окна

Инфо-окно используется для отображения текста при взаимодействии с маркером:

const infoWindow = new google.maps.InfoWindow({
  content: "<h3>Точка интереса</h3><p>Описание объекта</p>",
});

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

Типичные ошибки при создании первой карты

Часто возникающие проблемы:

  • отсутствует высота контейнера #map
  • API-ключ не активирован или ограничен
  • не включён billing в проекте
  • функция initMap не доступна глобально
  • неверные координаты (NaN или undefined)

Безопасность API-ключа

API-ключ должен быть ограничен:

  • по HTTP-рефереру (домены)
  • по IP (для серверных запросов)
  • по API (разрешён только Maps JavaScript API)

Открытый ключ без ограничений может привести к несанкционированному использованию квоты.

Полный пример первой карты

<!DOCTYPE html>
<html>
<head>
  <title>First Map</title>
  <style>
    #map {
      height: 100vh;
      width: 100%;
    }
  </style>
</head>
<body>
  <div id="map"></div>

  <script>
    function initMap() {
      const center = { lat: 51.5074, lng: -0.1278 };

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

      new google.maps.Marker({
        position: center,
        map: map,
        title: "London",
      });
    }
  </script>

  <script
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    async
    defer
  ></script>
</body>
</html>

Особенности жизненного цикла карты

Инициализация происходит после загрузки внешнего скрипта, поэтому порядок выполнения критичен: сначала HTML, затем callback, затем создание экземпляра карты. Любые операции с картой должны выполняться после её создания, иначе объекты API будут недоступны.

При повторном использовании контейнера карта не пересоздаётся автоматически — требуется либо очистка DOM, либо повторная инициализация экземпляра google.maps.Map.

Оглавление