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 importu biblioteki
• użyj tagu bezpośredniego wczytywania skryptu
• użyj pakietu js-api-loader NPM.

Używanie dynamicznego importu biblioteki

Dynamiczny import biblioteki umożliwia wczytywanie bibliotek w czasie działania. Dzięki temu możesz poprosić o potrzebne biblioteki w momencie, gdy ich potrzebujesz, a nie wszystkie naraz podczas wczytywania. Chroni to też stronę przed wielokrotnym wczytywaniem interfejsu Maps JavaScript API.

Aby wczytać interfejs Maps JavaScript API, dodaj do kodu aplikacji wbudowany program wczytujący, 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>

Kod programu wczytującego możesz też dodać bezpośrednio do kodu JavaScript.

Aby wczytać biblioteki w czasie działania, użyj operatora await, aby wywołać importLibrary() w funkcji async. Deklarowanie zmiennych dla potrzebnych klas pozwala pominąć używanie kwalifikowanej ścieżki (np. google.maps.Map), jak pokazano w tym przykładzie kodu:

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 poprosić o nie równolegle:

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

Unikaj wywoływania await google.maps.importLibrary() w kolejnych wierszach. Kolejne instrukcje await blokują wykonywanie, dopóki każda biblioteka nie zostanie pobrana i zainicjowana, zanim zostanie wysłane żądanie następnej biblioteki, co tworzy kaskadę sieciową, która zwiększa czas wczytywania. Promise.all() rozpoczyna pobieranie wszystkich bibliotek jednocześnie i rozwiązuje je, gdy wszystkie są gotowe.

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

Biblioteki możesz też wczytać bezpośrednio w kodzie HTML, jak pokazano tutaj:

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

Dowiedz się, jak przeprowadzić migrację do interfejsu Dynamic Library Loading API.

Wymagane parametry

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

Parametry opcjonalne

• v: Wersja interfejsu Maps JavaScript API do wczytania. Jeśli nie określisz wyraźnie kanału ani wersji, domyślnie otrzymasz kanał tygodniowy. Jeśli przeprowadzisz migrację z planu Premium i nie określisz wyraźnie kanału ani wersji, domyślnie otrzymasz kanał kwartalny. Jeśli określisz nieprawidłową wersję, otrzymasz domyślny kanał. Więcej informacji.

• libraries: tablica dodatkowych bibliotek interfejsu Maps JavaScript API , które mają zostać wstępnie wczytane. 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. Przed użyciem każdej wybranej biblioteki nadal trzeba wywołać google.maps.importLibrary().

• language: język do użycia. Wpływa to na nazwy elementów sterujących, powiadomienia o prawach autorskich, wskazówki dojazdu, etykiety elementów sterujących i odpowiedzi na zapytania o usługę. Zobacz listę obsługiwanych języków.

• region: Kod regionu do użycia. Zmienia to działanie interfejsu API na podstawie danego kraju lub terytorium.

• authReferrerPolicy: klienci Maps JS mogą skonfigurować ograniczenia strony odsyłającej 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 dowolny adres URL w tej samej domenie lub źródle może używać klucza interfejsu API, 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 włączone są ograniczenia strony odsyłającej HTTP, interfejs Maps JavaScript API będzie można wczytać tylko wtedy, gdy istnieje ograniczenie strony odsyłającej 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. 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: zobacz Śledzenie wykorzystania według kanału.

Używanie tagu bezpośredniego wczytywania skryptu

W tej sekcji dowiesz się, jak używać tagu bezpośredniego wczytywania skryptu. Ponieważ skrypt bezpośredni wczytuje biblioteki podczas wczytywania mapy, może uprościć mapy utworzone za pomocą elementu gmp-map, eliminując konieczność wyraźnego żądania bibliotek w czasie działania. Ponieważ tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki jednocześnie podczas wczytywania skryptu, w przypadku niektórych aplikacji może to mieć wpływ na wydajność. Tag bezpośredniego wczytywania skryptu należy umieścić tylko raz na wczytanie strony.

Dodawanie tagu skryptu

Aby wczytać interfejs Maps JavaScript API wbudowany w plik 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ówimy wszystkie parametry, które możesz 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ą oddzielone znakiem ampersand (&).

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

Adres URL w tym 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>

Wymagane parametry (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 zostanie podany prawidłowy klucz 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ć interfejs Maps JavaScript API. Ustaw wartość async, aby wskazać, że interfejs Maps JavaScript API nie został wczytany synchronicznie i że żadna część kodu JavaScript nie jest wywoływana przez zdarzenie load skryptu. Aby zwiększyć wydajność, zalecamy ustawienie tej wartości na async zawsze, gdy jest to możliwe. (Aby wykonywać działania, gdy interfejs Maps JavaScript API jest dostępny, użyj parametru callback.) Dostępne od wersji 3.55.

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

• v: wersja interfejsu Maps JavaScript API do użycia.

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

• language: język do użycia. Wpływa to na nazwy elementów sterujących, powiadomienia o prawach autorskich, wskazówki dojazdu, etykiety elementów sterujących i odpowiedzi na zapytania o usługę. Zobacz listę obsługiwanych języków.

• region: Kod regionu do użycia. Zmienia to działanie interfejsu API na podstawie danego kraju lub terytorium.

• auth_referrer_policy: klienci mogą skonfigurować ograniczenia strony odsyłającej 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 dowolny adres URL w tej samej domenie lub źródle może używać klucza interfejsu API, możesz ustawić auth_referrer_policy=origin, aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu Maps JavaScript API. Jest to dostępne od wersji 3.46. Gdy ten parametr jest określony, a w Konsoli Cloud włączone są ograniczenia strony odsyłającej HTTP, interfejs Maps JavaScript API będzie można wczytać tylko wtedy, gdy istnieje ograniczenie strony odsyłającej 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: zobacz Śledzenie wykorzystania według kanału.

Używanie pakietu js-api-loader NPM

Dostępny jest pak0iet @googlemaps/js-api-loader, który można wczytać za pomocą menedżera pakietów NPM. Zainstaluj go za pomocą tego polecenia:

npm install @googlemaps/js-api-loader

Zaimportuj pakiet, jak pokazano tutaj:

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

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

Program wczytujący używa obietnic, aby udostępniać biblioteki. Wczytaj biblioteki za pomocą metody importLibrary(). Ten przykład pokazuje, jak użyć programu wczytującego do wczytania mapy:

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

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

Migracja do interfejsu Dynamic Library Import API

W tej sekcji opisujemy kroki wymagane do przeprowadzenia migracji integracji, aby 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ć i uzyskać dostęp do potrzebnych bibliotek.

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 poprosić o biblioteki równolegle, i rozpakuj zwrócone klasy:

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

Nie wczytuj bibliotek szeregowo, łącząc oddzielne instrukcje await:

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

Gdy wywołujesz await dla każdego wywołania 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 zainicjowanie wszystkich żądań bibliotek w tym samym czasie, co zmniejsza opóźnienie sieci i przyspiesza inicjowanie.