Wczytaj interfejs JavaScript JavaScript Map Google

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

Używanie funkcji Importowania z bibliotek dynamicznych

Dynamiczne importowanie bibliotek umożliwia ładowanie bibliotek w czasie działania. Dzięki temu podczas wczytywania wszystkich bibliotek możesz zamawiać potrzebne biblioteki w odpowiednim momencie, zamiast wszystkich naraz. Chroni również Twoją stronę przed wielokrotnym ładowaniem interfejsu Maps JavaScript API.

Wczytaj interfejs Maps JavaScript API, dodając wbudowany moduł wczytywania do kodu aplikacji, jak 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ż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, jak pokazano w tym przykładowym kodzie:

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

Jeśli dodasz mapę za pomocą elementu gmp-map, funkcja initMap() może wczytywać biblioteki bez deklarowania zmiennej dla wymaganych klas:

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 wczytania.

  • libraries: rozdzielona przecinkami lista dodatkowych bibliotek Maps JavaScript API do wczytania. 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. Dotyczy to nazw elementów sterujących, informacji o prawach autorskich, wskazówek dojazdu i etykiet kontrolnych 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 Map Google w języku JS mogą skonfigurować ograniczenia HTTP dotyczące stron odsyłających w Cloud Console, aby ograniczyć możliwość korzystania z konkretnego klucza interfejsu API w przypadku adresów URL. 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 dotyczące 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

W tej sekcji pokazujemy, jak korzystać z tagu bezpośredniego wczytywania skryptu. Bezpośredni skrypt wczytuje biblioteki podczas wczytywania mapy, dlatego może uprościć mapy tworzone za pomocą elementu gmp-map, eliminując potrzebę jawnego żądania bibliotek w środowisku wykonawczym. Pamiętaj jednak, aby dodawać go tylko raz na wczytanie strony.

Dodaj tag skryptu

Aby wczytać interfejs Maps JavaScript API bezpośrednio 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>

Bezpośrednie wczytywanie parametrów adresu URL przez skrypt

W tej sekcji omawiamy wszystkie parametry, które można określić w ciągu zapytania adresu URL skryptu wczytywania 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 zmienne 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)

Te parametry pozwalają zażądać konkretnej wersji interfejsu Maps JavaScript API, wczytać dodatkowe biblioteki, zlokalizować mapę lub określić zasadę sprawdzania strony odsyłającej HTTP.

  • loading: strategia wczytywania kodu, z której może korzystać interfejs Maps JavaScript API. Ustaw jako async, aby wskazać, że interfejs Maps JavaScript API nie został ładowany synchronicznie i że zdarzenie load w skrypcie nie wywołuje kodu JavaScript. Jeśli to możliwe, zalecamy ustawienie tego ustawienia na async, ponieważ pozwala to zwiększyć wydajność. (Zamiast tego używaj parametru callback, aby wykonywać działania, gdy dostępny jest interfejs Maps JavaScript API). 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ó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.

  • auth_referrer_policy: klienci mogą skonfigurować ograniczenia HTTP dotyczące stron odsyłających w Cloud Console, aby ograniczyć liczbę adresów URL, które mogą używać określonego klucza interfejsu 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ć 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 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. Powoduje wstępne wczytanie konfiguracji określonych identyfikatorów map.

  • channel: patrz Ś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ć wdrażanie bardziej złożonych przykładów kodu i poprawiać jakość rozwiązania, Google umieszcza w przykładowym kodzie parametr zapytania solution_channel w wywołaniach interfejsu API.

Użyj pakietu NPM js-api-loader

Dostępny jest pakiet @googlemaps/js-api-loader do wczytania za pomocą menedżera pakietów NPM. Zainstaluj go za pomocą tego polecenia:

npm install @googlemaps/js-api-loader

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 pokazujemy użycie 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 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 wczytywania skryptu wbudowanym tagiem wczytywania wczytywania.

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