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 dynamicznego importowania bibliotek

Dynamiczne importowanie bibliotek umożliwia wczytywanie bibliotek w czasie działania programu. Dzięki temu możesz poprosić o potrzebne biblioteki w momencie, gdy są potrzebne, zamiast wczytywać je wszystkie naraz. Chroni też stronę przed wielokrotnym wczytywaniem interfejsu Maps JavaScript API.

Wczytaj interfejs Maps JavaScript API, dodając do kodu aplikacji wbudowany program do uruchamiania, jak pokazano w tym fragmencie:

<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żesz też dodać kod programu ładującego bezpośrednio do kodu JavaScript.

Aby wczytać biblioteki w czasie działania programu, użyj operatora await, aby wywołać importLibrary() w funkcji async. Zadeklarowanie zmiennych dla potrzebnych klas pozwala pominąć używanie kwalifikowanej ścieżki (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, 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 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, jak pokazano poniżej:

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

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

Wymagane parametry

  • key: Twój klucz API. Interfejs Maps JavaScript API nie wczyta się, dopóki nie zostanie podany prawidłowy klucz interfejsu API.

Parametry opcjonalne

  • v: wersja interfejsu Maps JavaScript API do wczytania.

  • libraries: tablica dodatkowych bibliotek Maps JavaScript API do wczytania. Określanie stałego zestawu bibliotek nie jest zwykle 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, informacji o prawach autorskich, wskazówek dojazdu i etykiet elementów sterujących oraz odpowiedzi na żądania usług. Zobacz listę obsługiwanych języków.

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

  • authReferrerPolicy: klienci korzystający z interfejsu Maps JS mogą skonfigurować w konsoli Cloud ograniczenia odsyłającego adres HTTP, aby określić, które adresy URL mogą używać danego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby tylko określone ścieżki mogły używać klucza API. Jeśli dowolny adres URL w tej samej domenie lub pochodzący z tego samego źródła może używać klucza interfejsu API, możesz ustawić parametr authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu Maps JavaScript API. Jeśli ten parametr jest określony, a w Konsoli Cloud włączone są ograniczenia odsyłającego adresu HTTP, interfejs Maps JavaScript API będzie można 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. Powoduje wstępne wczytanie konfiguracji dla określonych identyfikatorów map. Określanie identyfikatorów map w tym miejscu nie jest wymagane do ich używania, ale jest dostępne dla programistów, którzy chcą precyzyjnie dostosować wydajność sieci.

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

  • solutionChannel: Google Maps Platform udostępnia wiele rodzajów przykładowego kodu, który ułatwia szybkie rozpoczęcie pracy. Aby śledzić wdrażanie naszych bardziej złożonych przykładowych fragmentów kodu i poprawiać jakość rozwiązań, w przykładach kodu umieszczamy w wywołaniach interfejsu API parametr zapytania solutionChannel.

Używanie tagu bezpośredniego wczytywania skryptu

W tej sekcji dowiesz się, jak używać tagu bezpośredniego wczytywania skryptu. Skrypt bezpośredni wczytuje biblioteki podczas wczytywania mapy, co może uprościć mapy utworzone za pomocą elementu gmp-map, ponieważ nie trzeba wtedy jawnie wysyłać żądań bibliotek w czasie działania programu. Tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki jednocześnie po załadowaniu skryptu, więc w przypadku niektórych aplikacji może to mieć wpływ na wydajność. Tag bezpośredniego wczytywania skryptu należy umieszczać tylko raz podczas wczytywania strony.

Dodawanie tagu skryptu

Aby wczytać interfejs Maps JavaScript API w pliku HTML, dodaj tag script w sposób pokazany 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ą 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"

URL w tagu script w przykładzie poniżej 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 API. Interfejs Maps JavaScript API nie zostanie wczytany, jeśli nie podasz prawidłowego klucza 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 zdarzenie load skryptu nie wywołuje żadnego kodu JavaScript. W celu zwiększenia wydajności zalecamy ustawienie tej opcji na async, jeśli tylko 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 załadowaniu Maps JavaScript API.

  • v: wersja interfejsu Maps JavaScript API, która ma być używana.

  • libraries: lista dodatkowych bibliotek Maps JavaScript API do wczytania, oddzielonych przecinkami.

  • language: Język, którego chcesz użyć. Dotyczy to nazw elementów sterujących, informacji o prawach autorskich, wskazówek dojazdu i etykiet elementów sterujących, a także odpowiedzi na żądania usług. Zobacz listę obsługiwanych języków.

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

  • auth_referrer_policy: Klienci mogą skonfigurować ograniczenia dotyczące strony odsyłającej HTTP w konsoli Cloud, aby ograniczyć adresy URL, które mogą używać określonego klucza 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 pochodzący 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 autoryzowania żądań z interfejsu Maps JavaScript API. Ta funkcja jest dostępna od wersji 3.46. Jeśli ten parametr jest określony, a w konsoli Cloud włączone są ograniczenia dotyczące odsyłającego HTTP, interfejs Maps JavaScript API będzie można wczytać tylko wtedy, gdy istnieje ograniczenie dotyczące odsyłającego HTTP, które pasuje do domeny bieżącej witryny bez określonej ścieżki.

  • mapIds: lista identyfikatorów map rozdzielonych przecinkami. Powoduje wstępne wczytanie konfiguracji dla określonych identyfikatorów map. Określanie tutaj 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.

  • solution_channel: Google Maps Platform udostępnia wiele rodzajów przykładowego kodu, który ułatwia szybkie rozpoczęcie pracy. Aby śledzić wdrażanie naszych bardziej złożonych przykładowych fragmentów kodu i poprawiać jakość rozwiązań, w przykładach kodu umieszczamy w wywołaniach interfejsu API parametr zapytania solution_channel.

Korzystanie z pakietu NPM js-api-loader

Dostępny jest pakiet @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

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

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

Ładowarka udostępnia interfejs Promise i interfejs wywołania zwrotnego. Poniżej pokazujemy, jak używać domyślnej metody Promise 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ład z użyciem js-api-loader

W tym przykładzie pokazujemy, jak wczytywać biblioteki 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 API importu bibliotek dynamicznych

W tej sekcji znajdziesz instrukcje migracji integracji na Dynamic Library Import API.

Etapy migracji

Najpierw zastąp tag bezpośredniego ładowania skryptu tagiem wbudowanego programu do ładowania początkowego.

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