Wczytywanie interfejsu Maps JavaScript API

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

Korzystanie z importu dynamicznej biblioteki

Dynamiczny import bibliotek umożliwia wczytywanie bibliotek w czasie wykonywania. Dzięki temu możesz wczytywać potrzebne biblioteki w chwili, gdy ich potrzebujesz, a nie wszystkie naraz w momencie wczytywania. Zapobiega też wielokrotnemu wczytywaniu interfejsu Maps JavaScript API przez stronę.

Wczytaj interfejs Maps JavaScript API, dodając do kodu aplikacji wbudowany bootstrap loader, 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 ładowania bootstrapa możesz też dodać bezpośrednio do kodu JavaScript.

Aby wczytać biblioteki w czasie wykonywania, użyj operatora await do wywołania funkcji importLibrary() z poziomu funkcji async. Deklarowanie zmiennych dla potrzebnych klas umożliwia pominięcie ścieżki kwalifikowanej (np. google.maps.Map), jak pokazano w tym przykładzie kodu:

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

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

Możesz też wczytać biblioteki bezpośrednio w HTML-u:

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

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

Wymagane parametry

  • key: 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 załadowania.

  • libraries: tablica dodatkowych bibliotek Maps JavaScript API do załadowania. Podawanie stałego zestawu bibliotek nie jest zalecane, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować działanie pamięci podręcznej w swojej witrynie.

  • language: język, którego chcesz użyć. Dotyczy to nazw elementów sterujących, powiadomień o prawach autorskich, wskazówek nawigacyjnych i etykietek elementów sterujących oraz odpowiedzi na żądania usługi. Zobacz listę obsługiwanych języków.

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

  • authReferrerPolicy: klienci korzystający z usługi Maps JS mogą skonfigurować w konsoli Google Cloud ograniczenia dotyczące odsyłającego adresu HTTP, aby ograniczyć listę adresów URL, które mogą używać konkretnego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby zezwalały na korzystanie z klucza API tylko w przypadku określonych ścieżek. Jeśli dowolny adres URL w tej samej domenie lub pochodzeniu może używać klucza interfejsu API, możesz ustawić wartość authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych podczas autoryzacji żądań z interfejsu Maps JavaScript API. Gdy ten parametr jest określony, a w Konsoli Google Cloud włączone są ograniczenia odsyłającego adresu HTTP, interfejs Maps JavaScript API będzie mógł się wczytać tylko wtedy, gdy istnieje ograniczenie odsyłającego adresu HTTP, które pasuje do domeny bieżącej witryny bez określonej ścieżki.

  • mapIds: tablica identyfikatorów map. Spowoduje wstępne załadowanie konfiguracji dla określonych identyfikatorów map. Podawanie identyfikatorów map nie jest wymagane, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

  • channel: zobacz śledzenie wykorzystania na poszczególnych kanałach.

  • solutionChannel: Google Maps Platform udostępnia wiele typów przykładowego kodu, aby ułatwić Ci szybkie rozpoczęcie pracy. Aby śledzić stosowanie bardziej złożonych przykładowych fragmentów kodu i ulepszać jakość rozwiązań, Google uwzględnia parametr zapytania solutionChannel w przykładowym kodzie w wywołaniach interfejsu API.

Używanie tagu bezpośredniego wczytywania skryptu

Z 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, ponieważ nie trzeba już wyraźnie prosić o biblioteki w czasie wykonywania. Tag bezpośredniego wczytywania skryptu wczytuje wszystkie wymagane biblioteki od razu po załadowaniu skryptu, dlatego w niektórych aplikacjach może to mieć wpływ na wydajność. Dołącz tag bezpośredniego wczytywania skryptu tylko raz na stronę.

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 omawiamy wszystkie parametry, które możesz określić w serii zapytań w adresie URL wczytywania skryptu podczas wczytywania interfejsu Maps JavaScript API. Niektóre parametry są wymagane, a inne – opcjonalne. Zgodnie ze standardem w adresach URL wszystkie parametry są rozdzielane 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 tagu script w tym przykładzie 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: klucz interfejsu API. Interfejs Maps JavaScript API nie zostanie wczytany, chyba że podany zostanie prawidłowy klucz interfejsu API.

Parametry opcjonalne (bezpośrednie)

Użyj tych parametrów, aby zażądać określonej wersji interfejsu Maps JavaScript API, załadować dodatkowe biblioteki, zlokalizować mapę lub określić zasady sprawdzania strony odsyłającej HTTP.

  • loading: strategia ładowania kodu, której może używać Maps JavaScript API. Ustaw na async, aby wskazać, że interfejs Maps JavaScript API nie został wczytany synchronicznie i że żaden kod JavaScript nie jest wywoływany przez zdarzenie load skryptu. Zalecamy, aby w miarę możliwości ustawić tę wartość na async, ponieważ zwiększy to wydajność. (używaj zamiast tego parametru callback, aby wykonywać działania, gdy interfejs Maps JavaScript API jest dostępny). Dostępna od wersji 3.55.

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

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

  • libraries: lista oddzielonych przecinkami dodatkowych bibliotek interfejsu Maps JavaScript API do załadowania.

  • language: język, którego chcesz użyć. Dotyczy to nazw elementów sterujących, powiadomień o prawach autorskich, wskazówek nawigacyjnych i etykietek elementów sterujących, a także odpowiedzi na żądania dotyczące usługi. Zobacz listę obsługiwanych języków.

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

  • auth_referrer_policy: klienci mogą skonfigurować ograniczenia strony odsyłającej HTTP w Konsoli Google Cloud, aby ograniczyć listę adresów URL, które mogą używać określonego klucza API. Domyślnie te ograniczenia można skonfigurować tak, aby klucz interfejsu API mógł być używany tylko przez określone ścieżki. Jeśli dowolny adres URL w tej samej domenie lub pochodzeniu może używać klucza interfejsu API, możesz ustawić wartość auth_referrer_policy=origin, aby ograniczyć ilość danych wysyłanych podczas autoryzacji żądań z interfejsu 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 odesłań HTTP, interfejs Maps JavaScript API będzie mógł się wczytać tylko wtedy, gdy istnieje ograniczenie dotyczące odesłań HTTP, które pasuje do domeny bieżącej witryny bez określonej ścieżki.

  • mapIds: lista identyfikatorów map oddzielonych przecinkami. Spowoduje wstępne załadowanie konfiguracji dla określonych identyfikatorów map. Podanie identyfikatorów map nie jest wymagane do korzystania z tych identyfikatorów, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

  • channel: zobacz śledzenie wykorzystania według kanału.

  • solution_channel: Google Maps Platform udostępnia wiele typów przykładowego kodu, aby ułatwić Ci szybkie rozpoczęcie pracy. Aby śledzić stosowanie bardziej złożonych przykładowych fragmentów kodu i ulepszać jakość rozwiązań, Google uwzględnia parametr zapytania solution_channel w przykładowym kodzie w wywołaniach interfejsu API.

Używanie pakietu js-api-loader w NPM

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

npm install @googlemaps/js-api-loader

Ten pakiet można zaimportować do aplikacji za pomocą:

import { Loader } from "@googlemaps/js-api-loader"

Ładowarka udostępnia interfejs obietnicy i wywołania zwrotnego. Poniżej przedstawiamy użycie domyślnej metody load().

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

Zobacz przykładowy kod z biblioteką js-api-loader

Poniższy przykład pokazuje wczytywanie bibliotek za pomocą loader.importLibrary():

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

Migracja do interfejsu Dynamic Library Import API

W tej sekcji znajdziesz instrukcje migracji integracji na potrzeby korzystania z interfejsu Dynamic Library Import API.

Etapy migracji

Najpierw zastąp tag bezpośredniego ładowania skryptu tagiem wbudowanego ładowania bootstrapa.

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 funkcję importLibrary(), aby wczytać potrzebne biblioteki i dostęp do nich.

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