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

В этом руководстве показано, как загрузить JavaScript API для работы с картами. Это можно сделать тремя способами:

• Используйте динамический импорт библиотек.
• Используйте тег прямой загрузки скрипта.
• Используйте пакет NPM js-api-loader.

Используйте динамический импорт библиотек.

Динамический импорт библиотек обеспечивает возможность загрузки библиотек во время выполнения. Это позволяет запрашивать необходимые библиотеки в нужный момент, а не все сразу при загрузке страницы. Это также защищает вашу страницу от многократной загрузки JavaScript API карт.

Загрузите JavaScript API для работы с картами, добавив встроенный загрузчик Bootstrap в код вашего приложения, как показано в следующем фрагменте кода:

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

Вы также можете добавить код загрузчика Bootstrap непосредственно в свой JavaScript-код.

Для загрузки библиотек во время выполнения используйте оператор await , чтобы вызвать importLibrary() из async функции. Объявление переменных для необходимых классов позволяет обойтись без указания полного пути (например, google.maps.Map ), как показано в следующем примере кода:

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();
index.js

Ваша функция также может загружать библиотеки без объявления переменной для необходимых классов, что особенно полезно, если вы добавили карту с помощью элемента gmp-map . Без переменной вам необходимо использовать полные пути, например, google.maps.Map :

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await google.maps.importLibrary("maps");
  await google.maps.importLibrary("marker");

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

В качестве альтернативы, вы можете загрузить библиотеки непосредственно в HTML, как показано здесь:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Узнайте, как перейти на API динамической загрузки библиотек .

Необходимые параметры

• key : Ваш API-ключ . API карт JavaScript не загрузится, если не указан действительный API-ключ.

Дополнительные параметры

• v : Версия JavaScript API для карт, которую необходимо загрузить.

• libraries : Массив дополнительных библиотек JavaScript API для карт, которые будут предварительно загружены. Указывать фиксированный набор библиотек обычно не рекомендуется, но такая возможность доступна для разработчиков, желающих точно настроить поведение кэширования на своем веб-сайте. Тем не менее, важно вызвать google.maps.importLibrary() для каждой выбранной библиотеки перед ее использованием.

• language : Язык , который следует использовать. Это влияет на названия элементов управления, уведомления об авторских правах, указания по управлению и метки элементов управления, а также на ответы на запросы к сервису. См. список поддерживаемых языков .

• region : Код региона для использования. Это изменяет поведение API в зависимости от конкретной страны или территории.

• authReferrerPolicy : Пользователи Maps JS могут настроить ограничения HTTP Referrer в Cloud Console, чтобы ограничить круг URL-адресов, которым разрешено использовать определенный ключ API. По умолчанию эти ограничения можно настроить таким образом, чтобы разрешить использование ключа API только определенным путям. Если любой URL-адрес в том же домене или источнике может использовать ключ API, вы можете установить authReferrerPolicy: "origin" , чтобы ограничить объем данных, отправляемых при авторизации запросов к Maps JavaScript API. Если этот параметр указан и ограничения HTTP Referrer включены в Cloud Console, Maps JavaScript API сможет загружаться только в том случае, если существует ограничение HTTP Referrer , соответствующее домену текущего веб-сайта без указанного пути.

• mapIds : Массив идентификаторов карт. Приводит к предварительной загрузке конфигурации для указанных идентификаторов карт. Указание идентификаторов карт здесь не является обязательным для их использования, но доступно разработчикам, которые хотят точно настроить производительность сети.

• channel : см. Отслеживание использования по каждому каналу .

• internalUsageAttributionIds : Массив идентификаторов атрибуции использования, который помогает Google понять, какие библиотеки и примеры полезны для разработчиков, например, использование библиотеки кластеризации маркеров. Чтобы отказаться от отправки идентификатора атрибуции использования, можно удалить это свойство или установить значение в пустой массив ( [] ). Будут отправляться только уникальные значения. Дополнительную информацию см. в параметре решений Google Maps Platform .

Примечание: Параметр solutionChannel по-прежнему действителен, но не рекомендуется. Вместо него используйте internalUsageAttributionIds .

Используйте тег прямой загрузки скрипта.

В этом разделе показано, как использовать тег прямой загрузки скрипта. Поскольку прямой скрипт загружает библиотеки при загрузке карты, он может упростить создание карт с помощью элемента gmp-map , устраняя необходимость явного запроса библиотек во время выполнения. Однако, поскольку тег прямой загрузки скрипта загружает все запрошенные библиотеки одновременно при загрузке скрипта, это может повлиять на производительность некоторых приложений. Включайте тег прямой загрузки скрипта только один раз за загрузку страницы.

Примечание: Вы можете вызвать importLibrary после того, как завершится загрузка тега прямой загрузки скрипта.

Добавьте тег <script>

Чтобы загрузить JavaScript API карт непосредственно в HTML-файл, добавьте тег script , как показано ниже.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Прямая загрузка параметров URL-адреса скриптом

В этом разделе рассматриваются все параметры, которые можно указать в строке запроса URL-адреса загрузки скрипта при загрузке API JavaScript для карт. Некоторые параметры являются обязательными, другие — необязательными. Как это принято в URL-адресах, все параметры разделяются символом амперсанда ( & ).

В приведенном ниже примере URL-адреса содержатся заполнители для всех возможных параметров:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

В приведенном ниже примере тега script URL-адрес загружает JavaScript API для работы с картами:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Обязательные параметры (прямой доступ) {:.hide-from-toc}

Для загрузки JavaScript API карт необходимы следующие параметры.

• key : Ваш API-ключ . API карт JavaScript не загрузится, если не указан действительный API-ключ.

Необязательные параметры (прямой) {:.hide-from-toc}

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

• loading : Стратегия загрузки кода, которую может использовать JavaScript API карт. Установите значение async , чтобы указать, что JavaScript API карт не был загружен синхронно и что событие load скрипта не запускает никакой JavaScript-код. Настоятельно рекомендуется по возможности устанавливать значение async для повышения производительности. (Вместо этого используйте параметр callback для выполнения действий, когда JavaScript API карт доступен.) Доступно начиная с версии 3.55.

• callback : Имя глобальной функции, которая будет вызвана после полной загрузки JavaScript API карт.

• v : Версия JavaScript API для работы с картами, которую следует использовать.

• libraries : Список дополнительных библиотек JavaScript API для работы с картами, разделенных запятыми, для загрузки.

• language : Язык , который будет использоваться. Это влияет на названия элементов управления, уведомления об авторских правах, указания по управлению и метки элементов управления, а также на ответы на запросы к сервису. См. список поддерживаемых языков .

• region : Код региона для использования. Это изменяет поведение API в зависимости от конкретной страны или территории.

• auth_referrer_policy : Клиенты могут настроить ограничения HTTP Referrer в Cloud Console, чтобы ограничить круг URL-адресов, которым разрешено использовать определенный ключ API. По умолчанию эти ограничения можно настроить таким образом, чтобы разрешить использование ключа API только определенным путям. Если любой URL-адрес в том же домене или источнике может использовать ключ API, вы можете установить auth_referrer_policy=origin , чтобы ограничить объем данных, отправляемых при авторизации запросов к Maps JavaScript API. Эта функция доступна начиная с версии 3.46. Если этот параметр указан и ограничения HTTP Referrer включены в Cloud Console, Maps JavaScript API сможет загружаться только в том случае, если существует ограничение HTTP Referrer , соответствующее домену текущего веб-сайта без указанного пути.

• map_ids : Список идентификаторов карт, разделенных запятыми. Это приводит к предварительной загрузке конфигурации для указанных идентификаторов карт. Указание идентификаторов карт здесь не является обязательным для их использования, но доступно разработчикам, желающим точно настроить производительность сети.

• channel : см. Отслеживание использования по каждому каналу .

• internal_usage_attribution_ids : Список идентификаторов атрибуции использования, разделенных запятыми, которые помогают Google понять, какие библиотеки и примеры полезны для разработчиков, например, использование библиотеки кластеризации маркеров. Чтобы отказаться от отправки идентификатора атрибуции использования, можно удалить это свойство или заменить значение пустой строкой. Будут отправляться только уникальные значения. Дополнительную информацию см. в параметре решений Google Maps Platform .

Примечание: Параметр solution_channel по-прежнему действителен, но не рекомендуется. Вместо него используйте internal_usage_attribution_ids .

Используйте пакет NPM js-api-loader.

Совет: В версии 2.0.0 выполнена масштабная переработка кода, в результате которой старый класс Loader заменен API, состоящим из двух функций: setOptions() и importLibrary() . Это изменение обеспечивает динамическую загрузку отдельных библиотек Maps API по запросу, откладывая загрузку объектов для повышения производительности при первоначальной загрузке страниц.

Пакет @googlemaps/js-api-loader доступен для загрузки с помощью менеджера пакетов NPM. Установите его, используя следующую команду:

npm install @googlemaps/js-api-loader

Импортируйте пакет, как показано здесь:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader"

Загрузчик использует промисы для предоставления доступа к библиотекам. Загрузка библиотек осуществляется с помощью метода importLibrary() . В следующем примере показано, как использовать загрузчик для загрузки карты:

Машинопись

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function initMap(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });

    // Load the Maps library.
    const { Map } = (await importLibrary('maps')) as google.maps.MapsLibrary;

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();
index.ts

Примечание: Ознакомьтесь с руководством по использованию TypeScript и Google Maps.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));
    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };
    // Declare the map.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();
index.js

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

Переход на API динамического импорта библиотек

В этом разделе описаны шаги, необходимые для миграции вашей интеграции на использование API динамического импорта библиотек.

Этапы миграции

Во-первых, замените тег прямой загрузки скрипта на встроенный тег загрузчика Bootstrap.

До

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

После

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

Далее обновите код вашего приложения:

• Измените функцию initMap() на асинхронную.
• Вызовите importLibrary() для загрузки и доступа к необходимым библиотекам.

До

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

После

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();