Ereignisse

Plattform auswählen: Android iOS JavaScript

Auf dieser Seite werden die Ereignisse auf der Benutzeroberfläche sowie Fehlerereignisse beschrieben, die programmatisch erfasst und verarbeitet werden können.

Ereignisse auf der Benutzeroberfläche

JavaScript funktioniert im Browser ereignisgesteuert. Das heißt, es reagiert auf Interaktionen mit der Erzeugung von Ereignissen und erwartet, dass ein Programm auf auffällige Ereignisse wartet. Es gibt zwei verschiedene Arten von Ereignissen:

  • Nutzerereignisse, wie z. B. Mausklicks, werden vom DOM an die Maps JavaScript API weitergeleitet. Dies sind separate Ereignisse, die sich von standardmäßigen DOM-Ereignissen unterscheiden.
  • Benachrichtigungen zu MVC-Statusänderungen geben Aufschluss über Änderungen an Maps JavaScript API-Objekten und werden entsprechend der property_changed-Konvention benannt.

Mit jedem Maps JavaScript API-Objekt wird eine Anzahl benannter Ereignisse exportiert. Programme, für die bestimmte Ereignisse benötigt werden, registrieren JavaScript-Ereignis-Listener für die entsprechenden Ereignisse und führen Code aus, wenn die Ereignisse erfasst werden. Dabei wird addListener() aufgerufen, um Event-Handler für das Objekt zu registrieren.

Im folgenden Beispiel wird gezeigt, welche Ereignisse von google.maps.Map ausgelöst werden, wenn Sie mit der Karte interagieren.

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

Ereignisse auf der Benutzeroberfläche

Einige Objekte in der Maps JavaScript API reagieren auf Nutzerinteraktionen wie Maus- oder Tastaturereignisse. Ein google.maps.Marker-Objekt kann z. B. auf folgende Nutzerereignisse warten:

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

Die vollständige Liste finden Sie in der Klasse Markierungen. Diese Ereignisse wirken unter Umständen wie standardmäßige DOM-Ereignisse, gehören aber tatsächlich zur Maps JavaScript API. Da in den verschiedenen Browsern unterschiedliche DOM-Ereignismodelle implementiert sind, sind diese Mechanismen in der Maps JavaScript API verfügbar, um auf DOM-Ereignisse zu warten und zu reagieren, ohne die verschiedenen browserübergreifenden Besonderheiten berücksichtigen zu müssen. Mit diesen Ereignissen werden typischerweise auch Argumente im Ereignis übergeben, die einen bestimmten UI-Zustand angeben (z. B. die Mausposition).

MVC-Statusänderungen

MVC-Objekte enthalten in der Regel Statusinformationen. Wird ein Objektattribut geändert, löst die Maps JavaScript API ein entsprechendes Ereignis aus. Ein zoom_changed-Ereignis für eine Karte wird z. B. über die API ausgelöst, wenn der Zoomfaktor geändert wird. Sie können diese Statusänderungen abfangen, indem Sie addListener() aufrufen, um auch Event-Handler für das Objekt zu registrieren.

Nutzerereignisse und MVC-Statusänderungen ähneln sich vielleicht auf den ersten Blick, sollten im Code jedoch unterschiedlich verarbeitet werden. Bei MVC-Ereignissen werden z. B. im Ereignis keine Argumente übergeben. Überprüfen Sie das bei einer MVC-Statusänderung geänderte Attribut, indem Sie die entsprechende getProperty-Methode für das Objekt aufrufen.

Ereignisse verarbeiten

Verwenden Sie den addListener()-Event-Handler, um Ereignisbenachrichtigungen zu registrieren. Bei dieser Methode ist ein Ereignis erforderlich, auf das gewartet werden soll, sowie eine Funktion, die beim Eintreten des entsprechenden Ereignisses aufgerufen wird.

Beispiel: Karten- und Markierungsereignisse

Im folgenden Code werden Nutzerereignisse mit Statusänderungsereignissen kombiniert. Wir hängen einen Event-Handler an eine Markierung an, mit dem die Kartenansicht vergrößert wird, wenn ein Nutzer auf die Karte klickt. Wir fügen außerdem einen Event-Handler für Änderungen am center-Attribut in die Karte ein, sodass sie 3 Sekunden nach Eingang des center_changed-Ereignisses zurück zur Markierung schwenkt:

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

Testbeispiel

Tipp: Wenn eine Änderung im Darstellungsbereich erkannt werden soll, muss das spezifische bounds_changed-Ereignis anstelle der Ereignisse zoom_changed und center_changed verwendet werden. Da die beiden letzteren Ereignisse unabhängig über die Maps JavaScript API ausgelöst werden, liefert getBounds() unter Umständen erst dann sinnvolle Ergebnisse, wenn der Darstellungsbereich verbindlich geändert wurde. Wenn nach einem solchen Ereignis getBounds() ausgeführt werden soll, muss stattdessen auf das bounds_changed-Ereignis gewartet werden.

Beispiel: Ereignisse beim Bearbeiten und Ziehen von Formen

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

Beispiel ansehen (rectangle-event.html)

Argumente in UI-Ereignissen aufrufen

Bei UI-Ereignissen in der Maps JavaScript API wird in der Regel ein Ereignisargument übergeben, auf das der Event-Listener zugreifen kann. Dabei wird der UI-Status zum Zeitpunkt des Ereignisses erfasst. So übergibt ein UI-Ereignis vom Typ 'click' z. B. normalerweise ein MouseEvent mit einer latLng-Eigenschaft, die den angeklickten Ort auf der Karte angibt. Das gilt nur für UI-Ereignisse. Bei MVC-Statusänderungen werden keine Argumente in Ereignissen übergeben.

Sie können die Argumente des Ereignisses in einem Event-Listener ebenso aufrufen wie die Attribute eines Objekts. Im folgenden Beispiel wird ein Event-Listener zur Karte hinzugefügt und eine Markierung erstellt, wenn der Nutzer im entsprechenden Bereich 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

Testbeispiel

Closures in Ereignis-Listenern verwenden

Beim Ausführen eines Ereignis-Listeners ist es häufig vorteilhaft, private und persistente Daten an ein Objekt anzuhängen. „Private“ Instanzdaten werden von JavaScript nicht unterstützt, Closures sind aber zulässig. Mit ihnen können innere Funktionen auf äußere Variablen zugreifen. Closures in Ereignis-Listenern sind hilfreich, um auf Variablen zuzugreifen, die normalerweise nicht an Objekte angehängt werden, bei denen Ereignisse auftreten.

Im folgenden Beispiel wird eine Funktions-Closure im Event-Listener verwendet, um einer Gruppe von Markierungen eine geheime Nachricht zuzuordnen. Durch Klicken auf die einzelnen Markierungen wird ein Teil der geheimen Nachricht offengelegt, der 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

Testbeispiel

Attribute in Event-Handlern abrufen und festlegen

Bei keinem der MVC-Statusänderungsereignisse im Ereignissystem der Maps JavaScript API werden beim Auslösen des Ereignisses Argumente übergeben. Bei Nutzerereignissen werden dagegen Argumente übergeben, die überprüft werden können. Wenn Sie bei einer MVC-Statusänderung ein Attribut überprüfen müssen, sollten Sie die entsprechende getProperty()-Methode für das Objekt explizit aufrufen. Bei der Überprüfung wird immer der aktuelle Status des MVC-Objekts abgerufen. Er entspricht möglicherweise nicht dem Status zum Zeitpunkt, als das Ereignis ausgelöst wurde.

Hinweis: Das explizite Festlegen eines Attributs in einem Event-Handler, der auf eine Statusänderung dieses konkreten Attributs reagiert, kann ein unvorhersehbares und/oder unerwünschtes Verhalten nach sich ziehen. Wenn Sie ein entsprechendes Attribut festlegen, wird z. B. ein neues Ereignis ausgelöst, und wenn Sie immer ein Attribut in diesem Event-Handler definieren, kann das zu einer Endlosschleife führen.

Im folgenden Beispiel definieren wir, dass ein Event-Handler auf Zoom-Ereignisse reagieren soll, indem ein Infofenster mit der entsprechenden Ebene angezeigt wird.

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

Testbeispiel

DOM-Ereignisse beobachten

Im Maps JavaScript API-Ereignismodell werden eigene benutzerdefinierte Ereignisse erstellt und verwaltet. Das Document Object Model (DOM) im Browser erstellt jedoch auch eigene Ereignisse und löst sie aus, entsprechend dem jeweils verwendeten Browsermodell. Wenn Sie diese Ereignisse erfassen und darauf reagieren möchten, können Sie die statische addDomListener()-Methode der Maps JavaScript API nutzen, mit der auf DOM-Ereignisse gewartet und eine Verbindung zu ihnen hergestellt wird.

Diese einfache Methode hat folgende Signatur:

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

wobei instance jedes beliebige DOM-Element sein kann, das vom Browser unterstützt wird, einschließlich:

  • hierarchischen Mitgliedern des DOMs wie zum Beispiel window oder document.body.myform
  • benannten Elementen wie document.getElementById("foo")

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

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.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
Beispiel ansehen

Testbeispiel

Obwohl der Code oben Maps JavaScript API-Code ist, erstellt die addDomListener()-Methode eine Verbindung zum window-Objekt des Browsers und ermöglicht der API die Kommunikation mit Objekten außerhalb der normalen API-Domain.

Ereignis-Listener entfernen

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

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

google.maps.event.removeListener(listener1);

Wenn Sie alle Listener aus einer bestimmten Instanz entfernen möchten, 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);

Wenn Sie alle Listener für einen bestimmten Ereignistyp für eine bestimmte Instanz entfernen möchten, rufen Sie clearListeners() auf und übergeben Sie den 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 finden Sie in der Referenzdokumentation zu google.maps.event namespace.

Auf Authentifizierungsfehler warten

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