Обзор

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

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

Аудитория

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

Эта концептуальная документация предназначена для того, чтобы вы могли быстро приступить к изучению и разработке приложений с помощью Maps JavaScript API. Мы также публикуем Справочник API JavaScript для Карт .

Привет, мир

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

Машинопись

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;

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;

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;
}

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>
Посмотреть пример

Попробуйте образец

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

  1. Мы объявляем приложение как HTML5, используя объявление <!DOCTYPE html> .
  2. Мы создаем элемент div с именем «карта» для хранения карты.
  3. Мы определяем функцию JavaScript, которая создает карту в div .
  4. Мы загружаем 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> (с id 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.

Машинопись

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,
  });
});

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,
  });
});

Атрибуты тега скрипта

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

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

Библиотеки

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

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

В теге script , который загружает Maps JavaScript API, можно опустить атрибут defer и параметр callback . Это приведет к блокировке загрузки API до тех пор, пока 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.

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

Объект карты

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

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

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

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

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

Исправление проблем

Ключ API и ошибки выставления счетов

При определенных обстоятельствах может отображаться затемненная карта или «негативное» изображение Street View с водяным знаком с текстом «только для целей разработки». Такое поведение обычно указывает на проблемы с ключом API или выставлением счетов. Чтобы использовать продукты платформы Google Карт, в вашей учетной записи должно быть включено выставление счетов, а все запросы должны включать действительный ключ API. Следующий алгоритм поможет решить эту проблему:

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

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

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