Добавьте карту 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 без ограничений или ключ с ограничениями для браузера, вы можете использовать его.

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

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

  7. Получив ключ API, добавьте его в следующий фрагмент кода, нажав «YOUR_API_KEY». Скопируйте и вставьте тег скрипта загрузчика, чтобы использовать его на своей веб-странице.

    <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 .
  • Загрузил Maps JavaScript API с помощью загрузчика bootstrap.
  • Создан элемент gmp-map для хранения карты.

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

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

<!DOCTYPE html>

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

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

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

Загрузите API JavaScript Карт

Загрузчик начальной загрузки подготавливает API JavaScript Карт к загрузке (библиотеки не загружаются до тех пор, пока не будет вызван 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>

Инструкции по получению собственного ключа API см. в разделе Шаг 3: Получите ключ 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 — минимальный масштаб, отображающий всю Землю. Увеличьте значение масштабирования, чтобы увеличить масштаб изображения Земли при более высоком разрешении.

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

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

  • 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-метки в левый верхний угол карты.