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 (empfohlen)
NPM-js-api-loader-Paket verwenden
Lade-Tag des alten Scripts verwenden

Dynamic Library Import API verwenden

Laden Sie die Maps JavaScript API. Fügen Sie hierzu 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, wie im folgenden Codebeispiel gezeigt:

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

Erforderliche Parameter

key: Die Maps JavaScript API wird nur geladen, wenn Sie einen gültigen API-Schlüssel angeben.

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

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.

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

Beispiel mit „js-api-loader“ ansehen

Lade-Tag des alten Scripts verwenden

Das Lade-Tag des alten Scripts wird weiterhin unterstützt. Dieser Abschnitt wurde für Integrationen verfasst, für die dieses Tag verwendet wird. Google empfiehlt jedoch die Migration zur Dynamic Library Loading API.

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&callback=initMap">
</script>

Parameter für die URL zum 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
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

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&callback=initMap">
</script>

Erforderliche Parameter (Legacy)

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.
callback: Der Name einer globalen Funktion, die aufgerufen werden soll, nachdem die Maps JavaScript API vollständig geladen wurde.

Optionale Parameter (Legacy)

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.

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

Hinweis: Dieser Abfrageparameter wird von Google verwendet. Weitere Informationen finden Sie unter Google Maps Platform – Lösungsparameter.
auth_referrer_policy: 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 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).

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.

Migrationsanleitung

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

Vorher

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