Es kann losgehen!

Bevor Sie mit der Entwicklung beginnen, lesen Sie bitte unsere Entwicklerdokumentation.

Die Google Maps JavaScript API aktivieren

Zum Einstieg führen wir Sie durch die Google Developers Console, wo Sie vorab Folgendes tun müssen:

  1. Ein Projekt erstellen oder auswählen
  2. Die Google Maps JavaScript API und zugehörige Dienste aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Ereignisse

Auf dieser Seite werden die Benutzeroberflächen- und Fehlerereignisse beschrieben, die programmgesteuert gemeldet und behandelt werden können.

Benutzeroberflächenereignisse

JavaScript im Browser ist ereignisgesteuert, das bedeutet, dass JavaScript durch das Generieren von Ereignissen auf Interaktionen reagiert und erwartet, dass ein Programm auf interessante Ereignisse wartet. Es gibt zwei verschiedene Arten von Ereignissen:

  • Nutzerereignisse (zum Beispiel „Mausklick“-Ereignisse) werden vom DOM an die Google Maps JavaScript API übermittelt. Diese Ereignisse sind eigenständig und gehören nicht zu den DOM-Standardereignissen.
  • Benachrichtigungen zur Änderung des MVC-Zustands erfolgen bei Änderungen in Objekten vom Typ Maps JavaScript API; sie werden entsprechend der Namenskonvention property_changed benannt.

Mit jedem Objekt Maps JavaScript API wird eine Anzahl benannter Ereignisse exportiert. Programme mit Interesse an bestimmten Ereignissen melden JavaScript-Ereignislistener für diese Ereignisse an und führen beim Eintreten dieser Ereignisse einen Code aus. Dazu wird addListener() aufgerufen, um Ereignishandler für das Objekt anzumelden.

Im nachfolgenden Beispiel wird gezeigt, welche Ereignisse während Ihrer Interaktion mit der Karte durch google.maps.Map ausgelöst werden.

Eine vollständige Liste der Ereignisse finden Sie in der Referenz zur Google Maps JavaScript APIMaps API. Ereignisse werden in einem eigenen Abschnitt für jedes Objekt, das Ereignisse enthält, aufgeführt.

UI-Ereignisse

Einige Objekte in der Google Maps JavaScript API sind dafür vorgesehen, auf Benutzerereignisse zu reagieren, z. B. auf Maus- oder Tastaturereignisse. Nachfolgend sind einige Beispiele für Benutzerereignisse aufgeführt, auf die eine Reaktion eines Objekts google.maps.Marker folgen kann:

  • 'click'
  • 'dblclick'
  • 'mouseup'
  • 'mousedown'
  • 'mouseover'
  • 'mouseout'

Die gesamte Liste finden Sie in der Klasse Marker. Diese Ereignisse sehen möglicherweise wie standardmäßige DOM-Ereignisse aus, sind aber in Wirklichkeit Teil der Maps JavaScript API. Da in den verschiedenen Browsern unterschiedliche DOM-Ereignismodelle implementiert sind, bietet die Maps JavaScript API diese Mechanismen zum Warten und Reagieren auf DOM-Ereignisse, ohne die verschiedenen browserspezifischen Besonderheiten berücksichtigen zu müssen. Mit diesen Ereignissen werden typischerweise auch Argumente mit dem Ereignis übergeben, die einen bestimmten UI-Zustand angeben (z. B. die Mausposition).

Änderungen des MVC-Zustands

MVC-Objekte enthalten in der Regel einen Zustand. Bei jeder Änderung der Eigenschaft eines Objekts wird in der Google Maps JavaScript API ein Eigenschaftsänderungsereignis ausgelöst. Beispielsweise wird in der API ein Ereignis zoom_changed auf einer Karte ausgelöst, wenn sich die Vergrößerungsstufe der Karte ändert. Sie können diese Zustandsänderungen abfangen, indem Sie addListener() aufrufen, um Ereignishandler auch für das Objekt zu anzumelden.

Benutzerereignisse und Änderungen des MVC-Zustands können sich ähneln, Sie sollten sie in Ihrem Code jedoch unterschiedlich verarbeiten. MVC-Ereignisse übergeben beispielsweise keine Argumente mit ihrem Ereignis. Um die Eigenschaft, die im Zuge einer Änderung des MVC-Zustands verändert wurde, zu überprüfen, rufen Sie die entsprechende Methode getProperty zu diesem Objekt auf.

Ereignisse bearbeiten

Um Ereignisbenachrichtigungen zu registrieren, verwenden Sie den Ereignishandler addListener(). Diese Methode erfordert ein Ereignis, auf das gewartet werden soll, und eine Funktion, die beim Eintreten des angegebenen Ereignisses aufgerufen werden soll.

Beispiel: Karten- und Markerereignisse

Im folgenden Code werden Benutzerereignisse mit Zustandsänderungsereignissen kombiniert. Wir fügen einen Ereignishandler an einen Marker an, mit dem die Kartenansicht vergrößert wird, wenn ein Klick auf die Karte erfolgt. Außerdem fügen wir einen Ereignishandler für Änderungen an der Eigenschaft center hinzu, sodass die Karte drei Sekunden nach Eingang des Ereignisses center_changed zurück auf den Marker geschwenkt wird:

function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

Beispiel anzeigen (event-simple.html).

Tipp: Wenn Sie versuchen, eine Änderung im Viewport zu erkennen, verwenden Sie unbedingt das spezifische Ereignis bounds_changed anstelle der zugehörenden Ereignisse zoom_changed und center_changed. Da die letzteren Ereignisse durch die Maps JavaScript API unabhängig ausgelöst werden, kann es sein, dass mit getBounds() keine verwendbaren Ergebnisse geliefert werden, solange der Viewport nicht verbindlich geändert wurde. Wenn Sie getBounds() nach einem Ereignis wie diesem ändern möchten, warten Sie stattdessen unbedingt auf das Ereignis bounds_changed.

Beispiel: Ereignisse zum Ziehen und Bearbeiten von Formen

Wenn eine Form bearbeitet oder gezogen wird, wird nach Abschluss der Aktion ein Ereignis ausgelöst. Eine Liste der Ereignisse und einige Codebeispiele finden Sie unter Formen.

Beispiel anzeigen (rectangle-event.html)

Argumente in UI-Ereignissen aufrufen

Durch UI-Ereignisse innerhalb der Google Maps JavaScript API wird typischerweise ein Ereignisargument mit dem UI-Zustand im Augenblick des Ereignisses übergeben, auf das der Ereignislistener zugreifen kann. Beispielsweise wird mit einem UI-Ereignis 'click' in der Regel ein MouseEvent übergeben, das eine Eigenschaft latLng enthält, die angibt, an welcher Position auf die Karte geklickt wurde. Beachten Sie, dass dieses Verhalten nur bei UI-Ereignissen erfolgt; bei Änderungen des MVC-Zustands werden keine Argumente mit den zugehörigen Ereignissen übergeben.

Sie können die Argumente des Ereignisses in einem Ereignislistener auf die gleiche Weise aufrufen wie die Eigenschaften eines Objekts. Im nachfolgenden Beispiel wird ein Ereignislistener zur Karte hinzugefügt und ein Marker erstellt, wenn der Benutzer im Klickbereich auf die Karte klickt:

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}

Beispiel anzeigen (event-arguments.html).

Auslöser für Ereignislistener verwenden

Beim Ausführen eines Ereignislisteners ist es häufig vorteilhaft, private und persistente Daten an ein Objekt anzufügen. „Private“ Instanzdaten werden von JavaScript nicht unterstützt, es werden jedoch Auslöser unterstützt, die es ermöglichen, dass interne Funktionen auf externe Variablen zugreifen. Auslöser in Ereignislistenern sind hilfreich, um auf Variablen zuzugreifen, die normalerweise nicht an Objekte angefügt werden, für die Ereignisse erfolgen.

Im nachfolgenden Beispiel wird ein Funktionsauslöser im Ereignislistener verwendet, um eine geheime Nachricht an eine Markergruppe zu senden. Durch Klicken auf die einzelnen Marker wird ein Teil der geheimen Nachricht offen gelegt, der nicht im Marker selbst enthalten ist.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random()
      },
      map: map
    });
    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random()
      },
      map: map
    });
    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}

Beispiel anzeigen (event-closure.html).

Eigenschaften in Ereignishandlern abrufen und festlegen

Bei keinem der MVC-Zustandsänderungsereignisse im Ereignissystem der Google Maps JavaScript API werden beim Auslösen des Ereignisses Argumente übergeben. (Benutzerereignisse übergeben dagegen Argumente, die überprüft werden können.) Um eine Eigenschaft einer Änderung des MVC-Zustands zu überprüfen, rufen Sie explizit die entsprechende MethodegetProperty() zu diesem Objekt auf. Bei dieser Prüfung wird immer der aktuelle Zustand des MVC-Objekts abgerufen, der nicht mit dem Zustand des Objekts zum Zeitpunkt der Ereignisauslösung übereinstimmen muss.

Hinweis: Das explizite Festlegen einer Eigenschaft in einem Ereignishandler, die mit einer Zustandsänderung der jeweiligen Eigenschaft übereinstimmt, kann zu unvorhersehbarem bzw. unerwünschtem Verhalten führen. Das Festlegen einer entsprechenden Eigenschaft löst beispielsweise ein neues Ereignis aus, und wenn Sie immer eine Eigenschaft in diesem Ereignishandler definieren, kann dies zu einer Endlosschleife führen.

Im nachfolgenden Beispiel legen wir fest, dass ein Ereignishandler auf Zoom-Ereignisse reagieren soll, indem ein Info-Fenster mit dieser Ebene angezeigt wird.

function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}

Beispiel anzeigen (event-properties.html).

Reaktionen auf DOM-Ereignisse

Mit dem Ereignismodell von Google Maps JavaScript API werden benutzerdefinierte Ereignisse erstellt und verwaltet. Das DOM (Document Object Model) im Browser erstellt und verteilt jedoch auch eigene Ereignisse entsprechend dem jeweils verwendeten Browsermodell. Wenn Sie diese Ereignisse erfassen und darauf reagieren möchten, stellt die Maps JavaScript API die statische Methode addDomListener() bereit, um auf DOM-Ereignisse zu warten und sie zu binden.

Diese Erleichterungsmethode hat folgende Signatur:

addDomListener(instance:Object, eventName:string, handler:Function)

wobei instance ein beliebiges, browserunterstütztes DOM-Element sein kann, z. B.:

  • Hierarchische Mitglieder des DOM, wie window oder document.body.myform
  • Benannte Elemente, wie document.getElementById("foo")

Beachten Sie, dass mit addDomListener() einfach das angegebenen Ereignis an den Browser übergeben wird, in dem das Ereignis dann gemäß dem DOM-Ereignismodell des Browsers verarbeitet wird; heute unterstützen jedoch fast alle modernen Browser mindestens DOM Level 2. (Weitere Informationen zu DOM-Level-Ereignissen finden Sie in der Referenz Mozilla DOM-Level.)

Wenn Sie die Dokumentation bis an diese Stelle gelesen haben, sind Sie vermutlich bereits mit einem DOM-Element vertraut: das Ereignis window.onload, das wir im Tag <body> verarbeitet haben. Wir verwenden dieses Ereignis, um den JavaScript-Anfangscode auszulösen, sobald eine HTML-Seite vollständig geladen wurde – siehe unten:

<script>
  function initialize() {

    // Map initialization

  }
</script>
<body onload="initialize()">
  <div id="map"></div>
</body>

Obwohl dieses Ereignis hier an das Element <body> angefügt ist, ist dieses Ereignis eigentlich ein Ereignis window, mit dem angegeben wird, dass die DOM-Hierarchie unter dem Element window vollständig erstellt und wiedergegeben wurde.

Obgleich dies einfach zu verstehen ist, vermischt ein Ereignis onload innerhalb eines Tages <body> Inhalt mit Verhalten. Im Allgemeinen empfiehlt es sich in der Praxis, Inhaltscode (HTML) vom Verhaltenscode (JavaScript) zu trennen und auch den Darstellungscode (CSS) separat bereitzustellen. Ersetzen Sie dazu wie folgt in Ihrem Maps JavaScript API-Code den Inline-Ereignishandler onload durch einen DOM-Listener:

<script>
  function initialize() {

    // Map initialization

  }

  google.maps.event.addDomListener(window, 'load', initialize);
</script>
<body>
  <div id="map"></div>
</body>

Beispiel anzeigen (event-domListener.html)

Obwohl es sich beim obigen Code um Maps JavaScript API-Code handelt, wird die Methode addDomListener() an das Objekt window des Browsers gebunden und ermöglicht die API-Kommunikation mit Objekten außerhalb der regulären API-Domäne.

Ereignislistener entfernen

Um einen einzelnen Ereignislistener zu entfernen, muss dieser einer Variable zugeordnet sein. Sie können anschließend removeListener() aufrufen und den Namen der Variablen übergeben, der dieser Listener zugeordnet wurde.

var listener1 = marker.addListener('click', aFunction);

google.maps.event.removeListener(listener1);

Um alle Listener aus einer bestimmten Instanz zu entfernen, rufen Sie clearInstanceListeners() auf, und übergeben Sie den Namen der Instanz.

var listener1 = marker.addListener('click', aFunction);
var listener2 = marker.addListener('mouseover', bFunction);

// Remove listener1 and listener2 from marker instance.
google.maps.event.clearInstanceListeners(marker);

Um alle Listener zu einem bestimmten Ereignistyp zu entfernen, rufen Sie clearListeners() auf und übergeben Sie die Namen der Instanz und des Ereignisses.

marker.addListener('click', aFunction);
marker.addListener('click', bFunction);
marker.addListener('click', cFunction);

// Remove all click listeners from marker instance.
google.maps.event.clearListeners(marker, 'click');

Weitere Informationen erhalten Sie in der Referenzdokumentation zum Namensraum google.maps.event.

Warten auf Authentifizierungsfehler

Wenn Sie eine fehlgeschlagene Authentifizierung programmgesteuert erkennen möchten (zum Beispiel um automatisch ein Beacon zu senden), können Sie eine Callbackfunktion bereitstellen. Wenn die folgende globale Funktion definiert ist, wird sie bei einer fehlgeschlagenen Authentifizierung aufgerufen. function gm_authFailure() { /* Code */ };

Feedback geben zu...

Google Maps JavaScript API
Google Maps JavaScript API