Начало работы

Целевая аудитория

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

Этот концептуальный документ поможет вам быстро приступить к проектированию и разработке приложений с использованиемGoogle Maps JavaScript API. Также мы публикуем Дополнительные материалы по Google Maps JavaScript API.

Приложение Hello World

Проще всего познакомиться с Google Maps JavaScript API на простом примере. На следующей веб-странице показана карта, в центре которой располагается город Сидней (штат Новый Южный Уэльс, Австралия):

var map;
function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8
  });
}

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

/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap" async defer></script>

<!DOCTYPE html>
<html>
  <head>
    <title>Simple Map</title>
    <meta name="viewport" content="initial-scale=1.0">
    <meta charset="utf-8">
    <style>
      /* Always set the map height explicitly to define the size of the div
       * element that contains the map. */
      #map {
        height: 100%;
      }
      /* Optional: Makes the sample page fill the window. */
      html, body {
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map;
      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: {lat: -34.397, lng: 150.644},
          zoom: 8
        });
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

Просмотр примера (map-simple.html)

Даже в этом простом примере следует отметить ряд моментов:

Приложение декларируется в формате HTML5 с использованием декларации <!DOCTYPE html>.
Для хранения карты создается элемент div с именем "map".
Определяется функция JavaScript, которая создает карту в элементе div.
Maps JavaScript API загружается с помощью тега script.

Более подробное описание этих шагов приведено ниже.

Декларирование приложения в формате HTML5

Мы рекомендуем декларировать тип DOCTYPE внутри веб-приложения. В приведенных примерах мы декларируем для приложений тип HTML5, используя простую декларацию HTML5 DOCTYPE, как показано ниже:

<!DOCTYPE html>

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

Некоторые стили CSS, работающие в режиме совместимости, не работают в стандартном режиме. В частности, все размеры, выраженные в процентах, должны наследоваться от родительских элементов блоков. Если для любого из этих родительских элементов размер не указан, предполагается, что они имеют размер 0 x 0 пикселей. Поэтому мы используем следующую декларацию <style>:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Эта декларация CSS указывает, что контейнер карты <div> (с идентификатором map) должен занимать до 100% высоты тела HTML. Следует отметить, что мы также должны явно декларировать эти процентные величины для частей <body> и <html>.

Загрузка Google Maps JavaScript API

Для загрузки Google Maps JavaScript API следует использовать тег script, как в следующем примере:

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

URL-адрес в теге script указывает местоположение файла JavaScript, который загружает все символы и определения, необходимые для использования Maps JavaScript API. Этот тег script является обязательным.

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

Параметр key содержит ключ API вашего приложения. Дополнительную информацию см. в документе Получение ключа.

Примечание. При загрузке API пользователи Google Maps APIs Premium Plan могут использовать ключ API или действующий идентификатор клиента. См. дополнительную информацию о параметрах аутентификации пользователей Premium Plan.

HTTPS или HTTP

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

Мы рекомендуем загружать Maps JavaScript API по протоколу HTTPS, используя тег <script>, приведенный выше.

При необходимости вы можете загрузить Maps JavaScript API по протоколу HTTP через URL http://maps.googleapis.com/ или http://maps.google.cn (для пользователей из Китая).

Библиотеки

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

Синхронная загрузка API

В теге script, загружающем Maps JavaScript API, можно опустить атрибут async и параметр callback. В этом случае загрузка API заблокирует все другие операции до момента ее завершения.

Скорее всего, это замедлит загрузку страницы. Однако это позволит писать последующие теги сценария с уверенностью в том, что API уже загружен.

Элементы DOM карты

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

Чтобы отобразить карту на веб-странице, для нее нужно зарезервировать место. Обычно для этого создается именованный элемент div, а в объектной модели документов браузера (DOM) создается ссылка на этот элемент.

В примере выше мы используем CSS, чтобы установить значение высоты "100%" для элемента div с картой. Благодаря этому размер карты будет подгоняться под размер экрана мобильных устройств. Значения ширины и высоты требуется корректировать в зависимости от размера экрана браузера и отступов. Элементы div обычно используют ширину содержащего их элемента, а пустые элементы div обычно имеют высоту 0. В связи с этим высоту элементов <div> всегда следует указывать явно.

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

Два параметра обязательны для каждой карты: center и zoom.

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

Уровни масштабирования

Изначальное разрешение, в котором отображается карта, определяется свойством zoom. Значение zoom 0 соответствует карте планеты Земля в наименьшем масштабе, а при более высоком значении разрешение увеличивается. Масштаб указывается как целое число.

zoom: 8

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

1: мир
5: континент
10: Город
15: Улицы
20: Здания

На следующих трех изображениях показано одно и то же место в Токио с уровнями масштабирования 0, 7 и 18.

Информацию о загрузке фрагментов Maps JavaScript API в зависимости от текущего уровня масштабирования см. в разделе Координаты фрагментов в документации по типам карт.

Объект Map

map = new google.maps.Map(document.getElementById("map"), {...});

Класс Map – это класс JavaScript, представляющий карту. Объекты этого класса определяют отдельную карту на странице. (Вы можете создать несколько экземпляров этого класса – каждый объект будет определять отдельную карту на странице.) Для создания нового экземпляра этого класса мы используем оператор JavaScript new.

При создании нового экземпляра карты нужно указать на странице HTML элемент <div>, который послужит контейнером для карты. Узлы HTML представляют собой дочерние элементы объекта JavaScript document, и мы получаем ссылку на этот элемент с помощью метода document.getElementById().

Этот код определяет переменную (с именем map) и привязывает ее к новому объекту Map. Ниже показана функция Map(), называемая конструктором, а также приводится ее определение:

Конструктор	Описание
`Map(mapDiv:Node, opts?:MapOptions )`	Создает новую карту в заданном контейнере HTML (обычно в элементе DIV) с использованием любых переданных (необязательных) параметров.

Устранение неполадок

Примечание. Использование параметра sensor больше не требуется.

В этом видеоролике Брендан Кенни (Brendan Kenny) и Мэноу Маркс (Mano Marks) рассказывают о некоторых распространенных ошибках при создании карт и способах их устранения.

Если ваш код не работает:

Ищите опечатки. Помните, что в языке JavaScript учитывается регистр.
Не забывайте об основах! Некоторые распространенные проблемы возникают еще на начальном этапе создания карты. Например:
- Убедитесь, что вы указали свойства zoom и center в параметрах вашей карты.
- Убедитесь, что вы декларировали элемент div, в котором карта будет отображаться на экране.
- Убедитесь, что вы задали высоту для элемента div на карте. По умолчанию элементы div создаются с высотой 0 и не отображаются на экране.
Ознакомьтесь с нашим примером реализации.
Используйте для выявления проблем отладчик JavaScript, например, отладчик в составе набора инструментов Chrome Developer Tools. Начните поиск ошибок в консоли JavaScript.
Задавайте вопросы на сайте Stack Overflow. Рекомендации относительно того, как задавать правильные вопросы, см. на странице Поддержка.

Все готово!

Целевая аудитория

Приложение Hello World

Декларирование приложения в формате HTML5

Загрузка Google Maps JavaScript API

HTTPS или HTTP

Библиотеки

Синхронная загрузка API

Элементы DOM карты

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

Уровни масштабирования

Объект Map

Устранение неполадок

Оставить отзыв о...

Все готово!

Активация Google Maps JavaScript API

Начало работы

Целевая аудитория

Приложение Hello World

Декларирование приложения в формате HTML5

Загрузка Google Maps JavaScript API

HTTPS или HTTP

Библиотеки

Синхронная загрузка API

Элементы DOM карты

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

Уровни масштабирования

Объект Map

Устранение неполадок

Оставить отзыв о...