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

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

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

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

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

Подробнее о том, как перейти на 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: отслеживание использования по каналам.

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

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

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

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

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

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

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

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

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

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

• auth_referrer_policy – ограничивает доступ к API по источнику ссылок HTTP, заданному пользователями в Cloud Console (на страницах с какими URL будет срабатывать ключ 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

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