Wczytywanie interfejsu Maps JavaScript API

Z tego przewodnika dowiesz się, jak wczytać interfejs Maps JavaScript API. Możesz to zrobić na 3 sposoby:

• Użyj dynamicznego importowania biblioteki.
• Użyj tagu bezpośredniego wczytywania skryptu.
• Użyj pakietu js-api-loader NPM.

Używanie dynamicznego importowania bibliotek

Importowanie bibliotek dynamicznych umożliwia wczytywanie bibliotek w czasie działania. Dzięki temu możesz żądać potrzebnych bibliotek w momencie, gdy są potrzebne, a nie wszystkich naraz podczas wczytywania. Zapobiega też wielokrotnemu wczytywaniu interfejsu Maps JavaScript API na stronie.

Wczytaj interfejs Maps JavaScript API, dodając do kodu aplikacji wbudowane narzędzie do wczytywania, jak pokazano w tym fragmencie kodu:

<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>

Możesz też dodać kod narzędzia do wczytywania bezpośrednio do kodu JavaScript.

Aby wczytać biblioteki w czasie działania, użyj operatora await do wywołania importLibrary() z funkcji async. Zadeklarowanie zmiennych dla potrzebnych klas pozwala pominąć użycie ścieżki kwalifikowanej (np. google.maps.Map), jak pokazano w tym przykładowym kodzie:

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

Jeśli aplikacja potrzebuje kilku bibliotek jednocześnie, użyj Promise.all(), aby zażądać ich równolegle:

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

Unikaj wywoływania funkcji await google.maps.importLibrary() w osobnych wierszach po kolei. Sekwencyjne instrukcje await blokują wykonywanie, dopóki każda biblioteka nie zostanie pobrana i zainicjowana, zanim zostanie wysłane żądanie kolejnej. Powoduje to powstanie kaskady sieciowej, która wydłuża czas wczytywania. Promise.all() rozpoczyna jednocześnie pobieranie wszystkich bibliotek i kończy działanie, gdy wszystkie są gotowe.

Funkcja może też wczytywać biblioteki bez deklarowania zmiennej dla potrzebnych klas, co jest szczególnie przydatne, jeśli dodasz mapę za pomocą elementu gmp-map. Bez zmiennej musisz używać ścieżek kwalifikowanych, na przykład 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();

Możesz też wczytać biblioteki bezpośrednio w kodzie HTML, jak pokazano poniżej:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Dowiedz się, jak przejść na interfejs Dynamic Library Loading API.

Wymagane parametry

• key: Twój klucz interfejsu API. Interfejs Maps JavaScript API nie zostanie wczytany, jeśli nie podasz prawidłowego klucza interfejsu API.

Parametry opcjonalne

• v: wersja interfejsu Maps JavaScript API, która ma zostać wczytana. Jeśli nie określisz wyraźnie kanału ani wersji, domyślnie będziesz otrzymywać wersje z kanału tygodniowego. Jeśli przeniesiesz się z abonamentu Premium i nie określisz kanału ani wersji, domyślnie otrzymasz kanał kwartalny. Jeśli podasz nieprawidłową wersję, otrzymasz kanał domyślny. Więcej informacji

• libraries: tablica dodatkowych bibliotek Maps JavaScript API, które mają być wstępnie wczytywane. Określanie stałego zestawu bibliotek nie jest ogólnie zalecane, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować działanie pamięci podręcznej w swojej witrynie. Nadal ważne jest, aby przed użyciem wywołać funkcję google.maps.importLibrary() dla każdej wybranej biblioteki.

• language: język, którego chcesz użyć. Ma to wpływ na nazwy elementów sterujących, powiadomienia o prawach autorskich, wskazówki dojazdu i etykiety elementów sterujących oraz odpowiedzi na zapytania o usługę. Zobacz listę obsługiwanych języków.

• region: kod regionu, którego chcesz użyć. Zmienia to działanie interfejsu API w zależności od danego kraju lub terytorium.

• authReferrerPolicy: klienci Maps JS mogą skonfigurować ograniczenia dotyczące odsyłających adresów HTTP w konsoli Cloud, aby ograniczyć adresy URL, które mogą używać określonego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby tylko określone ścieżki mogły używać klucza interfejsu API. Jeśli klucza interfejsu API może używać dowolny adres URL w tej samej domenie lub tym samym źródle, możesz ustawić authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu Maps JavaScript API. Gdy ten parametr jest określony, a w konsoli Cloud są włączone ograniczenia dotyczące stron odsyłających HTTP, interfejs Maps JavaScript API będzie mógł się wczytać tylko wtedy, gdy istnieje ograniczenie dotyczące stron odsyłających HTTP, które pasuje do domeny bieżącej witryny bez określonej ścieżki.

• mapIds: tablica identyfikatorów map. Powoduje wstępne wczytanie konfiguracji określonych identyfikatorów map. Podanie identyfikatorów map nie jest wymagane do ich używania, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

• channel: patrz Śledzenie wykorzystania na kanał.

Używanie tagu bezpośredniego wczytywania skryptu

W tej sekcji dowiesz się, jak używać tagu bezpośredniego wczytywania skryptu. Skrypt bezpośredni wczytuje biblioteki podczas wczytywania mapy, więc może uprościć mapy utworzone za pomocą elementu gmp-map, eliminując konieczność jawnego żądania bibliotek w czasie działania. Tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki jednocześnie, co może mieć wpływ na wydajność niektórych aplikacji. Tag bezpośredniego wczytywania skryptu powinien być uwzględniany tylko raz na każde wczytanie strony.

Uwaga: funkcję importLibrary możesz wywołać po zakończeniu wczytywania tagu bezpośredniego wczytywania skryptu.

Dodawanie tagu skryptu

Aby wczytać interfejs Maps JavaScript API w pliku HTML, dodaj tag script, jak pokazano poniżej.

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

Parametry adresu URL bezpośredniego wczytywania skryptu

W tej sekcji omówiono wszystkie parametry, które można określić w ciągu zapytania adresu URL wczytywania skryptu podczas wczytywania interfejsu Maps JavaScript API. Niektóre parametry są wymagane, a inne opcjonalne. Zgodnie ze standardem adresów URL wszystkie parametry są rozdzielone znakiem ampersand (&).

Poniższy przykładowy adres URL zawiera obiekty zastępcze dla wszystkich możliwych parametrów:

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"

URL w poniższym przykładowym tagu script wczytuje interfejs Maps JavaScript API:

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

Parametry wymagane (bezpośrednie)

Podczas wczytywania interfejsu Maps JavaScript API wymagane są te parametry.

• key: Twój klucz interfejsu API. Interfejs Maps JavaScript API nie zostanie wczytany, jeśli nie podasz prawidłowego klucza interfejsu API.

Parametry opcjonalne (bezpośrednie)

Użyj tych parametrów, aby poprosić o określoną wersję interfejsu Maps JavaScript API, wczytać dodatkowe biblioteki, zlokalizować mapę lub określić zasadę sprawdzania strony odsyłającej HTTP.

• loading: strategia wczytywania kodu, której może używać Maps JavaScript API. Ustaw wartość async, aby wskazać, że interfejs Maps JavaScript API nie został wczytany synchronicznie i że zdarzenie load skryptu nie wywołuje żadnego kodu JavaScript. Zdecydowanie zalecamy ustawienie tej opcji na async, gdy tylko jest to możliwe, aby zwiększyć wydajność. (Zamiast tego użyj parametru callback, aby wykonywać działania, gdy interfejs Maps JavaScript API jest dostępny). Dostępne od wersji 3.55.

• callback: nazwa funkcji globalnej, która ma zostać wywołana po całkowitym załadowaniu interfejsu Maps JavaScript API.

• v: wersja interfejsu Maps JavaScript API, której chcesz użyć.

• libraries: lista rozdzielona przecinkami dodatkowych bibliotek Maps JavaScript API do wczytania.

• language: język, którego chcesz użyć. Ma to wpływ na nazwy elementów sterujących, powiadomienia o prawach autorskich, wskazówki dojazdu i etykiety elementów sterujących, a także odpowiedzi na zapytania o usługę. Zobacz listę obsługiwanych języków.

• region: kod regionu, którego chcesz użyć. Zmienia to działanie interfejsu API w zależności od kraju lub terytorium.

• auth_referrer_policy: klienci mogą skonfigurować ograniczenia stron odsyłających HTTP w konsoli Cloud, aby ograniczyć adresy URL, które mogą używać określonego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby tylko określone ścieżki mogły używać klucza interfejsu API. Jeśli klucza interfejsu API może używać dowolny adres URL w tej samej domenie lub tym samym źródle, możesz ustawić auth_referrer_policy=origin, aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z Maps JavaScript API. Ta funkcja jest dostępna od wersji 3.46. Gdy ten parametr jest określony, a w konsoli Cloud są włączone ograniczenia dotyczące stron odsyłających HTTP, interfejs Maps JavaScript API będzie mógł się wczytać tylko wtedy, gdy istnieje ograniczenie dotyczące stron odsyłających HTTP, które pasuje do domeny bieżącej witryny bez określonej ścieżki.

• map_ids: rozdzielona przecinkami lista identyfikatorów map. Powoduje wstępne wczytanie konfiguracji określonych identyfikatorów map. Określanie identyfikatorów map nie jest wymagane do ich używania, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

• channel: patrz Śledzenie wykorzystania na kanał.

Używanie pakietu js-api-loader z NPM

Wskazówka: wersja v2.0.0 to duża refaktoryzacja, która zastępuje starą klasę Loader interfejsem API składającym się z 2 funkcji: setOptions() i importLibrary(). Ta zmiana umożliwia dynamiczne wczytywanie poszczególnych bibliotek interfejsu API Map Google na żądanie, co pozwala opóźnić pobieranie funkcji i poprawić początkową wydajność strony.

Pakiet @googlemaps/js-api-loader jest dostępny do wczytania za pomocą menedżera pakietów NPM. Zainstaluj go za pomocą tego polecenia:

npm install @googlemaps/js-api-loader

Zaimportuj pakiet w sposób pokazany poniżej:

TypeScript

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

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

JavaScript

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

Moduł ładujący używa obiektów Promise, aby udostępniać biblioteki. Wczytaj biblioteki za pomocą metody importLibrary(). Poniższy przykład pokazuje, jak użyć modułu ładującego do wczytania mapy:

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

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map 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

Zobacz kompletny przykładowy kod.

Przejście na interfejs Dynamic Library Import API

W tej sekcji opisujemy czynności, które należy wykonać, aby przeprowadzić migrację integracji i zacząć korzystać z interfejsu Dynamic Library Import API.

Kroki migracji

Najpierw zastąp tag bezpośredniego wczytywania skryptu tagiem wbudowanego narzędzia do wczytywania.

Przed

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

Po

<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>

Następnie zaktualizuj kod aplikacji:

• Zmień funkcję initMap() na asynchroniczną.
• Wywołaj importLibrary(), aby wczytać potrzebne biblioteki i uzyskać do nich dostęp.

Przed

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

Po

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

Wczytywanie wielu bibliotek

Aby wczytać więcej niż 1 bibliotekę, użyj Promise.all(), aby równolegle wysłać żądanie dotyczące bibliotek i rozbić zwrócone klasy:

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

Nie wczytuj bibliotek szeregowo przez łączenie oddzielnych instrukcji await:

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

Gdy wywołujesz await i importLibrary() jedno po drugim, drugie żądanie biblioteki nie rozpocznie się, dopóki pierwsza biblioteka nie zostanie całkowicie pobrana i zainicjowana. Użycie Promise.all() powoduje jednoczesne zainicjowanie wszystkich żądań biblioteki, co zmniejsza opóźnienie sieci i zwiększa szybkość inicjowania.