Wczytaj interfejs JavaScript JavaScript Map Google

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

Korzystanie z importu dynamicznej biblioteki

Dynamiczne importowanie bibliotek umożliwia ładowanie bibliotek w czasie działania. Dzięki temu możesz wczytywać potrzebne biblioteki w chwili, gdy ich potrzebujesz, a nie wszystkie naraz w momencie wczytywania. Chroni również stronę przed wielokrotnym ładowaniem interfejsu Maps JavaScript API.

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>

Można go również dodać bezpośrednio do kodu JavaScript.

Aby wczytywać biblioteki w czasie działania, użyj operatora await do wywołania 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();

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

Funkcja może też wczytywać biblioteki bez deklarowania zmiennej dla wymaganych klas, co jest szczególnie przydatne, gdy dodajesz 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 kodzie HTML, jak pokazano poniżej:

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

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

Wymagane parametry

  • key: klucz interfejsu API. Interfejs Maps JavaScript API nie wczyta się, jeśli nie zostanie podany prawidłowy klucz interfejsu API.

Parametry opcjonalne

  • v: Wersja interfejsu Maps JavaScript API do załadowania.

  • libraries: lista oddzielonych przecinkami dodatkowych bibliotek interfejsu Maps JavaScript API do załadowania. Określanie stałego zestawu bibliotek nie jest zwykle zalecane, ale jest dostępne dla programistów, którzy chcą dostosować działanie buforowania w swojej witrynie.

  • language: język, który ma być używany. Ma to wpływ na nazwy elementów sterujących, informacje o prawach autorskich, wskazówki dojazdu i etykiety kontrolne oraz odpowiedzi na żądania usługi. Zobacz listę obsługiwanych języków.

  • region: kod regionu do użycia. Zmienia to działanie mapy w zależności od 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 API. Domyślnie ograniczenia te można skonfigurować tak, aby zezwalały na korzystanie z klucza interfejsu API tylko w przypadku określonych ścieżek. Jeśli dowolny adres URL w tej samej domenie lub źródle może korzystać z klucza interfejsu API, możesz ustawić authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych podczas autoryzacji żądań do interfejsu Maps JavaScript API. Jeśli określisz ten parametr i włączysz ograniczenia stron odsyłających HTTP w konsoli Cloud, Maps JavaScript API będzie się wczytywać tylko wtedy, gdy wystąpi ograniczenie HTTP dotyczące stron odsyłających, które będzie zgodne z domeną bieżącej witryny bez określonej ścieżki.

  • mapIds: tablica identyfikatorów map. Powoduje wstępne wczytanie konfiguracji określonych identyfikatorów map.

  • channel: patrz Śledzenie wykorzystania według kanału.

  • solutionChannel: Google Maps Platform udostępnia wiele typów przykładowego kodu, aby ułatwić Ci szybkie rozpoczęcie pracy. Aby śledzić wdrażanie bardziej złożonych przykładów kodu i poprawiać jakość rozwiązania, Google umieszcza w przykładowym kodzie parametr zapytania solutionChannel 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. Ponieważ tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki od razu po załadowaniu skryptu, skuteczność może być ograniczona w przypadku niektórych aplikacji. 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 ł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. Standardowo w adresach URL wszystkie parametry są oddzielane 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>

Parametry wymagane (bezpośrednie)

Poniższe parametry są wymagane podczas wczytywania interfejsu Maps JavaScript API.

  • key: klucz interfejsu API. Interfejs Maps JavaScript API nie wczyta się, jeśli nie zostanie podany 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. Jeśli to możliwe, zalecamy ustawienie tego ustawienia na async, ponieważ pozwala to 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 wczytaniu interfejsu Maps JavaScript API.

  • v: wersja interfejsu Maps JavaScript API, który ma zostać użyty.

  • libraries: rozdzielona przecinkami lista 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, informacje o prawach autorskich, wskazówki dojazdu i etykiety kontrolne oraz odpowiedzi na żądania usługi. Zobacz listę obsługiwanych języków.

  • region: kod regionu do użycia. Zmiana zachowania mapy 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 źródle może korzystać z klucza interfejsu API, możesz ustawić auth_referrer_policy=origin, aby ograniczyć ilość danych wysyłanych podczas autoryzacji żądań do interfejsu Maps JavaScript API. Ta funkcja jest dostępna od wersji 3.46. Gdy ten parametr jest określony i włączone są ograniczenia dotyczące stron odsyłających HTTP w konsoli Cloud, Maps JavaScript API będzie się wczytywać tylko wtedy, gdy występuje ograniczenie dotyczące stron odsyłających HTTP zgodne z domeną bieżącej witryny bez podanej ścieżki.

  • mapIds: rozdzielana przecinkami lista identyfikatorów map. Spowoduje wstępne załadowanie konfiguracji dla określonych identyfikatorów map.

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

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"

Moduł ładowania ujawnia interfejs Promise 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,
  });
});

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,
  });
});

Zobacz przykład z narzędziem js-api-loader.

Poniższy przykład pokazuje użycie loader.importLibrary() do wczytywania bibliotek:

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

Przejście na interfejs Dynamic Library Import API

W tej sekcji omawiamy czynności, które musisz wykonać, aby przeprowadzić migrację, aby korzystać 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 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();