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

Это руководство показывает, как загрузить Maps JavaScript API. Есть три способа сделать это:

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

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

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

Вы также можете добавить код загрузчика начальной загрузки непосредственно в свой код 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 : Массив дополнительных библиотек Maps JavaScript API для загрузки. Указание фиксированного набора библиотек обычно не рекомендуется, но доступно для разработчиков, которые хотят точно настроить поведение кэширования на своем веб-сайте.

• 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 : см. Отслеживание использования по каналу .

• solutionChannel : Платформа Google Карт предоставляет множество типов образцов кода, которые помогут вам быстро приступить к работе. Чтобы отслеживать внедрение наших более сложных образцов кода и повышать качество решения, Google включает параметр запроса solutionChannel в вызовы API в нашем образце кода.

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

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

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

Добавить тег скрипта

Чтобы загрузить Maps 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 загрузки скрипта при загрузке Maps JavaScript API. Некоторые параметры являются обязательными, а другие — необязательными. Как это принято в 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"

URL-адрес в следующем примере тега script загружает API JavaScript Карт:

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

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

При загрузке Maps JavaScript API требуются следующие параметры.

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

Необязательные параметры (прямые)

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

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

• callback : имя глобальной функции, которая будет вызвана после полной загрузки Maps 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, которое соответствует домену текущего веб-сайта без указанного пути.

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

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

• solution_channel : Платформа Google Карт предоставляет множество типов образцов кода, которые помогут вам быстро приступить к работе. Чтобы отслеживать внедрение наших более сложных образцов кода и повышать качество решения, Google включает параметр запроса solution_channel в вызовы API в нашем образце кода.

  Примечание: Этот параметр запроса предназначен для использования Google. См. параметр решений Google Maps Platform для получения дополнительной информации.

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

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

npm install @googlemaps/js-api-loader

Этот пакет можно импортировать в приложение с помощью:

import { Loader } from "@googlemaps/js-api-loader"

Загрузчик предоставляет интерфейс Promise и обратного вызова. Ниже показано использование метода 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,
  });
});
index.ts

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

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

Посмотрите пример с использованием js-api-loader.

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

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

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

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

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

Сначала замените тег прямой загрузки скрипта на тег встроенного загрузчика.

До

<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();