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

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

• Используйте Dynamic Library Import.
• использовать тег для прямой загрузки скрипта;
• использовать пакет NPM js-api-loader;

Загрузка с помощью Dynamic Library Import API

Dynamic Library Import API позволяет загружать библиотеки во время выполнения. Это позволяет запрашивать нужные библиотеки в тот момент, когда они необходимы, а не все сразу во время загрузки. Кроме того, он защищает страницу от многократной загрузки 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), как показано в следующем примере кода:

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();
index.js

Если вашему приложению требуется несколько библиотек одновременно, используйте Promise.all(), чтобы запросить их параллельно:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

Не вызывайте функцию await google.maps.importLibrary() на разных строках последовательно. Последовательные операторы await блокируют выполнение, пока каждая библиотека не будет скачана и инициализирована, прежде чем запрашивать следующую, создавая каскадную сеть, которая увеличивает время загрузки. Promise.all() запускает скачивание всех библиотек одновременно и завершает работу, когда они готовы.

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

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

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    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>

Подробнее о том, как перейти на Dynamic Library Loading API…

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

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

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

• v – версия Maps JavaScript API, которую нужно загрузить. Если версия обновления или ее номер не указаны явно, по умолчанию используется недельная версия. Если при переходе с плана Premium вы не укажете предпочтительную версию или ее номер, по умолчанию будет выбрана квартальная версия. Если указанное значение недействительно, будет применена версия по умолчанию. Подробнее…

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

• language – язык, который нужно использовать. Определяет отображение элементов интерфейса и управления картой, уведомлений об авторских правах, маршрутов и ответов на запросы к сервису. Вы можете ознакомиться со списком поддерживаемых языков.

• region – код региона. От него зависит, как будет выглядеть карта той или иной страны или территории.

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

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

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

Как использовать тег script для прямой загрузки

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

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

Как добавить тег script

Чтобы загрузить 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 для загрузки через тег script (прямой вариант)

В этом разделе описаны все параметры, которые можно задать в строке запроса с 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"

В следующем примере тег script загружает Maps JavaScript API по указанному в нём URL:

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

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

Перечисленные ниже параметры обязательны для загрузки Maps JavaScript API.

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

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

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

• loading – стратегия загрузки кода, которую может использовать Maps JavaScript API. Значение async указывает, что Maps JavaScript API не загружен синхронно и что событие load не запускает код JavaScript. Мы настоятельно рекомендуем по возможности задавать значение async, чтобы повысить эффективность. Чтобы выполнять действия, когда Maps JavaScript API доступен, используйте параметр callback. Доступно в версии 3.55 и более поздних.

• callback – глобальная функция, которую нужно вызвать по окончании загрузки Maps JavaScript API.

• v – версия Maps JavaScript API, которую нужно использовать.

• libraries – дополнительные библиотеки Maps JavaScript API, которые нужно загрузить (список, разделенный запятыми).

• language – язык, который нужно использовать. Определяет отображение элементов интерфейса и управления картой, уведомлений об авторских правах, маршрутов и ответов на запросы к сервису. Вы можете ознакомиться со списком поддерживаемых языков.

• region – код региона. От него зависит, как будет работать API в той или иной стране или территории.

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

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

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

Как использовать пакет NPM js-api-loader

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

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

npm install @googlemaps/js-api-loader

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

TypeScript

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

Примечание. Ознакомьтесь с руководством по работе с TypeScript в Google Картах.

JavaScript

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

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

TypeScript

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

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

    // 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.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();
index.ts

Примечание. Ознакомьтесь с руководством по работе с TypeScript в Google Картах.

JavaScript

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // 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.
    new Map(document.getElementById('map'), mapOptions);
}

void init();
index.js

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

Как перейти на Dynamic Library Import API

В этом разделе описаны действия, необходимые для переноса интеграции на Dynamic Library Import 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();

Как загрузить несколько библиотек

Чтобы загрузить несколько библиотек, используйте Promise.all() для параллельного запроса библиотек и деструктурируйте возвращенные классы:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

Не загружайте библиотеки последовательно, объединяя отдельные операторы await:

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

Если вы await каждый вызов importLibrary() один за другим, второй запрос библиотеки не начнется, пока первая библиотека не будет полностью загружена и инициализирована. При использовании Promise.all() все запросы библиотек инициируются одновременно, что снижает задержку сети и повышает скорость инициализации.