Обзор

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Выберите платформу: Android iOS JavaScript

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

Аудитория

Эта документация рассчитана на тех, кто уже знаком с языком JavaScript и принципами объектно ориентированного программирования. Также будет полезен опыт работы с Google Картами в качестве пользователя. Если вас интересуют обучающие ресурсы по JavaScript, вы без труда найдете их в интернете.

Цель этого раздела – помочь разработчикам быстро освоить Maps JavaScript API. Также мы подготовили справочную документацию по Maps JavaScript API.

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

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

TypeScript

let map: google.maps.Map;

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

let map;

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

window.initMap = initMap;
index.js

CSS

/*
 * 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.css

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!--
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html
Посмотреть пример

Примеры кода

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

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

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

Объявление приложения в формате HTML5

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

<!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>.

Загрузка Maps JavaScript API

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

Встроенная загрузка

Чтобы загрузить Maps JavaScript API в HTML-файл, добавьте тег script, как показано ниже.

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

Динамическая загрузка

Посмотрите, как динамически загрузить встроенный JavaScript API Карт с помощью отдельного файла JavaScript, в примере ниже. Этот подход позволяет брать весь код для работы с API из отдельного файла .js (так же, как делает встроенный тег скрипта).

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

Динамическая загрузка

Пакет @googlemaps/js-api-loader позволяет упростить динамическую загрузку. Его можно установить через NPM следующим образом:

npm install @googlemaps/js-api-loader

Пакет можно импортировать в приложение:

import { Loader } from "@googlemaps/js-api-loader"

Загрузчик предоставляет объект Promise и интерфейс обратного вызова. Ниже показано использование load() (метода Promise по умолчанию).

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

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

index.js

Атрибуты тега Script

Обратите внимание, что в приведенных выше примерах для тега script задано несколько рекомендуемых атрибутов. Пояснения к ним даются ниже.

  • src – URL-адрес, с которого загружается API JavaScript Карт, включая все символы и определения, необходимые для использования API. В этом примере у URL-адреса есть два параметра: key, где вы указываете свой ключ API, и callback, где вы указываете имя глобальной функции, которая будет вызываться после полной загрузки Maps JavaScript API. Подробнее о параметрах URL…
  • async – дает команду браузеру асинхронно загрузить и выполнить скрипт. Когда скрипт выполняется, он вызывает функцию, заданную с помощью параметра callback.

Библиотеки

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

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

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

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

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

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

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

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

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

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

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

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

Начальное разрешение, используемое при отображении карты, определяется параметром zoom, причем значение 0 соответствует наименьшему масштабу. При увеличении масштаба камера приближается к карте.

zoom: 8

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

  • 1: мир;
  • 5: континент;
  • 10: город;
  • 15: улицы;
  • 20: здания.

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

Подробнее о загрузке фрагментов в зависимости от уровня масштабирования читайте в руководстве по координатам карт и фрагментов.

Объект Map

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

За представление карты в JavaScript отвечает класс Map. Объекты этого класса определяют только одну карту. Вы можете создать несколько экземпляров объекта, каждый из которых будет определять на странице свою карту. Это можно сделать с помощью оператора JavaScript new.

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

В примере ниже переменная map определена и назначена новому объекту Map. Функция Map() использована в качестве конструктора.

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

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

Ошибки, связанные с оплатой и ключом API

Иногда карты могут отображаться затемненными, а панорамы Просмотра улиц – в негативе, с водяными знаками "for development purposes only" (только для целей разработки). Чаще всего такая проблема связана с ключом API или оплатой. Сервисами платформы Google Карт можно пользоваться, только если в вашем аккаунте активированы платежные функции, а в запросах к API указан действительный ключ. Ниже приведена последовательность шагов, которая поможет вам выявить и решить проблему.

Если ваш код по-прежнему не работает

Чтобы помочь вам справиться с наиболее распространенными ошибками, Брендан Кенни и Мано Маркс записали для вас это видео. Вот что они советуют:

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