Maps JavaScript API laden

In diesem Leitfaden erfahren Sie, wie Sie die Maps JavaScript API laden. Dafür gibt es drei Möglichkeiten:

• Dynamic Library Import API verwenden
• Tag zum direkten Laden von Scripts verwenden
• NPM-js-api-loader-Paket verwenden

Dynamic Library Import API verwenden

Mit dem Dynamic Library Import können Bibliotheken zur Laufzeit geladen werden. So können Sie die benötigten Bibliotheken genau dann anfordern, wenn Sie sie benötigen, anstatt sie alle gleichzeitig beim Laden anzufordern. Außerdem wird verhindert, dass die Maps JavaScript API mehrmals auf Ihrer Seite geladen wird.

Um die Maps JavaScript API zu laden, fügen Sie das Inline-Bootstrap-Ladeprogramm in Ihren Anwendungscode ein, wie im folgenden Snippet gezeigt:

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

Sie können den Code des Bootstrap-Ladeprogramms auch direkt in Ihren JavaScript-Code einfügen.

Wenn Sie Bibliotheken während der Laufzeit laden möchten, verwenden Sie den Operator await, um importLibrary() innerhalb einer async-Funktion aufzurufen. Wenn Sie Variablen für die erforderlichen Klassen deklarieren, können Sie einen qualifizierten Pfad (z.B. google.maps.Map) überspringen, wie im folgenden Codebeispiel gezeigt:

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

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

Ihre Funktion kann auch Bibliotheken laden, ohne eine Variable für die erforderlichen Klassen zu deklarieren. Das ist besonders nützlich, wenn Sie eine Karte mit dem Element gmp-map hinzugefügt haben:

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

Alternativ können Sie die Bibliotheken direkt in HTML laden, wie hier gezeigt:

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

Weitere Informationen zur Migration zur Dynamic Library Loading API

Erforderliche Parameter

• key: Ihr API-Schlüssel. Die Maps JavaScript API wird nur geladen, wenn ein gültiger API-Schlüssel angegeben wurde.

Optionale Parameter

• v: Die Version der Maps JavaScript API, die geladen werden soll.

• libraries: Eine kommagetrennte Liste zusätzlicher Maps JavaScript API-Bibliotheken, die geladen werden sollen. Generell empfiehlt es sich nicht, einen festen Satz von Bibliotheken anzugeben. Entwickler, die das Caching auf ihrer Website genau steuern möchten, können dies jedoch tun.

• language: Die zu verwendende Sprache. Sie wirkt sich auf die Namen und Labels von Steuerelementen, Urheberrechtshinweise, Wegbeschreibungen und Antworten auf Dienstanfragen aus. Hier finden Sie eine Liste der unterstützten Sprachen.

• region: Der zu verwendende Regionscode. Dadurch wird das Verhalten der Karte an das jeweilige Land oder Gebiet angepasst.

• authReferrerPolicy: Maps JS-Kunden können in der Cloud Console Einschränkungen für HTTP-Referrer-URLs konfigurieren, um festzulegen, für welche URLs ein bestimmter API-Schlüssel verwendet werden darf. Diese Einschränkungen können standardmäßig so konfiguriert werden, dass nur bestimmte Pfade einen API-Schlüssel verwenden dürfen. Wenn der API-Schlüssel von jeder URL derselben Domain oder desselben Ursprungs verwendet werden kann, können Sie den Parameter authReferrerPolicy: "origin" definieren und so die Datenmenge begrenzen, die bei der Autorisierung von Anfragen von der Maps JavaScript API gesendet wird. Wenn dieser Parameter definiert ist und Einschränkungen vom Typ „HTTP-Referrer-URLs“ in der Cloud Console aktiviert sind, kann die Maps JavaScript API nur auf Seiten mit der Domain der aktuellen Website geladen werden, auf die der Zugriff beschränkt ist (ohne Pfadangabe).

• mapIds: Ein Array von Karten-IDs. Die Konfiguration für die angegebenen Karten-IDs wird vorab geladen.

• channel: Siehe Nutzungs-Tracking pro Kanal.

• solutionChannel: Auf der Google Maps Platform stehen zahlreiche Arten von Beispielcode für einen schnellen Einstieg zur Verfügung. Um die Übernahme der komplexeren Codebeispiele in die Praxis im Blick zu behalten und die Qualität der Lösungen zu verbessern, fügt Google den Abfrageparameter solutionChannel in die API-Aufrufe in den Beispielcodes ein.

Lade-Tag für direktes Script verwenden

In diesem Abschnitt erfahren Sie, wie Sie das Tag zum direkten Laden von Scripts verwenden. Da das Direktscript Bibliotheken beim Laden der Karte lädt, können Karten, die mit einem gmp-map-Element erstellt wurden, vereinfacht werden, da Bibliotheken nicht mehr zur Laufzeit explizit angefordert werden müssen. Da mit dem Tag zum direkten Laden von Scripts alle angeforderten Bibliotheken gleichzeitig geladen werden, kann sich die Leistung bei einigen Anwendungen beeinträchtigen. Fügen Sie das Tag zum direkten Laden von Scripts nur einmal pro Seitenladevorgang ein.

Script-Tag hinzufügen

Um die Maps JavaScript API direkt (inline) in einer HTML-Datei zu laden, fügen Sie wie unten gezeigt ein script-Tag ein.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

URL-Parameter für das direkte Laden des Scripts

In diesem Abschnitt werden die Parameter beschrieben, die Sie im Abfragestring der URL zum Laden des Scripts angeben können, wenn die Maps JavaScript API geladen wird. Bestimmte Parameter sind erforderlich, während andere optional sind. Wie in URLs üblich, werden alle Parameter mit dem Und-Zeichen (&) getrennt.

Die folgende Beispiel-URL enthält Platzhalter für alle möglichen Parameter:

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"

Mit der URL im folgenden Beispiel-script-Tag wird die Maps JavaScript API geladen:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Erforderliche Parameter (direkt)

Die folgenden Parameter sind beim Laden der Maps JavaScript API erforderlich.

• key: Ihr API-Schlüssel. Die Maps JavaScript API wird nur geladen, wenn ein gültiger API-Schlüssel angegeben wurde.

Optionale Parameter (direkt)

Sie können diese Parameter verwenden, um eine bestimmte Version der Maps JavaScript API anzufordern, zusätzliche Bibliotheken zu laden, Ihre Karte zu lokalisieren oder die Richtlinie zum Prüfen von HTTP-Referrer-URLs anzugeben.

• loading: Die Codeladestrategie, die die Maps JavaScript API verwenden kann. Legen Sie diesen Parameter auf async fest, um anzugeben, dass die Maps JavaScript API nicht synchron geladen wurde und dass durch das load-Ereignis des Scripts kein JavaScript-Code ausgelöst wird. Wir empfehlen, diese Einstellung nach Möglichkeit auf async festzulegen, um die Leistung zu verbessern. Verwenden Sie stattdessen den Parameter callback, um Aktionen auszuführen, wenn die Maps JavaScript API verfügbar ist. Verfügbar ab Version 3.55.

• callback: Der Name einer globalen Funktion, die aufgerufen werden soll, nachdem die Maps JavaScript API vollständig geladen wurde.

• v: Die Version der Maps JavaScript API, die verwendet werden soll.

• libraries: Eine kommagetrennte Liste zusätzlicher Maps JavaScript API-Bibliotheken, die geladen werden sollen.

• language: Die zu verwendende Sprache. Sie wirkt sich auf die Namen und Labels von Steuerelementen, Urheberrechtshinweise, Wegbeschreibungen und Antworten auf Dienstanfragen aus. Hier finden Sie eine Liste der unterstützten Sprachen.

• region: Der zu verwendende Regionscode. Dadurch wird das Verhalten der Karte an das jeweilige Land oder Gebiet angepasst.

• auth_referrer_policy: Kunden können in der Cloud Console Einschränkungen für HTTP-Referrer-URLs konfigurieren, um festzulegen, für welche URLs ein bestimmter API-Schlüssel verwendet werden darf. Diese Einschränkungen können standardmäßig so konfiguriert werden, dass nur bestimmte Pfade einen API-Schlüssel verwenden dürfen. Wenn der API-Schlüssel von jeder URL derselben Domain oder desselben Ursprungs verwendet werden kann, können Sie den Parameter auth_referrer_policy=origin definieren und so die Datenmenge begrenzen, die bei der Autorisierung von Anfragen von der Maps JavaScript API gesendet wird. Diese Option ist ab Version 3.46 verfügbar. Wenn dieser Parameter definiert ist und Einschränkungen vom Typ „HTTP-Referrer-URLs“ in der Cloud Console aktiviert sind, kann die Maps JavaScript API nur auf Seiten mit der Domain der aktuellen Website geladen werden, auf die der Zugriff beschränkt ist (ohne Pfadangabe).

• mapIds: Eine durch Kommas getrennte Liste von Karten-IDs. Die Konfiguration für die angegebenen Karten-IDs wird vorab geladen.

• channel: Siehe Nutzungs-Tracking pro Kanal.

• solution_channel: Auf der Google Maps Platform stehen zahlreiche Arten von Beispielcode für einen schnellen Einstieg zur Verfügung. Um die Übernahme der komplexeren Codebeispiele in die Praxis im Blick zu behalten und die Qualität der Lösungen zu verbessern, fügt Google den Abfrageparameter solution_channel in die API-Aufrufe in den Beispielcodes ein.

NPM-js-api-loader-Paket verwenden

Das Paket @googlemaps/js-api-loader kann über den NPM-Paketmanager geladen werden. Verwenden Sie folgenden Befehl für die Installation:

npm install @googlemaps/js-api-loader

So wird das Paket in die Anwendung importiert:

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

Das Ladeprogramm zeigt eine Promise- und Callback-Oberfläche an. Im Folgenden wird die Verwendung der standardmäßigen Promise-Methode load() veranschaulicht.

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

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

Beispiel mit „js-api-loader“ ansehen

Im folgenden Beispiel wird gezeigt, wie Bibliotheken mit loader.importLibrary() geladen werden:

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

Zur Dynamic Library Import API migrieren

In diesem Abschnitt werden die Schritte beschrieben, die erforderlich sind, um Ihre Integration zur Dynamic Library Import API zu migrieren.

Migrationsschritte

Ersetzen Sie zuerst das Tag für das direkte Laden des Scripts durch das Tag für den Inline-Bootloader.

Vorher

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

Nachher

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

Aktualisieren Sie dann Ihren Anwendungscode:

• Ändern Sie die initMap()-Funktion in asynchron.
• Rufen Sie importLibrary() auf, um die benötigten Bibliotheken zu laden und darauf zuzugreifen.

Vorher

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

Nachher

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