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

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

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

Эта концептуальная документация поможет вам быстро начать проектировать и разрабатывать приложения с использованием Google Maps API. Также мы публикуем Справочник по Google Maps API.

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

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

<!DOCTYPE html>
<html>
  <head>
    <style type="text/css">
      html, body { height: 100%; margin: 0; padding: 0; }
      #map { height: 100%; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script type="text/javascript">

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

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

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

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

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

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

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

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

<!DOCTYPE html>

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

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

<style type="text/css">
  html, body { height: 100%; margin: 0; padding: 0; }
  #map { height: 100%; }
</style>

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

Загрузка Google Maps API

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

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

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

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

Пользователям Google Maps API for Work следует ознакомиться с разделом Загрузка Google Maps JavaScript API в документации Maps API for Work для получения важной информации по загрузке Google Maps API в приложениях.

HTTPS или HTTP

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

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

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

Библиотеки

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

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

В теге script, используемом для загрузки Google Maps 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 API разбиваются на "листы" и "уровни масштабирования". При малом увеличении небольшой набор листов покрывает большую площадь, а при сильном увеличении листы имеют более высокое разрешение и покрывают меньшую площадь.

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

Информацию о загрузке листов Google Maps 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) с использованием любых переданных (необязательных) параметров.

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

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

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

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

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

Текущей странице
Документации
Google Maps Javascript API
Google Maps Javascript API
Продуктах
Нужна помощь? Обратитесь в службу поддержки.