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 der Dynamic Library Import API können Sie Bibliotheken zur Laufzeit laden. So können Sie die benötigten Bibliotheken genau dann anfordern, wenn Sie sie brauchen, und nicht alle auf einmal bei der Ladezeit. 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 zur Laufzeit laden möchten, verwenden Sie den Operator await, um importLibrary() innerhalb einer async-Funktion aufzurufen. Wenn Sie Variablen für die benötigten Klassen deklarieren, können Sie einen qualifizierten Pfad (z.B. google.maps.Map) verwenden, wie im folgenden Codebeispiel gezeigt:

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();
index.js

Ihre Funktion kann Bibliotheken auch laden, ohne eine Variable für die benötigten Klassen zu deklarieren. Das ist besonders nützlich, wenn Sie eine Karte mit dem Element gmp-map hinzugefügt haben. Ohne die Variable müssen Sie qualifizierte Pfade verwenden, z. B. google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

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

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

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

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

Informationen zum Migrieren 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: Ein Array zusätzlicher Maps JavaScript API Bibliotheken, die vorab 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. Es ist weiterhin wichtig, google.maps.importLibrary() für jede ausgewählte Bibliothek aufzurufen, bevor sie verwendet wird.

• 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 Regions code. Dadurch wird das Verhalten der API 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 authReferrerPolicy: "origin" festlegen 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 geladen werden, wenn eine HTTP-Referrer- Einschränkung vorhanden ist, die mit der Domain der aktuellen Website übereinstimmt (ohne Pfadangabe).

• mapIds: Ein Array von Karten-IDs. Bewirkt, dass die Konfiguration für die angegebenen Karten-IDs vorab geladen wird. Die Angabe von Karten-IDs ist für die Verwendung von Karten-IDs nicht erforderlich, aber für Entwickler verfügbar, die die Netzwerkleistung genau steuern möchten.

• channel: Informationen finden Sie unter Nutzung pro Channel erfassen.

Tag zum direkten Laden von Scripts verwenden

In diesem Abschnitt wird beschrieben, wie Sie das Tag zum direkten Laden von Scripts verwenden. Da das direkte Script Bibliotheken lädt, wenn die Karte geladen wird, kann es Karten vereinfachen, die mit einem gmp-map-Element erstellt wurden, da Bibliotheken nicht mehr explizit zur Laufzeit angefordert werden müssen. Da das Tag zum direkten Laden von Scripts alle angeforderten Bibliotheken gleichzeitig lädt, wenn das Script geladen wird, kann sich dies auf die Leistung einiger Anwendungen auswirken. Das Tag zum direkten Laden von Scripts darf nur einmal pro Seitenaufruf verwendet werden.

Hinweis: Sie können importLibrary aufrufen, nachdem das Tag zum direkten Laden von Scripts geladen wurde.

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>

Parameter für die URL zum direkten 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, andere optional. 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) {:.hide-from-toc}

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) {:.hide-from-toc}

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 Strategie zum Laden von Code, die von der Maps JavaScript API verwendet werden kann. Legen Sie async fest, um anzugeben, dass die Maps JavaScript API nicht synchron geladen wurde und dass kein JavaScript-Code durch das load-Ereignis des Scripts ausgelöst wird. Für eine bessere Leistung wird dringend empfohlen, diese Option nach Möglichkeit auf async zu setzen. Verwenden Sie stattdessen den Parameter callback, um Aktionen auszuführen, wenn die Maps JavaScript API verfügbar ist. Ab Version 3.55 verfügbar.

• 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 durch Kommas getrennte 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 Regions code. Dadurch wird das Verhalten der API 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 auth_referrer_policy=origin festlegen 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).

• map_ids: Eine durch Kommas getrennte Liste von Karten-IDs. Bewirkt, dass die Konfiguration für die angegebenen Karten-IDs vorab geladen wird. Die Angabe von Karten-IDs ist für die Verwendung von Karten-IDs nicht erforderlich, aber für Entwickler verfügbar, die die Netzwerkleistung genau steuern möchten.

• channel: Informationen finden Sie unter Nutzung pro Channel erfassen.

NPM-js-api-loader-Paket verwenden

Tipp: Die v2.0.0 ist eine umfassende Überarbeitung, bei der die alte Klasse Loader durch eine API ersetzt wird, die aus zwei Funktionen besteht: setOptions() und importLibrary(). Diese Änderung ermöglicht das dynamische Laden einzelner Maps API-Bibliotheken bei Bedarf und das Verschieben von Feature-Downloads, um die anfängliche Seitenleistung zu verbessern.

Das Paket @googlemaps/js-api-loader kann über den NPM-Paketmanager geladen werden. Installieren Sie es mit dem folgenden Befehl:

npm install @googlemaps/js-api-loader

Importieren Sie das Paket wie hier gezeigt:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.ts

Hinweis: Lesen Sie sich hierzu den Leitfaden zur Verwendung von TypeScript und Google Maps durch.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.js

Das Ladeprogramm verwendet Promises, um Bibliotheken verfügbar zu machen. Laden Sie Bibliotheken mit der Methode importLibrary(). Im folgenden Beispiel wird gezeigt, wie Sie mit dem Ladeprogramm eine Karte laden:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function init(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();
index.ts

Hinweis: Lesen Sie sich hierzu den Leitfaden zur Verwendung von TypeScript und Google Maps durch.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map'), mapOptions);
}

void init();
index.js

Vollständiger Beispielcode

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 zum direkten Laden von 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();