В этом руководстве рассказывается, как загрузить 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();
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();
Обязательные параметры
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, }); });
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, }); });
Ознакомьтесь с примером, в котором используется 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"
®ion="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, выполняемые из образцов кода.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();