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

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

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: lista oddzielonych przecinkami 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 mapy na podstawie 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 z tego samego źródła 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. Jeśli ten parametr jest określony, a w Konsoli Cloud włączone są ograniczenia dotyczące odsyłającego adresu HTTP, interfejs Maps JavaScript API będzie mógł się wczytać tylko wtedy, gdy istnieje ograniczenie dotyczące 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.

• 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 wywołaniach interfejsu API w przykładowym kodzie.

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 wczytywania 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 załaduje 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. Zdecydowanie zalecamy, aby w miarę możliwości ustawić tę wartość na async, ponieważ poprawi to wydajność. (zamiast tego użyj 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 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 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 z tego samego źródła 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 włączone są 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.

• 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 wywołaniach interfejsu API w przykładowym kodzie.

Używanie pakietu js-api-loader 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"

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

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

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

Ten przykład pokazuje wczytywanie bibliotek za pomocą funkcji 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();