Événements

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
Sélectionnez une plate-forme: Android iOS JavaScript

Cette page décrit les événements d'interface utilisateur et les événements d'erreur que vous pouvez écouter et gérer de manière automatisée.

Événements de l'interface utilisateur

JavaScript dans le navigateur est basé sur des événements. En d'autres termes, JavaScript répond aux interactions en générant des événements et s'attend à ce qu'un programme écoute les événements intéressants. Il existe deux types d'événements:

  • Les événements utilisateur (tels que les clics de souris, par exemple) sont propagés du DOM vers l'API Maps JavaScript. Ces événements sont différents des événements DOM standards.
  • Les notifications de changement d'état MVC reflètent les modifications apportées aux objets de l'API Maps JavaScript et sont nommées selon une convention property_changed.

Chaque objet API Maps JavaScript exporte un certain nombre d'événements nommés. Les programmes intéressés par certains événements enregistrent des écouteurs d'événements JavaScript pour ces événements et exécutent du code lorsque ces événements sont reçus en appelant addListener() pour enregistrer les gestionnaires d'événements sur l'objet.

L'exemple ci-dessous vous montre quels événements sont déclenchés par google.maps.Map lorsque vous interagissez avec la carte.

Pour obtenir la liste complète des événements, consultez la documentation de référence de l'API Maps JavaScript. Les événements sont répertoriés dans une section distincte pour chaque objet qui contient des événements.

Événements d'interface utilisateur

Certains objets de l'API Maps JavaScript sont conçus pour répondre aux événements utilisateur tels que les événements de souris ou de clavier. Par exemple, voici quelques-uns des événements utilisateur qu'un objet google.maps.Marker peut écouter:

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

Pour obtenir la liste complète, consultez la classe Marker. Ces événements peuvent ressembler à des événements DOM standards, mais ils font en fait partie de l'API Maps JavaScript. Étant donné que différents navigateurs mettent en œuvre différents modèles d'événements DOM, l'API Maps JavaScript fournit ces mécanismes pour écouter les événements DOM et y répondre sans avoir à gérer les diverses particularités de chaque navigateur. De plus, ces événements transmettent généralement des arguments indiquant un état de l'interface utilisateur (par exemple, la position de la souris).

Changements d'état MVC

Les objets MVC comprennent généralement un état. Chaque fois qu'un objet change, l'API Maps JavaScript déclenche un événement correspondant. Par exemple, l'API déclenche un événement zoom_changed sur une carte lorsque le niveau de zoom change. Vous pouvez également intercepter ces changements d'état en appelant addListener() pour enregistrer les gestionnaires d'événements sur l'objet.

Les événements utilisateur et les changements d'état MVC peuvent sembler similaires, mais vous souhaitez généralement les traiter différemment dans votre code. Les événements MVC, par exemple, ne transmettent pas d'arguments dans leur événement. Vous allez inspecter la propriété qui a changé pour un état MVC en appelant la méthode getProperty appropriée sur cet objet.

Gérer les événements

Pour vous inscrire aux notifications d'événements, utilisez le gestionnaire d'événements addListener(). Cette méthode nécessite un événement à écouter et une fonction à appeler lorsque l'événement spécifié se produit.

Exemple: événements de carte et de repère

Le code suivant combine des événements utilisateur et des événements de changement d'état. Nous associons un gestionnaire d'événements à un repère qui zoome sur la carte lorsque l'utilisateur clique dessus. Nous ajoutons également un gestionnaire d'événements à la carte pour les modifications apportées à la propriété center, puis nous déplaçons la carte sur le repère trois secondes après réception de l'événement center_changed:

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;
Voir un exemple

Essayer l'exemple

Conseil: Si vous essayez de détecter un changement dans la fenêtre d'affichage, veillez à utiliser l'événement bounds_changed spécifique plutôt que les événements zoom_changed et center_changed constitutifs. Étant donné que l'API Maps JavaScript déclenche ces derniers événements indépendamment, getBounds() peut ne pas générer de résultats utiles tant que la fenêtre d'affichage n'a pas fait autorité. Si vous souhaitez getBounds() après un tel événement, veillez à écouter l'événement bounds_changed à la place.

Exemple: Modifier et faire glisser des événements

Lorsqu'une forme est modifiée ou déplacée, un événement est déclenché à la fin de l'action. Pour obtenir la liste des événements et des extraits de code, consultez la page Formes.

Voir un exemple (rectangle-event.html)

Accéder aux arguments des événements de l'interface utilisateur

Les événements d'interface utilisateur dans l'API Maps JavaScript transmettent généralement un argument d'événement auquel l'écouteur d'événement peut accéder, notant l'état de l'interface utilisateur lorsqu'il s'est produit. Par exemple, un événement 'click' d'interface utilisateur transmet généralement un MouseEvent contenant une propriété latLng indiquant l'emplacement sur lequel l'utilisateur a cliqué sur la carte. Notez que ce comportement est propre aux événements d'interface utilisateur. Les changements d'état MVC ne transmettent pas d'arguments dans leurs événements.

Vous pouvez accéder aux arguments de l'événement dans un écouteur d'événements de la même manière que vous accédez aux propriétés d'un objet. L'exemple suivant ajoute un écouteur d'événements pour la carte et crée un repère lorsque l'utilisateur clique sur la carte à l'emplacement indiqué.

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;
Voir un exemple

Essayer l'exemple

Utiliser des fermetures dans les écouteurs d'événement

Lors de l'exécution d'un écouteur d'événements, il est souvent avantageux d'associer des données privées et persistantes à un objet. JavaScript n'est pas compatible avec les données d'instance privées, mais il est compatible avec les fermetures, qui permettent aux fonctions internes d'accéder aux variables externes. Les fermetures sont utiles dans les écouteurs d'événements pour accéder aux variables qui ne sont généralement pas associées aux objets sur lesquels des événements se produisent.

L'exemple suivant utilise une fermeture de fonction dans l'écouteur d'événements pour attribuer un message secret à un ensemble de repères. Cliquez sur chaque repère pour afficher une partie du message secret, qui n'est pas contenu dans le repère lui-même.

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;
Voir un exemple

Essayer l'exemple

Obtenir et définir des propriétés dans les gestionnaires d'événements

Aucun des événements de changement d'état MVC dans le système d'événements de l'API Maps JavaScript ne transmet de arguments lorsque l'événement est déclenché. (Les événements utilisateur transmettent des arguments qui peuvent être inspectés.) Si vous devez inspecter une propriété lors d'un changement d'état MVC, vous devez appeler explicitement la méthode getProperty() appropriée sur cet objet. Cette inspection récupérera toujours l'état actuel de l'objet MVC, qui peut ne pas être l'état lorsque l'événement a été déclenché pour la première fois.

Remarque : Définir explicitement une propriété dans un gestionnaire d'événements qui répond à un changement d'état de cette propriété peut entraîner un comportement imprévisible et/ou indésirable. Par exemple, définir une telle propriété déclenche un nouvel événement. Si vous définissez toujours une propriété dans ce gestionnaire d'événements, vous risquez de créer une boucle infinie.

Dans l'exemple ci-dessous, nous configurons un gestionnaire d'événements pour répondre aux événements de zoom en ouvrant une fenêtre d'informations qui affiche ce niveau.

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;
Voir un exemple

Essayer l'exemple

Écouter les événements DOM

Le modèle d'événement de l'API Maps JavaScript crée et gère ses propres événements personnalisés. Toutefois, le DOM (Document Object Model) dans le navigateur crée et envoie également ses propres événements, en fonction du modèle d'événement de navigateur utilisé. Si vous souhaitez capturer ces événements et y répondre, l'API Maps JavaScript fournit la méthode statique addDomListener() qui permet d'écouter les événements DOM et de les lier.

Cette méthode pratique présente la signature suivante :

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

instance peut être n'importe quel élément DOM compatible avec le navigateur, y compris:

  • Membres hiérarchiques du DOM, tels que window ou document.body.myform
  • Éléments nommés, par exemple document.getElementById("foo")

Notez que addDomListener() transmet l'événement indiqué au navigateur, qui le gère selon le modèle d'événement DOM du navigateur. Toutefois, la plupart des navigateurs récents sont au moins compatibles avec le niveau DOM 2. (Pour en savoir plus sur les événements DOM, consultez la documentation de référence sur 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>
Voir un exemple

Essayer l'exemple

Bien que le code ci-dessus soit le code de l'API Maps JavaScript, la méthode addDomListener() est liée à l'objet window du navigateur et permet à l'API de communiquer avec des objets en dehors du domaine normal de l'API.

Supprimer des écouteurs d'événement

Pour supprimer un écouteur d'événements spécifique, vous devez l'avoir attribué à une variable. Vous pouvez ensuite appeler removeListener() en transmettant le nom de la variable à laquelle l'écouteur a été attribué.

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

google.maps.event.removeListener(listener1);

Pour supprimer tous les écouteurs d'une instance particulière, appelez clearInstanceListeners() en transmettant le nom de l'instance.

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

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

Pour supprimer tous les écouteurs d'un type d'événement spécifique pour une instance spécifique, appelez clearListeners() en transmettant le nom de l'instance et le nom de l'événement.

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

Pour en savoir plus, consultez la documentation de référence sur l'espace de noms google.maps.event.

Écouter les erreurs d'authentification

Si vous souhaitez détecter de manière automatisée un échec d'authentification (par exemple, pour envoyer automatiquement une balise), vous pouvez préparer une fonction de rappel. Si la fonction globale suivante est définie, elle est appelée en cas d'échec de l'authentification. function gm_authFailure() { /* Code */ };