Обзор

Выберите платформу: Android iOS JavaScript

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

Аудитория

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

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

Простейший пример приложения

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

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

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>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
Посмотреть пример

Примеры кода

Даже в этом простом примере есть несколько фрагментов, на которые нужно обратить внимание:

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

Эти шаги подробно описаны ниже.

Как загрузить Maps JavaScript API

Для загрузки Maps JavaScript API рекомендуется использовать встроенный загрузчик или пакет js-api-loader. Мы рекомендуем опробовать оба метода и выбрать тот, который лучше всего подходит для структуры кода в вашем проекте.

Подробную информацию можно найти в инструкции по загрузке Maps JavaScript API.

Встроенный загрузчик

Загрузите Maps JavaScript API, добавив встроенный загрузчик в код приложения, как показано в следующем фрагменте кода:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

Чтобы загружать библиотеки во время выполнения, используйте оператор await для вызова importLibrary() внутри асинхронной функции, как показано ниже.

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

Пакет js-api-loader для NPM

Пакет @googlemaps/js-api-loader позволяет загружать Maps JavaScript API через NPM. Чтобы установить его в 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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

Как объявить, что приложение создано в формате HTML5

В приложении рекомендуется объявлять истинный тип DOCTYPE. В приведенных здесь примерах используется простой код 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 % высоту страницы. Обратите внимание, что процентные значения также нужно явно объявить для <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>

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

Ниже показано, как динамически загрузить Maps 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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

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

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

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

Библиотеки

Когда вы загружаете Maps JavaScript API по URL, можно также загрузить дополнительные библиотеки, используя оператор await для вызова importLibrary() из асинхронной функции. Библиотеки – это модули кода, которые добавляют дополнительные функции в Maps JavaScript API. Они загружаются, только если вы специально их запросите. Подробную информацию вы найдете в разделе Библиотеки Maps JavaScript API.

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

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

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

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

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

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

map = new 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 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. Воспользуйтесь инструкциями и советами на странице Поддержка.