Événements

Sélectionnez une plate-forme : Android iOS JavaScript

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

Événements de l'interface utilisateur

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

• Les événements utilisateur (comme les événements de souris "clic") sont propagés du DOM vers l'API Maps JavaScript. Ils sont distincts des événements standards du DOM.
• Les notifications de changement d'état MVC reflètent les modifications intervenues dans les objets de l'API Maps JavaScript et sont nommées selon la convention property_changed.

Chaque objet de l'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 les événements en question, et exécutent du code lorsqu'ils les reçoivent en appelant addListener() pour enregistrer les gestionnaires d'événements sur l'objet.

L'exemple suivant montre les événements qui 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 listés dans une section distincte pour chaque objet qui contient des événements.

Événements de l'UI

Certains objets de l'API Maps JavaScript sont conçus pour répondre aux événements utilisateur comme les événements de souris ou de clavier. Voici quelques exemples d'événements utilisateur qu'un objet google.maps.marker.AdvancedMarkerElement peut écouter :

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

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

Changements d'état MVC

Les objets MVC comprennent généralement un état. Chaque fois que la propriété d'un objet est modifiée, l'API Maps JavaScript déclenche un événement. Par exemple, l'API déclenche un événement zoom_changed lorsque le niveau de zoom de la carte 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 en général, ils doivent être traités différemment dans le code. Les événements MVC, par exemple, ne transmettent aucun argument. Vous devez 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(). Pour utiliser cette méthode, il vous faut un événement à écouter et une fonction à appeler lorsqu'il 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. Il associe un gestionnaire d'événements à un repère qui effectue un zoom sur la carte si l'utilisateur clique dessus. Il ajoute également un gestionnaire d'événements à la carte pour les modifications apportées à la propriété center, puis déplace la carte sur le repère trois secondes après réception de l'événement center_changed :

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

Remarque:Consultez ce guide sur l'utilisation de TypeScript et Google Maps.

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

Remarque:Le code JavaScript est compilé à partir de l'extrait TypeScript.

Voir l'exemple

Essayer l'exemple

JSFiddle.net Google Cloud Shell

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 d'origine. Étant donné que l'API Maps JavaScript déclenche ces derniers indépendamment, getBounds() risque de ne pas produire de résultats exploitables tant que la fenêtre d'affichage n'a pas été modifiée. Si vous souhaitez utiliser getBounds() après un événement de ce type, veillez à écouter l'événement bounds_changed à la place.

Exemple : Modification de formes et événements de déplacement

Lorsque vous modifiez ou déplacez une forme, un événement est déclenché à la fin de l'action. Pour obtenir la liste des événements et des extraits de code, consultez Formes.

Voir un exemple (rectangle-event.html)

Accéder aux arguments des événements de l'UI

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énements peut accéder, indiquant l'état de l'interface utilisateur lorsque l'événement 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 spécifique aux événements d'interface utilisateur. Les événements de changements d'état MVC, en revanche, ne spécifient pas d'argument.

Pour accéder aux arguments de l'événement dans un écouteur d'événement, procédez de la même façon que pour accéder aux propriétés d'un objet. L'exemple de code suivant ajoute un écouteur d'événement pour la carte et, lorsque l'utilisateur clique sur la carte, crée un repère au point géographique où l'utilisateur a cliqué.

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

Remarque:Consultez ce guide sur l'utilisation de TypeScript et Google Maps.

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

Remarque:Le code JavaScript est compilé à partir de l'extrait TypeScript.

Voir l'exemple

Essayer l'exemple

JSFiddle.net Google Cloud Shell

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

Lorsque vous utilisez un écouteur d'événements, il est souvent avantageux d'associer à la fois des données privées et des données persistantes à un objet. JavaScript ne prend pas en charge les données d'instance "privées", mais il prend en charge les fermetures, qui permettent aux fonctions internes d'accéder aux variables externes. Les fermetures dans les écouteurs d'événements permettent d'accéder aux variables qui ne sont normalement pas associées aux objets concernés par les événements.

L'exemple suivant utilise une fermeture de fonction dans l'écouteur d'événement pour attribuer un message secret à un ensemble de repères. Cliquer sur chaque repère permet de révéler une partie du message secret, qui ne se trouve pas dans le repère lui-même.

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

Remarque:Consultez ce guide sur l'utilisation de TypeScript et Google Maps.

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

Remarque:Le code JavaScript est compilé à partir de l'extrait TypeScript.

Voir l'exemple

Essayer l'exemple

JSFiddle.net Google Cloud Shell

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 d'arguments lorsque l'événement est déclenché. Les événements utilisateur, en revanche, spécifient des arguments qui peuvent être examinés. Si vous devez inspecter une propriété sur 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 le même que 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. Définir une telle propriété peut déclencher un nouvel événement, par exemple. En outre, si vous définissez toujours une propriété dans ce gestionnaire d'événements, vous risquez de créer une boucle infinie.

L'exemple ci-dessous permet de configurer un gestionnaire d'événements pour répondre aux événements de zoom en affichant une fenêtre d'informations qui indique le niveau de zoom.

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

Remarque:Consultez ce guide sur l'utilisation de TypeScript et Google Maps.

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

Remarque:Le code JavaScript est compilé à partir de l'extrait TypeScript.

Voir l'exemple

Essayer l'exemple

JSFiddle.net Google Cloud Shell

É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) intégré au navigateur crée et envoie également ses propres événements, conformément au modèle d'événement utilisé par le navigateur. 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 et d'établir des liaisons avec les événements du DOM.

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

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

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

• les membres hiérarchiques du DOM, comme window ou document.body.myform ;
• les éléments nommés, comme document.getElementById("foo").

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

Remarque:Consultez ce guide sur l'utilisation de TypeScript et Google Maps.

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

Remarque:Le code JavaScript est compilé à partir de l'extrait TypeScript.

HTML

<html>
  <head>
    <title>Listening to DOM Events</title>

    <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

Voir un exemple

Essayer l'exemple

JSFiddle.net Google Cloud Shell

Bien que le code ci-dessus soit celui 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 de son domaine habituel.

Supprimer des écouteurs d'événements

Pour supprimer un écouteur d'événements spécifique, assurez-vous qu'il a été 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 en particulier, 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 utiliser la programmatique pour détecter un échec d'authentification (afin d'envoyer automatiquement une balise, par exemple), vous pouvez préparer une fonction de rappel. Si la fonction globale suivante est définie, elle sera appelée en cas d'échec de l'authentification. function gm_authFailure() { /* Code */ };