Wczytaj interfejs JavaScript JavaScript Map Google

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

Korzystanie z dynamicznego importu biblioteki

Wczytaj interfejs Maps JavaScript API, dodając do kodu aplikacji wbudowany program rozruchowy, 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żesz też dodać kod programu wczytywania bezpośrednio do kodu JavaScript.

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

Wymagane parametry

  • key: Twój klucz interfejsu API. Interfejs Maps JavaScript API nie zostanie wczytany, jeśli nie zostanie podany prawidłowy klucz interfejsu API.

Parametry opcjonalne

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

  • libraries: rozdzielona przecinkami lista dodatkowych bibliotek interfejsu Maps JavaScript API do wczytania. Określanie stałego zestawu bibliotek nie jest zwykle zalecane, ale może ono być dostępne dla deweloperów, którzy chcą doprecyzować działanie buforowania w swojej witrynie.

  • 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 prośby o usługę. Zobacz listę obsługiwanych języków.

  • region: kod regionu, którego należy użyć. Spowoduje to zmianę działania mapy w zależności od kraju lub terytorium.

  • authReferrerPolicy: klienci korzystający z Maps JS mogą skonfigurować w Cloud Console ograniczenia dotyczące stron odsyłających HTTP, aby określić, które adresy URL mogą używać określonego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby zezwolić na używanie klucza interfejsu API tylko określonym ścieżkom. Jeśli dowolny adres URL w tej samej domenie lub pochodzeniu może używać klucza interfejsu API, możesz ustawić authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu Maps JavaScript API. Gdy określisz ten parametr i włączysz ograniczenia HTTP w konsoli Google Cloud, interfejs Maps JavaScript API będzie się ładować tylko wtedy, gdy wystąpi ograniczenie HTTP dotyczące strony odsyłającej, które odpowiada domenie 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, który ułatwia szybkie rozpoczęcie pracy. Aby śledzić przyjęcie bardziej złożonych przykładów kodu i poprawić jakość rozwiązań, Google umieszcza parametr zapytania solutionChannel w wywołaniach interfejsu API w przykładowym kodzie.

Użyj pakietu js-api-loader NPM

Pakiet @googlemaps/js-api-loader jest dostępny do wczytania za pomocą menedżera pakietów NPM. Zainstaluj ją 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ł wczytywania wyświetla interfejs obiecywania i wywołania zwrotnego. Poniżej pokazujemy użycie domyślnej metody obiecującej obietnicy 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 wykorzystujący js-api-loader.

Poniższy przykład pokazuje, jak użyć narzędzia 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
});

Użyj tagu wczytywania bezpośredniego skryptu

W tej sekcji dowiesz się, jak używać tagu wczytywania bezpośredniego skryptu. Google zachęca do przejścia na interfejs Dynamic Library Upload API.

Dodaj tag 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>

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 wczytywania skryptu podczas ładowania interfejsu Maps JavaScript API. Niektóre parametry są wymagane, a inne opcjonalne. Zgodnie ze standardem w adresach URL wszystkie parametry są rozdzielone znakiem „&”.

Ten przykładowy URL zawiera symbole zastępcze 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 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: Twój klucz interfejsu API. Interfejs Maps JavaScript API nie zostanie wczytany, jeśli nie zostanie określony prawidłowy klucz interfejsu API.

  • callback: nazwa funkcji globalnej, która ma być wywołana po całkowitym wczytaniu interfejsu Maps JavaScript API.

Parametry opcjonalne (bezpośrednie)

Te parametry pozwalają na żądanie konkretnej wersji interfejsu Maps JavaScript API, wczytanie dodatkowych bibliotek, zlokalizowanie mapy lub określenie zasady sprawdzania stron odsyłających HTTP

  • loading: strategia wczytywania kodu, z której może korzystać interfejs Maps JavaScript API. Ustaw wartość async, aby wskazać, że interfejs Maps JavaScript API nie został ładowany synchronicznie i że zdarzenie load w skrypcie nie wywołuje żadnego kodu JavaScript. Zdecydowanie zalecamy ustawienie wartości async w miarę możliwości, aby 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 być wywołana po całkowitym wczytaniu interfejsu Maps JavaScript API.

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

  • libraries: rozdzielona przecinkami lista dodatkowych bibliotek interfejsu 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, a także odpowiedzi na prośby o usługę. Zobacz listę obsługiwanych języków.

  • region: kod regionu, którego należy użyć. Spowoduje to zmianę działania mapy w zależności od kraju lub terytorium.

  • auth_referrer_policy: klienci mogą skonfigurować w Cloud Console ograniczenia dotyczące stron odsyłających HTTP, aby określić, które adresy URL mogą używać określonego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby zezwolić na używanie klucza interfejsu API tylko określonym ścieżkom. Jeśli dowolny adres URL w tej samej domenie lub pochodzeniu może używać klucza interfejsu API, możesz ustawić 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. Gdy określisz ten parametr i są włączone ograniczenia dotyczące stron odsyłających w Cloud Console, interfejs Maps JavaScript API będzie się ładować tylko wtedy, gdy istnieje ograniczenie dotyczące strony odsyłającej HTTP, które pasuje do domeny bieżącej witryny bez podanej ścieżki.

  • mapIds: rozdzielona 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, który ułatwia szybkie rozpoczęcie pracy. Aby śledzić przyjęcie bardziej złożonych przykładów kodu i poprawić jakość rozwiązań, Google umieszcza parametr zapytania solution_channel w wywołaniach interfejsu API w przykładowym kodzie.

Przejście na interfejs Dynamic Library Import API

Z tej sekcji dowiesz się, jak przeprowadzić migrację integracji, aby korzystać z interfejsu Dynamic Library Import API.

Etapy migracji

Najpierw zastąp tag wczytywania bezpośredniego skryptu tagiem wbudowanego modułu wczytywania.

Przed

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&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();