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 program ładują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 ładowania bootstrapa możesz też dodać bezpośrednio do kodu JavaScript.

Aby wczytywać 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:

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

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:

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

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, dopóki nie podasz prawidłowego klucza 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 dojazdu, etykiet 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 zachowania interfejsu API na podstawie danego kraju lub terytorium.

  • authReferrerPolicy: klienci korzystający z Maps JS mogą skonfigurować w konsoli Cloud ograniczenia dotyczące HTTP Referrer, aby ograniczyć listę adresów URL, które mogą używać określonego klucza 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 Cloud Console są włączone ograniczenia odnośnika HTTP, interfejs Maps JavaScript API może się wczytać tylko wtedy, gdy istnieje ograniczenie odnośnika 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

W tej sekcji dowiesz się, jak używać tagu bezpośredniego wczytywania skryptu. Ponieważ skrypt wczytuje biblioteki podczas wczytywania mapy, może uprościć mapy tworzone za pomocą elementu gmp-map, ponieważ nie trzeba już wyraźnie prosić o biblioteki w czasie wykonywania. Tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki od razu po wczytaniu skryptu, dlatego w przypadku niektórych aplikacji może to mieć wpływ na wydajność. Dodaj 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 ładowania skryptu

W tej sekcji omawiamy wszystkie parametry, które możesz określić w składni zapytania adresu URL ładowania 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 załadowany, chyba że podany zostanie prawidłowy klucz interfejsu API.

Parametry opcjonalne (bezpośrednie)

Używaj tych parametrów, aby żądać określonej wersji interfejsu Maps JavaScript API, wczytywać dodatkowe biblioteki, lokalizować mapę lub określać zasady sprawdzania odesłania 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ść. (aby wykonać działania, gdy interfejs Maps JavaScript API jest dostępny, użyj zamiast tego parametru callback). 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 usługi. Zobacz listę obsługiwanych języków.

  • region: kod regionu, którego chcesz użyć. Zmiana zachowania interfejsu API na podstawie 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ć konkretnego klucza 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ść 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 odsyłającego adresu HTTP, interfejs Maps JavaScript API może 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: lista identyfikatorów map oddzielonych przecinkami. Spowoduje wstępne załadowanie konfiguracji dla określonych identyfikatorów map. Podawanie identyfikatorów map nie jest wymagane do korzystania z tych map, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

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

  • 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 NPM js-api-loader

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

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 ładowarka bootstrap.

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