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

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

• Использовать динамический импорт библиотеки
• Используйте тег прямой загрузки скрипта
• Используйте пакет 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: google.maps.Map;
async function initMap(): Promise<void> {
  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,
  });
}

initMap();
index.ts

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 :

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

initMap();

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

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

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

Обязательные параметры

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

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

• v : версия API JavaScript Карт для загрузки.

• libraries : разделенный запятыми список дополнительных библиотек Maps JavaScript API для загрузки. Указание фиксированного набора библиотек обычно не рекомендуется, но доступно разработчикам, которые хотят точно настроить поведение кэширования на своем веб-сайте.

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

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

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

• mapIds : Массив идентификаторов карт. Вызывает предварительную загрузку конфигурации для указанных идентификаторов карт.

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

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

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

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

Добавить тег сценария

Чтобы загрузить 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 загружает Maps JavaScript API:

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

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

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

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

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

• v : используемая версия Maps JavaScript API.

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

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

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

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

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

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

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

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

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

npm install @googlemaps/js-api-loader

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

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

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

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