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

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

Загрузка с помощью 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();

Если вашему приложению требуется несколько библиотек одновременно, используйте 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 не будет загружаться, если не указать действительный ключ 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. Если вы хотите, чтобы ключ API могли использовать все страницы в домене или источнике, присвойте параметру значение authReferrerPolicy: "origin". Это ограничит объем данных, пересылаемых при авторизации запросов от Maps JavaScript API. Если параметр определен и ограничения по источнику ссылок HTTP включены в Cloud Console, Maps JavaScript API сможет загружаться только на страницах домена (без уточнения пути), которым предоставлен доступ.

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

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

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

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

Как добавить тег 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 для прямой загрузки скрипта

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

Обязательные параметры (прямые продажи)

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

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

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

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

  • auth_referrer_policy: Клиенты могут настроить ограничения по источнику ссылок 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

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

npm install @googlemaps/js-api-loader

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

TypeScript

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

JavaScript

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

Загрузчик использует промисы, чтобы сделать библиотеки доступными. Загружайте библиотеки с помощью метода 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();

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

Ознакомьтесь с полным примером кода.

Как перейти на 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() все запросы библиотеки инициируются одновременно, что снижает задержку сети и повышает скорость инициализации.