Как добавить карту Google с маркером, используя JavaScript

Введение

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

Ниже показана карта, которая будет использоваться в качестве примера. Маркером отмечена скала Улуру в австралийском национальном парке Улуру – Ката-Тьюта.

Начало работы

Процесс создания встроенной в веб-страницу карты Google с маркером состоит из трех этапов:

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

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

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

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

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

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

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

  3. Нажмите Continue (Продолжить) для активации API и всех связанных сервисов.

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

  5. Узнайте, как защитить доступные ресурсы от посторонних и обезопасить ключ 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 с помощью начального загрузчика.
  • Создайте элемент gmp-map, который будет содержать карту.

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

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

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

Начальный загрузчик подготавливает Maps JavaScript API к загрузке (до вызова 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.

На этом этапе в окне будет показан только неформатированный текст ярлыка. Это связано с тем, что мы ещё не добавили код 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 задает уровень масштабирования карты. Нулю соответствует самый мелкий масштаб (пользователь видит на экране всю планету). Чем больше значение свойства, тем крупнее масштаб видимой карты.

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

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

  • 1: мир;
  • 5: континент;
  • 10: город;
  • 15: улицы;
  • 20: здания.

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

Код ниже задает размер элемента gmp-map с помощью стиля CSS.

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

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

Шаг 3. Добавьте код JavaScript

В этом разделе показано, как загрузить Maps JavaScript API на веб-страницу и написать собственный код JavaScript, который использует API для добавления карты с маркером.

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

При вызове initMap() приведенный выше код выполняет следующие действия:

  • Загружает библиотеки maps и marker.
  • Получает элемент карты из DOM.
  • Задает дополнительные параметры карты для внутренней карты.
  • Добавляет маркер на карту.

Получение объекта карты и настройка параметров

innerMap представляет экземпляр класса Map. Чтобы задать настройки карты, получите экземпляр innerMap из элемента карты и вызовите setOptions. В следующем фрагменте кода показано, как получить экземпляр innerMap из DOM, а затем вызвать setOptions.

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Дождитесь загрузки карты.

При использовании элемента gmp-map карта загружается асинхронно. Это может привести к состоянию гонки, если во время инициализации выполняются другие запросы (например, геолокации или информации о месте). Чтобы код выполнялся только после полной загрузки карты, используйте обработчик событий addListenerOnce в функции инициализации, как показано ниже.

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

Это гарантирует, что код будет выполнен только после загрузки карты. Обработчик запускается только один раз за жизненный цикл приложения.

Полный пример кода

Полный пример кода:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-map {
    height: 100%;
}

/*
   * Optional: Makes the sample page fill the window.
   */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <!-- The map, centered at Uluru, Australia. -->
        <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
            <div id="controls" slot="control-inline-start-block-start">
                <h3>My Google Maps Demo</h3>
            </div>
        </gmp-map>
    </body>
</html>

Подробнее о маркерах:

Советы и устранение неполадок

  • Узнайте, как получить координаты широты и долготы или преобразовать адрес в географические координаты.
  • Чтобы настроить отображение карты, меняйте стиль, свойства и другие переменные. Подробную информацию можно найти в руководствах по стилю и рисованию на карте.
  • Пользуйтесь консолью инструментов разработчика в браузере, чтобы тестировать и запускать свой код, просматривать отчеты об ошибках и устранять проблемы.
  • Открыть консоль в Chrome можно сочетанием клавиш:
    Command + Option + J (Mac) или Control + Shift + J (Windows).

  • Чтобы получить географические координаты (широту и долготу) точки на Google Картах:

    1. Откройте Google Карты в браузере.
    2. Нажмите правой кнопкой мыши на точку, координаты которой хотите получить.
    3. Выберите координаты широты и долготы в меню.

  • Преобразовать адрес в географические координаты можно с помощью сервиса геокодирования. В руководствах для разработчиков представлена подробная информация о том, как начать работу с сервисом геокодирования.