Ereignisse

Plattform auswählen: Android iOS JavaScript

Auf dieser Seite werden die Ereignisse auf der Benutzeroberfläche und 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 relevante Ereignisse wartet. Es gibt zwei verschiedene Arten von Ereignissen:

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

Mit jedem Maps JavaScript API-Objekt wird eine Anzahl benannter Ereignisse exportiert. Programme, für die bestimmte Ereignisse benötigt werden, registrieren JavaScript-Event-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.AdvancedMarkerElement-Objekt kann z. B. auf folgende Nutzerereignisse warten:

  • 'click'
  • 'drag'
  • 'dragend'
  • 'dragstart'
  • 'gmp-click'

Die vollständige Liste finden Sie in der Klasse AdvancedMarkerElement. 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 eine Objekteigenschaft geändert, löst die Maps JavaScript API ein entsprechendes Ereignis aus. Ein zoom_changed-Ereignis für eine Karte wird über die API z. B. dann 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 die bei einer MVC-Statusänderung geänderte Eigenschaft, 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 an der center-Eigenschaft in die Karte ein, sodass sie 3 Sekunden nach Eingang des center_changed-Ereignisses zurück zur Markierung schwenkt:

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const myLatlng = { lat: -25.363, lng: 131.044 };

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

  const marker = new google.maps.marker.AdvancedMarkerElement({
    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.position as google.maps.LatLng);
    }, 3000);
  });

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

initMap();
index.ts

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const myLatlng = { lat: -25.363, lng: 131.044 };
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: myLatlng,
    mapId: "DEMO_MAP_ID",
  });
  const marker = new google.maps.marker.AdvancedMarkerElement({
    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.position);
    }, 3000);
  });
  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.position);
  });
}

initMap();
index.js
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 im Moment 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 genauso aufrufen wie die Eigenschaften eines Objekts. Im folgenden Beispiel wird der Karte ein Event-Listener hinzugefügt und eine Markierung erstellt, wenn der Nutzer im entsprechenden Bereich auf die Karte klickt:

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

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

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

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

initMap();
index.ts

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary(
    "marker",
  );
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });

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

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

initMap();
index.js
Beispiel ansehen

Testbeispiel

Closures für Event-Listener verwenden

Beim Ausführen eines Event-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 Event-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

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

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

  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.AdvancedMarkerElement({
      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.AdvancedMarkerElement,
  secretMessage: string
) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

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

initMap();
index.ts

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });
  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.AdvancedMarkerElement({
      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.map, marker);
  });
}

initMap();
index.js
Beispiel ansehen

Testbeispiel

Eigenschaften in Event-Handlern abrufen und festlegen

Bei keinem Ereignis einer MVC-Statusänderung 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 eine Eigenschaft ü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 einer Eigenschaft in einem Event-Handler, der auf eine Statusänderung dieser konkreten Eigenschaft reagiert, kann ein unvorhersehbares und/oder unerwünschtes Verhalten nach sich ziehen. Wenn Sie eine entsprechende Eigenschaft festlegen, wird z. B. ein neues Ereignis ausgelöst, und wenn Sie immer eine Eigenschaft 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

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

  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()!);
  });
}

initMap();
index.ts

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  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());
  });
}

initMap();
index.js
Beispiel ansehen

Testbeispiel

Auf DOM-Ereignisse warten

Im Ereignismodell der Maps JavaScript API werden eigene benutzerdefinierte Ereignisse erstellt und verwaltet. Das Document Object Model (DOM) im Browser erstellt jedoch auch eigene Ereignisse und löst sie aus. Dies geschieht entsprechend dem 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 die Signatur

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

Dabei kann instance jedes beliebige DOM-Element sein, 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

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

  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!");
  });
}

initMap();
index.ts

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  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!");
  });
}

initMap();
index.js

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>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html
Beispiel ansehen

Testbeispiel

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

Event-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 */ };