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

Dynamiczny import bibliotek umożliwia wczytywanie bibliotek w czasie wykonywania. 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>

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:

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. 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 interfejsu Maps JavaScript API 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, i kontrolnych oraz odpowiedzi na żądania usług. Zobacz listę obsługiwanych języków.

  • region: region który ma być użyty. 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 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. 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: 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ć 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 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 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>

Parametry adresu URL bezpośredniego ładowania 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 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)

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 wczytywania kodu, z której może korzystać interfejs 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. 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: rozdzielana przecinkami lista dodatkowych interfejsów Maps JavaScript API. biblioteki 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ą 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, 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 pochodzeniu 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 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 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 przykładowym kodzie w wywołaniach interfejsu API.

Użyj pakietu NPM js-api-loader

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

npm install @googlemaps/js-api-loader

Ten 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ładowy kod z użyciem js-api-loader

Poniższy przykład pokazuje wczytywanie bibliotek 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 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();