Eventi

Seleziona la piattaforma: Android iOS JavaScript

Questa pagina descrive gli eventi dell'interfaccia utente e gli eventi di errore che puoi ascoltare e gestire in modo programmatico.

Eventi dell'interfaccia utente

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

  • Gli eventi utente (come gli eventi del mouse "click") 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 negli oggetti dell'API Maps JavaScript e vengono denominate utilizzando una convenzione property_changed.

Ogni oggetto dell'API Maps JavaScript esporta una serie di eventi denominati. I programmi interessati a determinati eventi registreranno listener di eventi JavaScript per questi eventi ed eseguiranno il codice quando questi eventi vengono ricevuti chiamando addListener() per registrare i gestori di eventi sull'oggetto.

Il seguente esempio mostra gli eventi attivati da google.maps.Map mentre interagisci con la mappa.

Per un elenco completo degli eventi, consulta i riferimenti dell'API Maps JavaScript. Gli eventi sono elencati in una sezione separata per ogni oggetto che li contiene.

Eventi UI

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

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

Per l'elenco completo, consulta la classe AdvancedMarkerElement. Questi eventi possono sembrare eventi DOM standard, ma in realtà fanno parte dell'API Maps JavaScript. Poiché browser diversi implementano modelli di eventi DOM diversi, l'API Maps JavaScript fornisce questi meccanismi per ascoltare e rispondere agli eventi DOM senza dover gestire le varie peculiarità cross-browser. In genere, questi eventi passano anche argomenti all'interno dell'evento, annotando alcuni stati dell'interfaccia utente (ad esempio la posizione del mouse).

Modifiche allo stato MVC

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

Gli eventi utente e le modifiche dello stato MVC possono sembrare simili, ma devi trattarli in modo diverso nel tuo codice. Gli eventi MVC, ad esempio, non passano argomenti all'interno dell'evento. Ispeziona la proprietà che è cambiata in seguito a una modifica dello stato MVC chiamando il metodo getProperty appropriato su quell'oggetto.

Gestire gli eventi

Per registrarti alle notifiche degli eventi, utilizza il gestore di eventi addListener(). Questo metodo accetta un evento da ascoltare e una funzione da chiamare quando si verifica l'evento specificato.

Esempio: eventi di mappa e indicatore

Il seguente codice combina gli eventi utente con gli eventi di modifica dello stato. Questo esempio associa un gestore di eventi a un indicatore che aumenta lo zoom della mappa quando viene fatto clic. Inoltre, associa un gestore di eventi alla mappa per le modifiche alla proprietà center e sposta la mappa sull'indicatore dopo 3 secondi dalla ricezione dell'evento center_changed.

TypeScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps')) as google.maps.MapsLibrary;
    (await google.maps.importLibrary('marker')) as google.maps.MarkerLibrary;

    // Retrieve the map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map from the map element.
    const innerMap = mapElement.innerMap;

    const center = mapElement.center;

    const marker = new google.maps.marker.AdvancedMarkerElement({
        position: center,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });

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

    // Zoom in when the marker is clicked.
    marker.addListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(marker.position as google.maps.LatLng);
    });
}

initMap();
index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps'));
    (await google.maps.importLibrary('marker'));
    // Retrieve the map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map from the map element.
    const innerMap = mapElement.innerMap;
    const center = mapElement.center;
    const marker = new google.maps.marker.AdvancedMarkerElement({
        position: center,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });
    innerMap.addListener('center_changed', () => {
        // 3 seconds after the center of the map has changed,
        // pan back to the marker.
        window.setTimeout(() => {
            innerMap.panTo(marker.position);
        }, 3000);
    });
    // Zoom in when the marker is clicked.
    marker.addListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(marker.position);
    });
}
initMap();
index.js
Visualizza esempio

Prova campione

Suggerimento: se stai cercando di rilevare una modifica nella finestra, assicurati di utilizzare l'evento bounds_changed specifico anziché gli eventi zoom_changed e center_changed costituenti. Poiché l'API Maps JavaScript attiva questi ultimi eventi in modo indipendente, getBounds() potrebbe non restituire risultati utili finché la visualizzazione non è cambiata in modo definitivo. Se vuoi getBounds() dopo un evento di questo tipo, assicurati di ascoltare l'evento bounds_changed.

Esempio: eventi di modifica e trascinamento delle forme

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

Visualizza l'esempio (rectangle-event.html)

Accedere agli argomenti negli eventi UI

Gli eventi dell'interfaccia utente all'interno dell'API Maps JavaScript in genere passano un argomento evento, a cui è possibile accedere tramite il listener di eventi, annotando lo stato dell'interfaccia utente quando si è verificato l'evento. Ad esempio, un evento 'click' dell'interfaccia utente in genere passa un MouseEvent contenente una proprietà latLng che indica la posizione su cui è stato fatto clic sulla mappa. Tieni presente che questo comportamento è specifico degli eventi dell'interfaccia utente; le modifiche dello stato MVC non passano argomenti nei relativi eventi.

Puoi accedere agli argomenti dell'evento all'interno di un listener di eventi nello stesso modo in cui accedi alle proprietà di un oggetto. Il seguente esempio aggiunge un listener di eventi per la mappa e crea un indicatore quando l'utente fa clic sulla mappa nella posizione in cui ha fatto clic.

TypeScript

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

  const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
  const innerMap = mapElement.innerMap;

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

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.
    await google.maps.importLibrary("maps");
    await google.maps.importLibrary("marker");
    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    innerMap.addListener("click", (e) => {
        placeMarkerAndPanTo(e.latLng, innerMap);
    });
}
function placeMarkerAndPanTo(latLng, map) {
    new google.maps.marker.AdvancedMarkerElement({
        position: latLng,
        map: map,
    });
    map.panTo(latLng);
}
initMap();
index.js
Visualizza esempio

Prova campione

Utilizzare le chiusure nei listener di eventi

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

L'esempio seguente utilizza una chiusura di funzione nel listener di eventi per assegnare un messaggio segreto a un insieme di indicatori. Se fai clic su ogni indicatore, viene visualizzata una parte del messaggio segreto, che non è contenuta nell'indicatore stesso.

TypeScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps')) as google.maps.MapsLibrary;
    (await google.maps.importLibrary('marker')) as google.maps.MarkerLibrary;

    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;
    const innerMap = mapElement.innerMap;

    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.
    innerMap.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: innerMap,
        });

        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('gmp-click', () => {
        infowindow.open(marker.map, marker);
    });
}

initMap();
index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps'));
    (await google.maps.importLibrary('marker'));
    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    const bounds = {
        north: -25.363882,
        south: -31.203405,
        east: 131.044922,
        west: 125.244141,
    };
    // Display the area between the location southWest and northEast.
    innerMap.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: innerMap,
        });
        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('gmp-click', () => {
        infowindow.open(marker.map, marker);
    });
}
initMap();
index.js
Visualizza esempio

Prova campione

Ottenere e impostare proprietà all'interno dei gestori di eventi

Nessuno degli eventi di modifica dello stato MVC nel sistema di eventi dell'API Maps JavaScript passa argomenti quando l'evento viene attivato. (Gli eventi utente passano argomenti che possono essere esaminati.) Se devi esaminare una proprietà in una modifica dello stato MVC, devi chiamare esplicitamente il metodo getProperty() appropriato per quell'oggetto. Questa ispezione recupererà sempre lo stato attuale dell'oggetto MVC, che potrebbe non essere lo stato al momento dell'attivazione dell'evento.

Nota: l'impostazione esplicita di una proprietà all'interno di un gestore di eventi che risponde a una modifica dello stato di quella particolare proprietà può produrre un comportamento imprevedibile e/o indesiderato. L'impostazione di una proprietà di questo tipo attiverà un nuovo evento, ad esempio, e se imposti sempre una proprietà all'interno di questo gestore di eventi, potresti creare un loop infinito.

L'esempio seguente mostra come configurare un gestore di eventi per rispondere agli eventi di zoom visualizzando una finestra informativa che mostra il livello.

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
Visualizza esempio

Prova campione

Rimuovi listener di eventi

Per rimuovere un listener di eventi specifico, deve essere stato assegnato a una variabile. A questo punto, puoi chiamare removeListener(), passando 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(), passando 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(), passando 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 saperne di più, consulta la documentazione di riferimento per lo spazio dei nomi google.maps.event.

Ascolto di errori di autenticazione

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

In TypeScript, potrebbe essere necessario aggiungere la funzione all'ambito globale come mostrato di seguito:

// Define the callback function.
window.gm_authFailure = () => {
  console.error("Google Maps failed to authenticate.");
  /* Code */
};

// Add gm_authFailure to the global scope.
declare global {
  interface Window {
    gm_authFailure?: () => void;
  }
}
export {};