Eventi

In questa pagina vengono descritti gli eventi dell'interfaccia utente e gli eventi di errore che puoi ascoltare e gestire in modo programmatico.

Eventi interfaccia utente

JavaScript all'interno del browser è basato sugli eventi, il che significa che JavaScript risponde alle interazioni generando eventi e si aspetta che un programma rilevi gli eventi interessanti. Esistono due tipi di eventi:

• Gli eventi utente (ad esempio gli eventi "clic" per mouse) vengono propagati dal DOM all'API Maps JavaScript. Questi eventi sono separati e distinti dagli eventi DOM standard.
• Le notifiche di modifica dello stato MVC riflettono le modifiche apportate agli oggetti dell'API Maps JavaScript e vengono denominate utilizzando una convenzione property_changed.

Ogni oggetto API JavaScript di Maps esporta una serie di eventi denominati. I programmi interessati a determinati eventi registreranno i listener di eventi JavaScript per tali eventi ed eseguiranno il codice al momento della ricezione di tali eventi chiamando addListener() per registrare i gestori di eventi nell'oggetto.

L'esempio seguente mostra quali eventi vengono attivati da google.maps.Map quando interagisci con la mappa.

Per un elenco completo degli eventi, consultate la documentazione di riferimento dell'API Maps JavaScript. Gli eventi sono elencati in una sezione separata per ogni oggetto che contiene gli eventi.

Eventi UI

Alcuni oggetti all'interno dell'API Maps JavaScript sono progettati per rispondere a eventi utente quali eventi del mouse o della tastiera. Ad esempio, questi sono alcuni degli eventi utente che un oggetto google.maps.Marker può ascoltare:

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

Per l'elenco completo, consulta la classe Marker. Questi eventi potrebbero sembrare eventi DOM standard, ma in realtà fanno parte dell'API Maps JavaScript. Poiché diversi browser implementano modelli di eventi DOM diversi, l'API Maps JavaScript fornisce questi meccanismi per ascoltare gli eventi DOM e rispondere senza dover gestire le varie peculiarità del browser. In genere, questi eventi trasmettono argomenti all'interno dell'evento anche se indicano uno stato della UI (ad esempio la posizione del mouse).

Modifiche stato MVC

In genere gli oggetti MVC contengono lo stato. Ogni volta che la proprietà di un oggetto cambia, l'API Maps JavaScript attiva un evento che la proprietà è stata modificata. Ad esempio, l'API attiva un evento zoom_changed su una mappa quando il livello di zoom della mappa cambia. Puoi intercettare queste modifiche di stato chiamando addListener() anche per registrare i gestori di eventi nell'oggetto.

Gli eventi utente e le modifiche dello stato MVC possono avere un aspetto simile, ma in genere vuoi trattarli in modo diverso nel codice. Gli eventi MVC, ad esempio, non trasmettono argomenti all'interno del relativo evento. Ti consigliamo di ispezionare la proprietà che è stata modificata in seguito a una modifica dello stato MVC chiamando il metodo getProperty appropriato per l'oggetto in questione.

Gestione degli eventi

Per registrarti alle notifiche di eventi, utilizza il gestore di eventi addListener(). Tale metodo richiede un evento in ascolto e una funzione da chiamare quando si verifica l'evento specificato.

Esempio: eventi mappa e indicatori

Il seguente codice unisce gli eventi utente agli eventi di modifica dello stato. Alleghiamo un gestore di eventi a un indicatore che esegue lo zoom della mappa quando viene fatto clic. Inoltre, aggiungiamo un gestore di eventi alla mappa per apportare modifiche alla proprietà center e spostiamo nuovamente la mappa sull'indicatore dopo tre secondi dal ricevimento dell'evento center_changed:

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;
index.ts

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;
index.js

Suggerimento: se stai cercando di rilevare una modifica nell'area visibile, assicurati di utilizzare l'evento bounds_changed specifico, anziché gli eventi zoom_changed e center_changed. Poiché l'API Maps JavaScript attiva questi ultimi eventi in modo indipendente, getBounds() potrebbe non segnalare risultati utili finché l'area visibile non è stata modificata intenzionalmente. Se vuoi getBounds() dopo questo evento, assicurati di ascoltare l'evento bounds_changed.

Esempio: eventi di modifica e trascinamento di forme

Quando una forma viene modificata o trascinata, un evento viene attivato al termine dell'azione. Per un elenco degli eventi e di alcuni snippet di codice, consulta Forme.

Visualizza l'esempio (rectangle-event.html)

Accesso ad argomenti negli eventi UI

In genere, gli eventi UI all'interno dell'API Maps JavaScript trasmettono un argomento evento, a cui il listener di eventi può accedere, prendendo nota dello stato della UI quando si è verificato l'evento. Ad esempio, un evento 'click' dell'interfaccia utente in genere trasmette un MouseEvent contenente una proprietà latLng che indica la posizione selezionata sulla mappa. Tieni presente che questo comportamento è univoco per gli eventi UI; le modifiche dello stato MVC non trasmettono argomenti nei relativi eventi.

Puoi accedere agli argomenti dell'evento all'interno di un listener di eventi allo stesso modo in cui accedi alle proprietà di un oggetto. L'esempio riportato di seguito aggiunge un listener di eventi per la mappa e crea un indicatore quando l'utente fa clic sulla mappa in corrispondenza della località selezionata.

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;
index.ts

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;
index.js

Utilizzo delle chiusure nei listener di eventi

Quando si esegue un listener di eventi, è spesso vantaggioso avere dati privati e permanenti collegati a un oggetto. JavaScript non supporta i dati di istanza "privati", ma supporta chiusure che consentono alle funzioni interne di accedere alle variabili esterne. Le chiusure sono utili all'interno dei listener di eventi per accedere alle variabili normalmente non collegate agli oggetti su cui si verificano gli eventi.

L'esempio seguente utilizza una chiusura di funzione nel listener di eventi per assegnare un messaggio secret a un set di indicatori. Fai clic su ogni indicatore per visualizzare una parte del messaggio segreto, che non è incluso nell'indicatore stesso.

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;
index.ts

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;
index.js

Recupero e impostazione delle proprietà all'interno dei gestori di eventi

Nessuno degli eventi di modifica di stato MVC nel sistema di eventi dell'API JavaScript di Maps trasmette argomenti quando l'evento viene attivato. (Gli eventi utente trasmettono argomenti che possono essere ispezionati). Se devi esaminare una proprietà su una modifica dello stato MVC, devi chiamare esplicitamente il metodo getProperty() appropriato per l'oggetto in questione. Questa ispezione recupera sempre lo stato attuale dell'oggetto MVC, che potrebbe non essere lo stato quando l'evento è stato attivato per la prima volta.

Nota: l'impostazione esplicita di una proprietà all'interno di un gestore di eventi in risposta a un cambiamento di stato della proprietà specifica può produrre comportamenti imprevedibili e/o indesiderati. Se imposti una proprietà di questo tipo, verrà attivato un nuovo evento e, se imposti sempre una proprietà in questo gestore di eventi, potresti creare un loop infinito.

Nell'esempio seguente, abbiamo configurato un gestore di eventi per rispondere agli eventi di zoom visualizzando una finestra informativa che mostra quel livello.

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;
index.ts

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;
index.js

In ascolto di eventi DOM

Il modello di evento dell'API Maps JavaScript crea e gestisce i propri eventi personalizzati. Tuttavia, il DOM (Document Object Model) all'interno del browser crea e invia anche i propri eventi, in base al modello di evento del browser in uso. Se vuoi acquisire e rispondere a questi eventi, l'API Maps JavaScript fornisce il metodo statico addDomListener() per ascoltare gli eventi DOM e associarli.

Questo metodo ha una firma come mostrato di seguito:

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

dove instance può essere qualsiasi elemento DOM supportato dal browser, tra cui:

• Membri gerarchici del DOM, ad esempio window o document.body.myform
• Elementi con nome, ad esempio document.getElementById("foo")

Tieni presente che addDomListener() trasmette l'evento indicato al browser, che lo gestisce in base al modello di evento DOM del browser; tuttavia, quasi tutti i browser moderni supportano almeno il livello 2. Per ulteriori informazioni sugli eventi del livello DOM, consulta il riferimento Livelli DOM Mozilla.

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;
index.ts

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;
index.js

<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>
index.html

Sebbene il codice sopra riportato sia il codice API di JavaScript per Maps, il metodo addDomListener() si associa all'oggetto window del browser e consente all'API di comunicare con oggetti al di fuori del normale dominio dell'API.

Rimozione dei listener di eventi

Per rimuovere un listener di eventi specifico, deve essere stato assegnato a una variabile. Puoi quindi chiamare removeListener(), trasmettendo il nome della variabile a cui è stato assegnato il listener.

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

google.maps.event.removeListener(listener1);

Per rimuovere tutti i listener da una determinata istanza, chiama clearInstanceListeners(), trasmettendo il nome dell'istanza.

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

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

Per rimuovere tutti i listener per un tipo di evento specifico per un'istanza specifica, chiama clearListeners(), trasmettendo il nome dell'istanza e il nome dell'evento.

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');

Per ulteriori informazioni, consulta la documentazione di riferimento per lo spazio dei nomi google.maps.event.

In ascolto di errori di autenticazione

Se vuoi rilevare in modo programmatico un errore di autenticazione (ad esempio per inviare automaticamente un beacon), puoi preparare una funzione di callback. Se la seguente funzione globale è stata definita, verrà chiamata quando l'autenticazione non va a buon fine. function gm_authFailure() { /* Code */ };