Wczytaj interfejs JavaScript JavaScript Map Google

Z tego przewodnika dowiesz się, jak wczytać interfejs Maps JavaScript API. OK 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 możesz zamawiać potrzebne biblioteki w odpowiednim momencie, zamiast niż wszystkie jednocześnie. Chroni również stronę przed wczytaniem Maps JavaScript API wielokrotnie.

Wczytaj interfejs Maps JavaScript API przez dodanie wbudowanego wczytywania do kodu aplikacji, jak widać 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 funkcji async. Deklarowanie zmiennych dla potrzebnych klas umożliwia możesz pominąć, korzystając z kwalifikowanej ścieżki (np. google.maps.Map), jak pokazano w następujący przykładowy kod:

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

Funkcja może również ładować biblioteki bez deklarowania zmiennej dla potrzebnych klas, co jest szczególnie przydatne, jeśli dodałeś mapę za pomocą Element 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. Maps JavaScript API nie zostanie wczytany, dopóki nie zostanie określony prawidłowy klucz interfejsu API.

Parametry opcjonalne

  • v: wersja komponentu Maps JavaScript API do wczytania.

  • libraries: rozdzielana przecinkami lista dodatkowych interfejsów Maps JavaScript API. biblioteki do załadowania. Określanie stały zestaw bibliotek nie jest zwykle zalecany, ale jest dostępny dla dla programistów, którzy chcą dokładnie dostosować działanie buforowania w swojej witrynie.

  • language: język na i ich używanie. Dotyczy to nazw elementów sterujących, informacji o prawach autorskich, wskazówek dojazdu, etykiety sterujące i kontrolne oraz odpowiedzi na żądania usługi. Zobacz listę obsługiwanych języków.

  • region: region który ma być użyty. Zmienia to zachowanie mapy w zależności od kraju lub w różnych regionach.

  • authReferrerPolicy: klienci korzystający z JS Map Google mogą konfigurować stronę odsyłającą HTTP Ograniczenia w konsoli Cloud dotyczące ograniczeń adresów URL, które mogą używać atrybutu konkretnego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, tylko określone ścieżki do użycia klucza interfejsu API. Jeśli dowolny adres URL w tej samej domenie lub tej samej domenie może używać klucza interfejsu API, możesz ustawić authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych przy autoryzacji żądań do interfejsu Maps JavaScript API. Kiedy ten parametr jest określony i włączone są ograniczenia stron odsyłających HTTP dla Konsola Cloud, Maps JavaScript API będzie się wczytywać tylko wtedy, występuje ograniczenie strony odsyłającej HTTP, , która pasuje do domeny 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 szybko rozpocząć pracę. Aby śledzić wdrożenie bardziej złożonego i poprawia jakość rozwiązania, Google uwzględnia solutionChannel w wywołaniach interfejsu API w przykładowym kodzie.

Używanie tagu bezpośredniego wczytywania skryptu

W tej sekcji pokazujemy, jak korzystać z tagu bezpośredniego wczytywania skryptu. Ponieważ reklama bezpośrednia ładuje biblioteki podczas wczytywania mapy, może uprościć mapy tworzone za pomocą gmp-map, eliminując potrzebę jawnego żądania bibliotek na stronie w środowisku wykonawczym. Ponieważ tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki na serwerze gdy skrypt jest wczytywany, może to mieć wpływ na wydajność aplikacji. Tag bezpośredniego wczytywania skryptu umieszczaj tylko raz na wczytanie strony.

Dodaj tag skryptu

Aby wczytywać interfejs Maps JavaScript API w pliku HTML, dodaj atrybut 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 zapytaniu ciągu skryptu URL wczytywania podczas wczytywania interfejsu Maps JavaScript API. Niektóre parametry są wymagane, a inne opcjonalne. Zgodnie ze standardem adresów URL, wszystkie parametry są rozdzielone znakiem „&”.

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 zostanie wczytany, jeśli klucz interfejsu API nie jest prawidłowy określone dane.

Parametry opcjonalne (bezpośrednie)

Użyj tych parametrów, aby przesłać żądanie konkretnej wersji interfejsu Maps JavaScript API. Wczytywanie dodatkowych bibliotek, lokalizowanie mapy i sprawdzanie stron odsyłających HTTP polityka

  • 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 skryptu nie wywołuje żadnego 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 zostanie wywołana po wprowadzeniu interfejsu Maps JavaScript API. wczytuje się całkowicie.

  • v: wersja interfejsu Maps JavaScript API. których użyć.

  • libraries: rozdzielona przecinkami lista dodatkowych interfejsów Maps JavaScript API. biblioteki do załadowania.

  • language: język na język i ich używanie. Dotyczy to nazw elementów sterujących, informacji o prawach autorskich, wskazówek dojazdu, etykiety sterujące i kontrolne oraz odpowiedzi na żądania usługi. Zobacz listę obsługiwanych języków.

  • region: region który ma być użyty. Zmienia to zachowanie mapy w zależności od kraju lub w różnych regionach.

  • auth_referrer_policy: klienci mogą konfigurować stronę odsyłającą HTTP Ograniczenia w konsoli Cloud dotyczące ograniczeń adresów URL, które mogą używać atrybutu konkretnego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, tylko określone ścieżki do użycia klucza interfejsu API. Jeśli dowolny adres URL w tej samej domenie lub tej samej domenie może używać klucza interfejsu API, możesz ustawić auth_referrer_policy=origin, aby ograniczyć ilość danych wysyłanych przy 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 dla Konsola Cloud, Maps JavaScript API będzie się wczytywać tylko wtedy, występuje ograniczenie dotyczące stron odsyłających HTTP pasujące do domeny bieżącej witryny bez określonej ś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 szybko rozpocząć pracę. Aby śledzić wdrożenie bardziej złożonego i poprawia jakość rozwiązania, Google uwzględnia solution_channel w wywołaniach interfejsu API w przykładowym kodzie.

Użyj pakietu NPM js-api-loader

@googlemaps/js-api-loader dostępny jest pakiet do załadowania przez menedżera pakietów NPM. Zainstaluj ją za pomocą to polecenie:

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. Ten przykład pokazuje, przy użyciu 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 należy wykonać, aby przeprowadzić migrację Dynamic Library Import API.

Etapy migracji

Najpierw zastąp tag bezpośredniego wczytywania skryptu wbudowanym modułem 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();