Superpositions personnalisées

1. Introduction
2. Ajouter une superposition personnalisée
   1. Sous-classer la superposition
   2. Initialiser la superposition
   3. Créer la superposition
3. Supprimer une superposition personnalisée
4. Afficher et masquer une superposition personnalisée

Introduction

Les superpositions sont des objets qui, sur une carte, sont liés aux coordonnées de latitude/longitude. Elles se déplacent donc lorsque vous faites glisser une carte ou effectuez un zoom. Pour plus d'informations sur des types de superposition prédéfinis, reportez-vous à la section Dessiner sur la carte.

Google Maps JavaScript API fournit une classe OverlayView afin de créer vos superpositions personnalisées. OverlayView est une classe de base qui offre plusieurs méthodes que vous devez implémenter lors de la création de vos superpositions. Cette classe fournit également quelques méthodes qui permettent de traduire des coordonnées à l'écran en points géographiques sur la carte.

Ajouter une superposition personnalisée

Suivez la procédure récapitulative suivante pour créer une superposition personnalisée :

• Définissez le prototype de votre objet de superposition personnalisée dans une nouvelle instance de google.maps.OverlayView(). Cela sous-classe ainsi la classe de superposition.
• Créez un constructeur pour votre superposition personnalisée et définissez tous les paramètres d'initialisation.
• Implémentez une méthode onAdd() dans votre prototype et associez la superposition à la carte. OverlayView.onAdd() est appelé lorsque la carte est prête afin de lui associer la superposition.
• Implémentez une méthode draw() dans votre prototype et gérez l'affichage visuel de votre objet. OverlayView.draw() est appelé lorsque l'objet est affiché pour la première fois.
• Vous devez également implémenter une méthode onRemove() pour nettoyer tous les éléments que vous avez ajoutés dans la superposition.

Les sections ci-dessous décrivent plus en détail les différentes étapes. Vous pouvez également consulter l'exemple complet et fonctionnel : Voir l'exemple (overlay-simple.html)

Sous-classer la superposition

L'exemple ci-dessous utilise OverlayView pour créer une superposition d'image simple.

// This example creates a custom overlay called USGSOverlay, containing
// a U.S. Geological Survey (USGS) image of the relevant area on the map.

// Set the custom overlay object's prototype to a new instance
// of OverlayView. In effect, this will subclass the overlay class therefore
// it's simpler to load the API synchronously, using
// google.maps.event.addDomListener().
// Note that we set the prototype to an instance, rather than the
// parent class itself, because we do not wish to modify the parent class.

var overlay;
USGSOverlay.prototype = new google.maps.OverlayView();

// Initialize the map and the custom overlay.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 62.323907, lng: -150.109291},
    mapTypeId: 'satellite'
  });

  var bounds = new google.maps.LatLngBounds(
      new google.maps.LatLng(62.281819, -150.287132),
      new google.maps.LatLng(62.400471, -150.005608));

  // The photograph is courtesy of the U.S. Geological Survey.
  var srcImage = 'https://developers.google.com/maps/documentation/' +
      'javascript/examples/full/images/talkeetna.png';

  // The custom USGSOverlay object contains the USGS image,
  // the bounds of the image, and a reference to the map.
  overlay = new USGSOverlay(bounds, srcImage, map);
}

À présent, nous créons un constructeur pour la classe USGSOverlay et nous initialisons les paramètres transmis en tant que propriétés du nouvel objet.

/** @constructor */
function USGSOverlay(bounds, image, map) {

  // Initialize all properties.
  this.bounds_ = bounds;
  this.image_ = image;
  this.map_ = map;

  // Define a property to hold the image's div. We'll
  // actually create this div upon receipt of the onAdd()
  // method so we'll leave it null for now.
  this.div_ = null;

  // Explicitly call setMap on this overlay.
  this.setMap(map);
}

Nous ne pouvons pas encore associer cette superposition à la carte dans le constructeur de la superposition. Il faut d'abord nous assurer que tous les volets de la carte sont disponibles, car ils indiquent l'ordre dans lequel les objets sont affichés sur la carte. L'API fournit une méthode d'aide indiquant que c'est bien le cas. Cette méthode est traitée dans la section suivante.

Initialiser la superposition

Lorsque la superposition est instanciée pour la première fois et prête à être affichée, il est nécessaire de l'associer à la carte via le DOM du navigateur. L'API indique que la superposition a été ajoutée à la carte en appelant la méthode onAdd() de la superposition. Pour utiliser cette méthode, nous créons un élément <div> pour contenir notre image, nous ajoutons un élément <img>, nous l'associons à l'élément <div>, puis nous associons la superposition à l'un des volets de la carte. Un volet est un nœud dans l'arborescence DOM.

Les volets, de type MapPanes, spécifient l'ordre d'empilement des différents calques de la carte. Les volets suivants sont disponibles et sont énumérés dans l'ordre d'empilement, de bas en haut :

• mapPane est le volet inférieur et se trouve au-dessus des tuiles. Il ne peut pas recevoir d'événements DOM. (volet 0).
• overlayLayer contient les polylignes, les polygones, les superpositions au sol et les superpositions de calques de tuiles. Il ne peut pas recevoir d'événements DOM. (volet 1).
• overlayShadow contient les ombres de marqueur. Il ne peut pas recevoir d'événements DOM. (volet 2).
• overlayImage contient les images de premier plan de marqueur. (volet 3).
• floatShadow contient l'ombre de la fenêtre d'info. Il se trouve au-dessus de overlayImage afin que des marqueurs puissent se trouver dans l'ombre de la fenêtre d'info. (volet 4).
• overlayMouseTarget contient les éléments qui reçoivent les événements de souris DOM, comme les cibles transparentes des marqueurs. Il se trouve au-dessus de floatShadow afin que les marqueurs dans l'ombre de la fenêtre d'info puissent être cliquables. (volet 5).
• floatPane contient la fenêtre d'info. Il se trouve au-dessus de toutes les superpositions de la carte. (volet 6).

Nous utilisons le volet overlayLayer car notre image est une « superposition au sol ». Lorsque nous disposons de ce volet, nous lui associons notre objet en tant qu'enfant.

/**
 * onAdd is called when the map's panes are ready and the overlay has been
 * added to the map.
 */
USGSOverlay.prototype.onAdd = function() {

  var div = document.createElement('div');
  div.style.borderStyle = 'none';
  div.style.borderWidth = '0px';
  div.style.position = 'absolute';

  // Create the img element and attach it to the div.
  var img = document.createElement('img');
  img.src = this.image_;
  img.style.width = '100%';
  img.style.height = '100%';
  img.style.position = 'absolute';
  div.appendChild(img);

  this.div_ = div;

  // Add the element to the "overlayLayer" pane.
  var panes = this.getPanes();
  panes.overlayLayer.appendChild(div);
};

Créer la superposition

Notez que nous n'avons appelé aucun affichage visuel spécial dans le code ci-dessus. L'API appelle une méthode draw() séparée pour la superposition chaque fois qu'elle doit dessiner la superposition sur la carte, y compris lorsqu'elle est ajoutée pour la première fois.

Nous implémentons donc cette méthode draw(), nous récupérons l'élément MapCanvasProjection de la superposition à l'aide de getProjection() et nous calculons les coordonnées exactes où le point supérieur droit et le point inférieur gauche de l'objet doivent être ancrés. Ensuite, il est possible de redimensionner l'élément <div>. Cela entraîne le redimensionnement de l'image afin qu'elle corresponde aux limites que nous avons spécifiées dans le constructeur de la superposition.

USGSOverlay.prototype.draw = function() {

  // We use the south-west and north-east
  // coordinates of the overlay to peg it to the correct position and size.
  // To do this, we need to retrieve the projection from the overlay.
  var overlayProjection = this.getProjection();

  // Retrieve the south-west and north-east coordinates of this overlay
  // in LatLngs and convert them to pixel coordinates.
  // We'll use these coordinates to resize the div.
  var sw = overlayProjection.fromLatLngToDivPixel(this.bounds_.getSouthWest());
  var ne = overlayProjection.fromLatLngToDivPixel(this.bounds_.getNorthEast());

  // Resize the image's div to fit the indicated dimensions.
  var div = this.div_;
  div.style.left = sw.x + 'px';
  div.style.top = ne.y + 'px';
  div.style.width = (ne.x - sw.x) + 'px';
  div.style.height = (sw.y - ne.y) + 'px';
};

Supprimer une superposition personnalisée

Nous pouvons également ajouter une méthode onRemove() afin de supprimer soigneusement la superposition de la carte.

// The onRemove() method will be called automatically from the API if
// we ever set the overlay's map property to 'null'.
USGSOverlay.prototype.onRemove = function() {
  this.div_.parentNode.removeChild(this.div_);
  this.div_ = null;
};

Afficher et masquer une superposition personnalisée

Si vous voulez afficher ou masquer une superposition plutôt que de la créer et de la supprimer, vous pouvez implémenter vos propres méthodes show() et hide() afin d'ajuster la visibilité de la superposition. Vous pouvez également dissocier la superposition du DOM de la carte, bien que cette opération soit légèrement plus longue. Notez que si vous associez à nouveau la superposition au DOM de la carte, la méthode onAdd() de la superposition sera à nouveau appelée.

Dans l'exemple suivant, des méthodes hide() et show() sont ajoutées au prototype de la superposition qui contrôle la visibilité du conteneur <div>. Nous avons également ajouté la méthode toggleDOM(), qui associe ou dissocie la superposition de la carte.

// Set the visibility to 'hidden' or 'visible'.
USGSOverlay.prototype.hide = function() {
  if (this.div_) {
    // The visibility property must be a string enclosed in quotes.
    this.div_.style.visibility = 'hidden';
  }
};

USGSOverlay.prototype.show = function() {
  if (this.div_) {
    this.div_.style.visibility = 'visible';
  }
};

USGSOverlay.prototype.toggle = function() {
  if (this.div_) {
    if (this.div_.style.visibility === 'hidden') {
      this.show();
    } else {
      this.hide();
    }
  }
};

// Detach the map from the DOM via toggleDOM().
// Note that if we later reattach the map, it will be visible again,
// because the containing <div> is recreated in the overlay's onAdd() method.
USGSOverlay.prototype.toggleDOM = function() {
  if (this.getMap()) {
    // Note: setMap(null) calls OverlayView.onRemove()
    this.setMap(null);
  } else {
    this.setMap(this.map_);
  }
};

Faites attention à l'interface utilisateur :

<!-- Add an input button to initiate the toggle method on the overlay. -->
    <div id="floating-panel">
      <input type="button" value="Toggle visibility" onclick="overlay.toggle();"></input>
      <input type="button" value="Toggle DOM attachment" onclick="overlay.toggleDOM();"></input>
    </div>

Voir l'exemple (overlay-hideshow.html)