Ereignisse

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Plattform auswählen: Android iOS JavaScript

Auf dieser Seite werden die Benutzeroberflächen- und Fehlerereignisse beschrieben, die Sie überwachen und programmatisch verarbeiten können.

Benutzeroberflächenereignisse

JavaScript erfolgt im Browser ereignisgesteuert. Das heißt, es reagiert auf Interaktionen mit der Erzeugung von Ereignissen und erwartet, dass ein Programm interessante Ereignisse überwacht. Es gibt zwei Arten von Ereignissen:

  • Nutzerereignisse wie z. B. „click“-Mausereignisse werden vom DOM an die Maps JavaScript API weitergegeben. Diese Ereignisse unterscheiden sich von Standard-DOM-Ereignissen.
  • Benachrichtigungen über MVC-Statusänderungen geben Aufschluss über Änderungen an Google Maps JavaScript API-Objekten und werden entsprechend der property_changed-Konvention benannt.

Jedes Maps JavaScript API-Objekt exportiert eine Anzahl benannter Ereignisse. Programme, die bestimmte Ereignisse benötigen, registrieren JavaScript-Ereignis-Listener für diese Ereignisse und führen Code aus, wenn sie empfangen werden. Dazu rufen Sie addListener() auf, um Ereignis-Handler für das Objekt zu registrieren.

Im Beispiel unten siehst du, welche Ereignisse von google.maps.Map ausgelöst werden, wenn du mit der Karte interagierst.

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

Benutzeroberflächenereignisse

Einige Objekte in der Maps JavaScript API sind so konzipiert, dass sie auf Nutzerereignisse wie Maus- oder Tastaturereignisse reagieren. Hier sind einige der Nutzerereignisse, die ein google.maps.Marker-Objekt beobachten kann:

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

Eine vollständige Liste finden Sie in der Klasse Marker. Diese Ereignisse sehen möglicherweise wie standardmäßige DOM-Ereignisse aus, sind aber Teil der Maps JavaScript API. Da verschiedene Browser unterschiedliche DOM-Ereignismodelle implementieren, bietet die Maps JavaScript API folgende Mechanismen, um DOM-Ereignisse zu überwachen und darauf zu reagieren, ohne die verschiedenen browserübergreifenden Besonderheiten berücksichtigen zu müssen. Diese Ereignisse übergeben in der Regel auch Argumente innerhalb des Ereignisses, die einen bestimmten UI-Status angeben (z. B. die Mausposition).

Änderungen des MVC-Zustands

MVC-Objekte enthalten in der Regel einen Zustand. Immer wenn sich die Eigenschaft eines Objekts ändert, löst die Maps JavaScript API ein Ereignis aus, das durch die Eigenschaft geändert wurde. Die API löst beispielsweise ein zoom_changed-Ereignis auf einer Karte aus, wenn sich die Zoomstufe der Karte ändert. Sie können diese Statusänderungen abfangen, indem Sie addListener() aufrufen, um auch Ereignis-Handler für das Objekt zu registrieren.

Nutzerereignisse und MVC-Statusänderungen können ähnlich aussehen, möchten Sie aber in Ihrem Code normalerweise anders behandeln. MVC-Ereignisse übergeben beispielsweise keine Argumente innerhalb ihres Ereignisses. Prüfen Sie das Attribut, das bei einer MVC-Statusänderung geändert wurde. Rufen Sie dazu die entsprechende Methode getProperty für dieses Objekt auf.

Ereignisse bearbeiten

Verwenden Sie den Ereignis-Handler addListener(), um sich für Ereignisbenachrichtigungen zu registrieren. Diese Methode erfordert ein zu überwachendes Ereignis und eine Funktion, die beim Eintreten des angegebenen Ereignisses aufgerufen wird.

Beispiel: Karten- und Markierungsereignisse

Im folgenden Code werden Benutzerereignisse mit Zustandsänderungsereignissen kombiniert. Wir fügen einen Event-Handler an eine Markierung an, mit der die Karte durch Klicken maximiert wird. Außerdem fügen wir der Karte einen Ereignis-Handler für Änderungen an der Property center hinzu und schwenken die Karte 3 Sekunden nach Erhalt des Ereignisses center_changed zurück zur Markierung:

TypeScript

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

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: myLatlng,
    }
  );

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

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.getPosition() as google.maps.LatLng);
    }, 3000);
  });

  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.getPosition() as google.maps.LatLng);
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const myLatlng = { lat: -25.363, lng: 131.044 };
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: myLatlng,
  });
  const marker = new google.maps.Marker({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.getPosition());
    }, 3000);
  });
  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

window.initMap = initMap;
Beispiel ansehen

Beispiel ausprobieren

Tipp: Wenn du eine Änderung im Darstellungsbereich erkennen möchtest, verwende das spezifische Ereignis bounds_changed statt die einzelnen Ereignisse zoom_changed und center_changed. Weil die beiden letzteren Ereignisse von der Maps JavaScript API unabhängig ausgelöst werden, werden von getBounds() möglicherweise erst dann Ergebnisse gemeldet, wenn sich der Darstellungsbereich autoritativ geändert hat. Wenn nach einem solchen Ereignis getBounds() ausgeführt werden soll, solltest du stattdessen das Ereignis bounds_changed beobachten.

Beispiel: Ereignisse beim Bearbeiten und Ziehen von Formen

Wenn eine Form bearbeitet oder gezogen wird, wird nach Abschluss der Aktion ein Ereignis ausgelöst. Eine Liste der Ereignisse und einige Code-Snippets findest du unter Formen.

Beispiel ansehen (rectangle-event.html)

Argumente in UI-Ereignissen aufrufen

UI-Ereignisse in der Maps JavaScript API übergeben in der Regel ein Ereignisargument, auf das vom Ereignis-Listener zugegriffen werden kann. Dabei wird der UI-Status zum Zeitpunkt des Ereignisses angegeben. Beispielsweise gibt ein UI-'click'-Ereignis normalerweise ein MouseEvent weiter, das eine latLng-Property enthält, die den angeklickten Standort auf der Karte angibt. Dieses Verhalten tritt nur bei UI-Ereignissen auf. Änderungen des MVC-Status übergeben keine Argumente in ihren Ereignissen.

Sie können auf die Argumente des Ereignisses in einem Ereignis-Listener genauso zugreifen wie auf die Eigenschaften eines Objekts. Im folgenden Beispiel wird ein Ereignis-Listener für die Karte hinzugefügt und eine Markierung erstellt, wenn der Nutzer am angeklickten Ort auf die Karte klickt.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
    }
  );

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng: google.maps.LatLng, map: google.maps.Map) {
  new google.maps.Marker({
    position: latLng,
    map: map,
  });
  map.panTo(latLng);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

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

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

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

window.initMap = initMap;
Beispiel ansehen

Beispiel ausprobieren

Auslöser für Ereignislistener verwenden

Bei der Ausführung eines Ereignis-Listeners ist es häufig vorteilhaft, sowohl private als auch dauerhafte Daten an ein Objekt anzuhängen. JavaScript unterstützt keine privaten Instanzdaten, jedoch Schließungen, mit denen innere Funktionen auf äußere Variablen zugreifen können. Closures sind innerhalb von Ereignis-Listenern nützlich, um auf Variablen zuzugreifen, die normalerweise nicht den Objekten zugeordnet sind, für die Ereignisse auftreten.

Im folgenden Beispiel wird eine Funktion geschlossen im Ereignis-Listener verwendet, um mehreren Markierungen eine geheime Nachricht zuzuweisen. Wenn Sie auf eine Markierung klicken, wird ein Teil der geheimen Nachricht angezeigt, die nicht in der Markierung selbst enthalten ist.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
    }
  );

  const bounds: google.maps.LatLngBoundsLiteral = {
    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.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const 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: google.maps.Marker,
  secretMessage: string
) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.get("map"), marker);
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
  });
  const 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.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const 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) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.get("map"), marker);
  });
}

window.initMap = initMap;
Beispiel ansehen

Beispiel ausprobieren

Eigenschaften in Ereignis-Handlern abrufen und festlegen

Keines der MVC-Statusänderungsereignisse im Ereignissystem der Maps JavaScript API übergibt Argumente, wenn das Ereignis ausgelöst wird. Nutzerereignisse übergeben Argumente, die überprüft werden können. Wenn Sie bei einer MVC-Statusänderung ein Attribut prüfen müssen, sollten Sie die entsprechende Methode getProperty() für dieses Objekt explizit aufrufen. Diese Prüfung ruft immer den aktuellen Status des MVC-Objekts ab. Dieser entspricht möglicherweise nicht dem Status, als das Ereignis zum ersten Mal ausgelöst wurde.

Hinweis: Das explizite Festlegen einer Property in einem Ereignis-Handler, der auf eine Statusänderung dieser Property reagiert, kann unvorhersehbares und/oder unerwünschtes Verhalten nach sich ziehen. Das Festlegen eines solchen Attributs löst beispielsweise ein neues Ereignis aus. Wenn du in diesem Ereignis-Handler immer ein Attribut festlegst, kann es zu einer Endlosschleife kommen.

Im folgenden Beispiel haben wir einen Ereignis-Handler eingerichtet, der auf Zoom-Ereignisse reagiert, indem ein Infofenster angezeigt wird, das diese Ebene anzeigt.

TypeScript

function initMap(): void {
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: originalMapCenter,
    }
  );

  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);

  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom()!);
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: originalMapCenter,
  });
  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);
  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom());
  });
}

window.initMap = initMap;
Beispiel ansehen

Beispiel ausprobieren

Reaktionen auf DOM-Ereignisse

Im Maps JavaScript API-Ereignismodell werden eigene benutzerdefinierte Ereignisse erstellt und verwaltet. Das DOM (Document Object Model) im Browser erstellt und sendet jedoch auch eigene Ereignisse, die sich nach dem jeweils verwendeten Browserereignismodell richten. Wenn Sie diese Ereignisse erfassen und darauf reagieren möchten, bietet die Maps JavaScript API die statische Methode addDomListener(), um DOM-Ereignisse zu erfassen und zu binden.

Diese Erleichterungsmethode hat folgende Signatur:

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

Dabei kann instance jedes DOM-Element sein, das vom Browser unterstützt wird, darunter:

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

Beachten Sie, dass addDomListener() das angegebene Ereignis an den Browser übergibt, der es dann gemäß dem DOM-Ereignismodell behandelt. In fast allen modernen Browsern wird jedoch mindestens die DOM-Ebene 2 unterstützt. Weitere Informationen zu Ereignissen auf DOM-Ebene findest du in der Referenz zu Mozilla DOM Levels.

TypeScript

function initMap(): void {
  const mapDiv = document.getElementById("map") as HTMLElement;
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

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

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

window.initMap = initMap;

HTML

<html>
  <head>
    <title>Listening to DOM Events</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
Beispiel ansehen

Beispiel ausprobieren

Obwohl der oben stehende Code ein Maps JavaScript API-Code ist, nimmt die addDomListener()-Methode eine Bindung an das window-Objekt des Browsers vor und ermöglicht der API die Kommunikation mit Objekten außerhalb der normalen API-Domain.

Ereignislistener entfernen

Wenn Sie einen bestimmten Ereignis-Listener entfernen möchten, muss er einer Variablen zugewiesen sein. Sie können dann removeListener() aufrufen und den Variablennamen übergeben, dem der Listener zugewiesen ist.

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

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 für einen bestimmten Ereignistyp für eine bestimmte Instanz zu entfernen, rufen Sie clearListeners() auf und übergeben Sie den Instanznamen und den Ereignisnamen.

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 finden Sie in der Referenzdokumentation zum Namespace google.maps.event.

Warten auf Authentifizierungsfehler

Wenn Sie programmatisch einen Authentifizierungsfehler erkennen möchten (z. B. um automatisch ein Beacon zu senden), können Sie eine Callback-Funktion vorbereiten. Wenn die folgende globale Funktion definiert ist, wird sie aufgerufen, wenn die Authentifizierung fehlschlägt. function gm_authFailure() { /* Code */ };