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

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

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

Как начать работу с Dynamic Library Import

Загрузите 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, как показано в следующем примере кода:

TypeScript

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

JavaScript

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

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

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

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

v – версия Maps JavaScript API, которую нужно загрузить.
libraries – дополнительные библиотеки Maps JavaScript API, которые нужно загрузить (список, разделенный запятыми). Как правило, использовать фиксированный набор библиотек не рекомендуется, но в этом случае разработчики могут точно настроить кеширование на сайте.
language – язык, который нужно использовать. Определяет отображение элементов интерфейса и управления картой, уведомлений об авторских правах, маршрутов и ответов на запросы к сервису. Вы можете ознакомиться со списком поддерживаемых языков.
region – код региона. От него зависит, как будет выглядеть карта той или иной страны или территории.
solutionChannel – используется для отслеживания работы с образцами кода, которые мы публикуем, чтобы помочь разработчикам освоиться с API. Параметр запроса solutionChannel включается в вызовы API, выполняемые из образцов кода.
authReferrerPolicy – ограничивает доступ к API по источнику ссылок HTTP, заданному пользователями Maps JS в Cloud Console (на страницах с какими URL будет срабатывать ключ API). Доступ можно ограничить только определенными адресами. Если вы хотите, чтобы ключ API могли использовать все страницы в домене или источнике, присвойте параметру значение authReferrerPolicy: "origin". Это ограничит объем данных, пересылаемых при авторизации запросов от Maps JavaScript API. Если параметр определен и ограничения по источнику ссылок HTTP включены в Cloud Console, Maps JavaScript 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() (метода Promise по умолчанию).

TypeScript

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

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.

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

Устаревший тег script для загрузки все ещё поддерживается. В этом разделе можно найти сведения для интеграций, в которых используется этот тег. Google рекомендует перейти на Dynamic Library Loading API.

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

Чтобы загрузить Maps JavaScript API в HTML-файле, добавьте тег script, как показано ниже.

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

Параметры URL для загрузки через тег script (устаревший вариант)

В этом разделе описаны все параметры, которые можно задать в строке запроса с URL для загрузки Maps JavaScript API. Обязательными являются не все параметры. Параметры разделяются амперсандами (&) в соответствии со стандартом написания URL.

В примере ниже приведен URL со всеми возможными параметрами и их условными значениями.

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

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

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

Обязательные параметры (для устаревшего тега script)

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

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

Необязательные параметры (для устаревшего тега script)

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

v – версия Maps JavaScript API, которую нужно использовать.
libraries – дополнительные библиотеки Maps JavaScript API, которые нужно загрузить (список, разделенный запятыми).
language – язык, который нужно использовать. Определяет отображение элементов интерфейса и управления картой, уведомлений об авторских правах, маршрутов и ответов на запросы к сервису. Вы можете ознакомиться со списком поддерживаемых языков.
region – код региона. От него зависит, как будет выглядеть карта той или иной страны или территории.
solution_channel – используется для отслеживания работы с образцами кода, которые мы публикуем, чтобы помочь разработчикам освоиться с API. Параметр запроса solution_channel включается в вызовы API, выполняемые из образцов кода.

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

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

В этом разделе описаны действия, необходимые для переноса интеграции на Dynamic Library Import API.

Этапы переноса

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

До

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&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();