Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Maps JavaScript API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou sélectionner un projet
  2. Activer Google Maps JavaScript API et les services connexes
  3. Créer les clés appropriées
Continuer

Événements

Cette page décrit les événements de l'interface utilisateur et les événements d'erreur que vous pouvez écouter et gérer par programmation.

Événements de l'interface utilisateur

Dans le navigateur, JavaScript se base sur les événements : il répond aux interactions en générant des événements, et présume qu'un programme va écouter les événements intéressants. Il existe deux types d'événements :

  • Les événements utilisateur (clic de la souris, par exemple) sont propagés du DOM vers Google Maps JavaScript API. Ils sont distincts des événements DOM standard.
  • Les notifications de changement d'état MVC correspondent aux changements qui se produisent dans les objets Maps JavaScript API. Elles sont nommées conformément à la convention property_changed.

Chaque objet Maps JavaScript API 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 en cas de réception de ces événements en appelant addListener() pour enregistrer les gestionnaires d'événements dans l'objet.

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

Pour la liste complète des événements, voir la Référence Google Maps JavaScript API. Les événements sont répertoriés dans une section distincte pour chaque objet qui contient des événements.

Événements de l'interface utilisateur

Dans Google Maps JavaScript API, certains objets sont conçus pour répondre aux événements utilisateur (liés à la souris ou au clavier, par exemple). Ainsi, un objet google.maps.Marker peut écouter les événements utilisateur suivants :

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

Pour obtenir la liste complète, voir la classe Marker. Ces événements peuvent ressembler à des événements DOM standard, mais en fait ils appartiennent à Maps JavaScript API. Comme les modèles d'événements DOM varient d'un navigateur à l'autre, Maps JavaScript API offre ces mécanismes pour écouter les événements DOM et y répondre, sans avoir à traiter les nombreuses particularités des différents 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. En cas de modification d'une propriété d'un objet, Google Maps JavaScript API déclenche un événement correspondant à cette modification. Par exemple, si le niveau de zoom d'une carte change, l'API déclenche un événement zoom_changed sur la carte. Pour intercepter ces changements d'état, vous pouvez appeler addListener() afin d'enregistrer les gestionnaires d'événements dans 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. Pour inspecter la propriété qui a changé lors d'un changement d'état MVC, appelez la méthode getProperty appropriée pour cet objet.

Gérer les événements

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

Exemple : Événements de marqueur et de carte

Le code suivant combine des événements utilisateur et des événements de changement d'état. Nous associons un gestionnaire d'événements à un marqueur qui effectue un zoom sur la carte si l'utilisateur clique dessus. Par ailleurs, nous ajoutons à la carte un gestionnaire d'événements qui effectue le suivi des changements apportés à la propriété center et nous effectuons un panoramique de la carte qui la ramène au niveau du marqueur 3 secondes après la réception de l'événement center_changed :

function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

Voir l'exemple (event-simple.html).

Astuce : Si vous tentez de détecter un changement apporté à la fenêtre d'affichage, utilisez l'événement bounds_changed plutôt que les événements zoom_changed et center_changed. Comme Maps JavaScript API déclenche ces derniers de manière indépendante, getBounds() risque de ne pas fournir de résultat exploitable tant que la fenêtre d'affichage n'a pas changé. Si vous souhaitez appeler getBounds() après un tel événement, écoutez plutôt l'événement bounds_changed.

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

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

Voir l'exemple (rectangle-event.html)

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

En général, dans Google Maps JavaScript API, les événements de l'interface utilisateur spécifient un événement en argument. L'écouteur d'événement peut accéder à ce dernier pour relever l'état de l'interface utilisateur lorsque l'événement s'est produit. Par exemple, un événement 'click' de l'interface utilisateur spécifie généralement un événement MouseEvent contenant une propriété latLng qui indique le point géographique où l'utilisateur a cliqué sur la carte. Notez que ce comportement est spécifique aux événements de l'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 marqueur au point géographique où l'utilisateur a cliqué.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

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

Voir l'exemple (event-arguments.html).

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

Lorsque vous utilisez un écouteur d'événement, il s'avère 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'instances « privées », mais prend en charge les fermetures, ce qui permet aux fonctions internes d'accéder à des variables externes. Les fermetures s'avèrent pratiques dans les écouteurs d'événements pour accéder aux variables qui normalement ne sont 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 marqueurs. Cliquez sur chaque marqueur pour afficher une partie du message secret (qui ne se trouve pas dans le marqueur lui-même).

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var 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.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var 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) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var 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.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var 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) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}

Voir l'exemple (event-closure.html).

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

Dans le système d'événements de Google Maps JavaScript API, aucun événement de changement d'état MVC ne spécifie d'argument lorsque l'événement se déclenche. (Les événements utilisateur, en revanche, spécifient des arguments qui peuvent être examinés.) Si vous souhaitez inspecter une propriété lors d'un changement d'état MVC, appelez explicitement la méthode getProperty() appropriée pour cet objet. De cette manière, vous récupérez toujours l'état actuel de l'objet MVC, qui peut être différent de son état au moment où l'événement a été déclenché.

Remarque : Lorsque vous définissez explicitement une propriété dans un gestionnaire d'événements qui répond à un changement d'état de cette propriété, il est possible qu'un comportement imprévu et/ou indésirable se produise. La définition d'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 pou répondre aux événements de zoom en affichant une fenêtre d'info qui indique le niveau de zoom.

function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}

Voir l'exemple (event-properties.html).

Écouter les événements DOM

Le modèle d'événements de Google Maps JavaScript API crée et gère ses propres événements personnalisés. Toutefois, le modèle objet de document (DOM) intégré au navigateur crée et envoie également ses propres événements, selon le modèle d'événements particulier au navigateur utilisé. Si vous souhaitez capturer ces événements et y répondre, vous pouvez utiliser la méthode statique addDomListener() de Maps JavaScript API pour l'écoute et la liaison des événements DOM.

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

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

instance peut être tout élément DOM pris en charge par le navigateur, notamment :

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

Notez que la méthode addDomListener() se contente de fournir l'événement indiqué au navigateur pour que celui-ci le traite conformément au modèle d'événements DOM du navigateur. Toutefois, presque tous les navigateurs modernes prennent en charge au moins DOM Level 2. (Pour plus d'informations sur les événements DOM, voir la référence Mozilla DOM Levels.)

Si vous avez lu la documentation jusqu'ici, vous avez sûrement déjà entendu parler d'un événement DOM : l'événement window.onload, que nous avons traité dans la balise <body>. Nous utilisons cet événement pour déclencher le code JavaScript initial suite au chargement complet d'une page HTML, comme illustré ci-dessous :

<script>
  function initialize() {

    // Map initialization

  }
</script>
<body onload="initialize()">
  <div id="map"></div>
</body>

Ici, cet événement est associé à l'élément <body>, mais il s'agit en fait d'un événement window qui indique que la hiérarchie DOM située sous l'élément window a bien été créée et rendue.

Même si ce n'est pas difficile à comprendre, en intégrant un événement onload à une balise <body>, nous mélangeons des données de contenu et de comportement. En général, il est conseillé de séparer le code de contenu (HTML) du code de comportement (JavaScript) et également de fournir un code de présentation (CSS) distinct. Pour ce faire, vous pouvez remplacer le gestionnaire d'événements onload en ligne par un écouteur DOM dans votre code Maps JavaScript API, comme ceci :

<script>
  function initialize() {

    // Map initialization

  }

  google.maps.event.addDomListener(window, 'load', initialize);
</script>
<body>
  <div id="map"></div>
</body>

Voir l'exemple (event-domListener.html)

Le code ci-dessus est du code Maps JavaScript API, mais la méthode addDomListener() assure la liaison avec l'objet window du navigateur et permet à l'API de communiquer avec les objets qui n'appartiennent pas au domaine normal de l'API.

Supprimer des écouteurs d'événement

Pour supprimer un écouteur d'événement spécifique, assurez-vous qu'il a été attribué à une variable. Vous pouvez alors appeler la méthode removeListener() avec en argument le nom de la variable à laquelle l'écouteur était attribué.

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

google.maps.event.removeListener(listener1);

Pour supprimer tous les écouteurs d'une instance particulière, appelez la méthode clearInstanceListeners() avec en argument 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 concernant un type d'événement spécifique pour une instance particulière, appelez la méthode clearListeners() avec en argument 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 plus d'informations, voir la documentation de référence de l'espace de noms google.maps.event namespace.

Écouter les erreurs d'authentification

Si vous souhaitez utiliser la programmation 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 est appelée en cas d'échec de l'authentification. function gm_authFailure() { /* Code */ };

Envoyer des commentaires concernant…

Google Maps JavaScript API
Google Maps JavaScript API
Besoin d'aide ? Consultez notre page d'assistance.