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>
Примеры кода
Даже в этом простом примере есть несколько фрагментов, на которые нужно обратить внимание:
- Для объявления приложения HTML5 мы используем
<!DOCTYPE html>
. - Для карты мы создаем элемент
div
под названием "map" – в нем будет находиться карта. - Мы определяем функцию JavaScript, которая создает карту в этом элементе
div
. - Мы загружаем 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. Воспользуйтесь инструкциями и советами на странице Поддержка.