Добавьте карту Google с маркером с помощью JavaScript

Введение

В этом руководстве показано, как добавить карту Google с маркером на веб-страницу, используя HTML, CSS и JavaScript. Также показано, как настроить параметры карты и как использовать слоты управления для добавления метки на карту.

Ниже представлена ​​карта, которую вы создадите, используя этот урок. Маркер расположен в Улуру (также известном как Айерс-Рок) в национальном парке Улуру-Ката-Тьюта.

Начиная

Создание карты Google с маркером на вашей веб-странице состоит из трех шагов:

  1. Получить ключ API
  2. Создать HTML-страницу
  3. Добавить карту с маркером

Вам понадобится веб-браузер. Выберите из списка поддерживаемых браузеров один из известных браузеров, например, Google Chrome (рекомендуется), Firefox, Safari или Edge, в зависимости от вашей платформы.

Шаг 1: Получите ключ API

В этом разделе объясняется, как аутентифицировать ваше приложение в API карт JavaScript, используя собственный ключ API.

Чтобы получить ключ API, выполните следующие действия:

  1. Перейдите в консоль Google Cloud .

  2. Создайте или выберите проект.

  3. Нажмите «Продолжить» , чтобы включить API и все связанные с ним сервисы.

  4. На странице «Учетные данные» получите ключ API (и установите ограничения для ключа API). Примечание: Если у вас уже есть неограниченный ключ API или ключ с ограничениями для браузера, вы можете использовать этот ключ.

  5. Чтобы предотвратить кражу квот и защитить свой API-ключ, см. раздел «Использование API-ключей» .

  6. Включите выставление счетов. Дополнительную информацию см. в разделе «Использование и выставление счетов» .

  7. Получив ключ API, добавьте его в следующий фрагмент кода, нажав на кнопку "ВАШ_КЛЮЧ_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>

Шаг 2: Создайте HTML-страницу

Вот код для простой HTML-страницы:

<!DOCTYPE html>
<!--
 @license
 Copyright 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Это очень простая HTML-страница, которая использует элемент gmp-map для отображения карты. Карта будет пустой, поскольку мы еще не добавили никакого кода JavaScript.

Разберитесь в коде.

На данном этапе примера мы имеем:

  • Приложение объявлено как HTML5 с помощью объявления !DOCTYPE html .
  • Загрузили JavaScript API карт с помощью загрузчика Bootstrap.
  • Создан элемент gmp-map для размещения карты.

Объявите ваше приложение как HTML5.

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

<!DOCTYPE html>

Большинство современных браузеров отображают контент, объявленный с помощью этого DOCTYPE в «стандартном режиме», что означает, что ваше приложение должно быть более кроссбраузерным. DOCTYPE также разработан для корректного отображения контента в случае его некорректного отображения; браузеры, которые его не понимают, будут игнорировать его и использовать «режим совместимости» для отображения своего контента.

Обратите внимание, что некоторые CSS-стили, работающие в режиме совместимости, недействительны в стандартном режиме. В частности, все размеры, заданные в процентах, должны наследоваться от родительских блочных элементов, и если какой-либо из этих предков не указывает размер, предполагается, что он равен 0 x 0 пикселям. По этой причине мы включаем следующее объявление style :

<style>
  gmp-map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Загрузите JavaScript API карт.

Загрузчик bootstrap подготавливает JavaScript API Maps к загрузке (библиотеки не загружаются до вызова функции importLibrary() ).

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

См. Шаг 3: Получение ключа API для получения инструкций по созданию собственного ключа API.

На этом этапе урока появляется пустое окно, отображающее только неформатированный текст метки. Это происходит потому, что мы еще не добавили никакого кода JavaScript.

Создайте элемент gmp-map

Для отображения карты на веб-странице необходимо зарезервировать для неё место. Обычно это делается путём создания элемента gmp-map и получения ссылки на этот элемент в объектной модели документа (DOM) браузера. Также можно использовать элемент div ( подробнее ), но рекомендуется использовать элемент gmp-map .

Приведённый ниже код определяет элемент gmp-map и задаёт параметры center , zoom и map-id .

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

Параметры center и zoom всегда обязательны. В приведенном выше коде свойство center указывает API, где следует центрировать карту, а свойство zoom задает уровень масштабирования карты. Zoom: 0 — это наименьший уровень масштабирования, отображающий всю Землю. Установите большее значение zoom, чтобы увеличить масштаб Земли с более высоким разрешением.

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

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

  • 1: Мир
  • 5: Суша или континент
  • 10: Город
  • 15: Улицы
  • 20: Здания

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

Приведённый ниже код описывает CSS-код, который задаёт размер элемента gmp-map .

/* Set the size of the gmp-map element that contains the map */
gmp-map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

В приведенном выше коде элемент style задает размер ` gmp-map . Установите ширину и высоту больше 0 пикселей, чтобы карта была видна. В данном случае gmp-map имеет высоту 400 пикселей и ширину 100%, чтобы отображаться по всей ширине веб-страницы. Рекомендуется всегда явно задавать стили высоты и ширины.

Управление слотами

Вы можете использовать слоты управления для добавления элементов управления HTML-формами на карту. Слот — это предопределенная позиция на карте; используйте атрибут slot , чтобы задать необходимую позицию для элемента, и вкладывайте элементы внутрь элемента gmp-map . Следующий фрагмент кода показывает добавление HTML-метки в верхний левый угол карты.