API JavaScript Карт позволяет настраивать карты с собственным контентом и изображениями для отображения на веб-страницах и мобильных устройствах. API JavaScript Карт включает четыре основных типа карт (дорожная карта, спутниковая, гибридная и карта местности), которые вы можете изменять с помощью слоев и стилей, элементов управления и событий, а также различных сервисов и библиотек.
Аудитория
Эта документация предназначена для людей, знакомых с программированием на JavaScript и концепциями объектно-ориентированного программирования. Вы также должны быть знакомы с Картами с точки зрения пользователя. В Интернете доступно множество руководств по JavaScript .
Эта концептуальная документация предназначена для того, чтобы вы могли быстро начать изучать и разрабатывать приложения с помощью Maps JavaScript API. Мы также публикуем Справочник по Maps JavaScript API .
Привет, мир
Самый простой способ начать изучение Maps JavaScript API — рассмотреть простой пример. В следующем примере показана карта с центром в Сиднее, Новый Южный Уэльс, Австралия.Машинопись
let map: google.maps.Map; async function initMap(): Promise<void> { 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, }); } initMap();
JavaScript
let map; async function initMap() { 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> <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 с помощью загрузчика начальной загрузки.
Эти шаги описаны ниже.
Загрузите API JavaScript Карт
Загрузчик начальной загрузки – это рекомендуемый способ загрузки API JavaScript Карт. В качестве альтернативы также предоставляется загрузчик JS API. Мы рекомендуем вам рассмотреть оба подхода и выбрать тот, который наиболее соответствует структуре кода вашего проекта.
Дополнительные сведения см. в разделе Загрузка 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", v: "weekly", // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.). // Add other bootstrap parameters as needed, using camel case. }); </script>
Чтобы загрузить библиотеки во время выполнения, используйте оператор await
для вызова importLibrary()
из асинхронной функции, как показано здесь:
Машинопись
let map: google.maps.Map; async function initMap(): Promise<void> { 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, }); } initMap();
JavaScript
let map; async function initMap() { const { Map } = await google.maps.importLibrary("maps"); map = new Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } initMap();
Пакет NPM js-api-loader
Используйте @googlemaps/js-api-loader, чтобы использовать NPM для загрузки API JavaScript Карт. Установите его через NPM, используя следующую команду:
npm install @googlemaps/js-api-loader
Этот пакет можно импортировать в приложение с помощью:
import { Loader } from "@googlemaps/js-api-loader"
Загрузчик предоставляет интерфейс обещаний и обратного вызова. Ниже показано использование метода Promise по умолчанию load()
.
Машинопись
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, используя простой 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 % высоты тела HTML. Обратите внимание, что мы должны специально объявить эти проценты для <body>
и <html>
.
Загрузка API JavaScript Карт
API JavaScript Карт загружается с помощью тегаscript
, который можно добавить в HTML-файл или динамически с помощью отдельного файла JavaScript. Мы рекомендуем вам рассмотреть оба подхода и выбрать тот, который наиболее соответствует структуре кода вашего проекта.Встроенная загрузка
Чтобы загрузить Maps JavaScript API в HTML-файле, добавьте тег script
, как показано ниже.
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&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()
.
Машинопись
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
установлено несколько атрибутов, которые рекомендуется использовать. Ниже приводится объяснение каждого атрибута.
-
src
: URL-адрес, с которого загружается API JavaScript Карт, включая все символы и определения, необходимые для использования API JavaScript Карт. URL-адрес в этом примере имеет два параметра:key
, где вы указываете свой ключ API, иcallback
, где вы указываете имя глобальной функции, которая будет вызываться после полной загрузки Maps JavaScript API. Узнайте больше о параметрах URL . -
async
: просит браузер асинхронно загрузить и выполнить скрипт. Когда скрипт будет выполнен, он вызовет функцию, указанную с помощью параметраcallback
.
Библиотеки
При загрузке Maps JavaScript API через URL-адрес вы можете дополнительно загрузить дополнительные библиотеки, используя оператор await
для вызова importLibrary()
из асинхронной функции. Библиотеки — это модули кода, которые предоставляют дополнительные функции основному API JavaScript Карт, но не загружаются, если вы их специально не запросите. Дополнительную информацию см. в разделе «Библиотеки в Maps JavaScript API» .
Сопоставление элементов DOM
<div id="map"></div>
Чтобы карта отображалась на веб-странице, мы должны зарезервировать для нее место. Обычно мы делаем это, создавая именованный элемент div
и получая ссылку на этот элемент в объектной модели документа браузера (DOM).
В приведенном выше примере мы использовали CSS, чтобы установить высоту div карты на «100%». Это расширится, чтобы соответствовать размеру на мобильных устройствах. Возможно, вам придется настроить значения ширины и высоты в зависимости от размера экрана и заполнения браузера. Обратите внимание, что ширина элементов div обычно берется из содержащего их элемента, а пустые элементы div обычно имеют нулевую высоту. По этой причине вы всегда должны явно задавать высоту <div>
.
Параметры карты
Для каждой карты есть две обязательные опции: center
и zoom
.
map = new Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 });
Уровни масштабирования
Начальное разрешение для отображения карты задается свойством zoom
, где масштаб 0
соответствует полностью уменьшенной карте Земли, а более высокие уровни масштабирования увеличиваются с более высоким разрешением.
zoom: 8
Чтобы представить карту всей Земли в виде одного изображения, потребуется либо огромная карта, либо маленькая карта с очень низким разрешением. В результате изображения карт в Картах Google и Maps JavaScript API разбиваются на «плитки» и «уровни масштабирования». При низких уровнях масштабирования небольшой набор фрагментов карты покрывает большую территорию; при более высоких уровнях масштабирования плитки имеют более высокое разрешение и занимают меньшую площадь. В следующем списке показан приблизительный уровень детализации, который вы можете ожидать при каждом уровне масштабирования:
- 1: Мир
- 5: Суша/континент
- 10: Город
- 15: Улицы
- 20: Здания
Следующие три изображения отражают одно и то же местоположение Токио при уровнях масштабирования 0, 7 и 18.
Информацию о том, как Maps JavaScript API загружает плитки на основе текущего уровня масштабирования, см. в руководстве по координатам карты и плиток .
Объект карты
map = new 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 Maps, в вашей учетной записи должна быть включена оплата, а все запросы должны включать действительный ключ API. Следующий поток поможет устранить эту неполадку:
Если ваш код не работает:
Чтобы помочь вам запустить код ваших карт, Брендан Кенни и Мано Маркс в этом видео указывают на некоторые распространенные ошибки и способы их исправления.
- Ищите опечатки. Помните, что JavaScript — язык, чувствительный к регистру.
- Ознакомьтесь с основами — некоторые из наиболее распространенных проблем возникают при первоначальном создании карты. Такой как:
- Убедитесь, что вы указали свойства
zoom
иcenter
в параметрах карты. - Убедитесь, что вы объявили элемент div, в котором карта будет отображаться на экране.
- Убедитесь, что элемент div для карты имеет высоту. По умолчанию элементы div создаются с высотой 0 и поэтому невидимы.
- Убедитесь, что вы указали свойства
- Используйте отладчик JavaScript, чтобы выявить проблемы, например тот, который доступен в Инструментах разработчика Chrome . Начните с поиска ошибок в консоли JavaScript.
- Задавайте вопросы в Stack Overflow . Рекомендации о том, как публиковать хорошие вопросы, доступны на странице поддержки .