Calques KML et GeoRSS

1. Présentation
2. Options de calque KML
3. Détail des composants KML

L'objet KmlLayer permet d'effectuer le rendu d'éléments KML et GeoRSS dans une superposition de tuiles Maps API V3.

Présentation

Google Maps API prend en charge les formats de données KML et GeoRSS pour l'affichage des informations géographiques. Ces formats de données sont affichés sur une carte en utilisant l'objet KmlLayer, dont le constructeur utilise l'URL d'un fichier KML ou GeoRSS accessible publiquement.

Remarque : Voir la page Support KML de la documentation sur le langage KML pour en savoir plus sur les éléments pris en charge et les restrictions en termes de taille et de complexité.

Maps API convertit les données géographiques XML fournies en une représentation KML qui est affichée sur la carte au moyen d'une superposition de tuiles V3. Cet élément KML ressemble aux éléments familiers de superposition V3 (et se comporte plus ou moins de la même manière). Les éléments KML <Placemark> et GeoRSS point sont rendus en tant que marqueurs, c'est-à-dire que les éléments <LineString> sont rendus en tant que polylignes et les éléments <Polygon> en tant que polygones. De même, les éléments <GroundOverlay> sont rendus en tant qu'images rectangulaires sur la carte. Plus important encore, toutefois, ces objets ne sont pas des objets Marker, Polyline, Polygon ou GroundOverlay Google Maps API. Ils sont rendus en tant qu'objet unique sur la carte.

Les objets KmlLayer apparaissent sur une carte une fois que leur propriété map a été définie. Vous pouvez les supprimer de la carte en appelant la méthode setMap() et en spécifiant la valeur null. L'objet KmlLayer gère le rendu de ces éléments enfants en récupérant automatiquement les composants appropriés pour les limites spécifiées de la carte. Lorsque les limites sont modifiées, les composants de la fenêtre d'affichage ouverte sont rendus automatiquement.

Étant donné que les composants d'un objet KmlLayer sont rendus à la demande, le calque vous permet de facilement gérer le rendu de milliers de marqueurs, polylignes et polygones. Notez que vous ne pouvez pas accéder directement à ces composants, bien qu'ils fournissent chacun des événements de clic renvoyant des données sur ces objets individuels.

Options de calque KML

Le constructeur KmlLayer() permet au besoin de définir un certain nombre d'objets KmlLayerOptions :

• map spécifie l'objet Map sur lequel effectuer le rendu du calque KmlLayer. Vous pouvez masquer un calque KmlLayer en définissant sa valeur sur null dans la méthode setMap().
• preserveViewport indique que la carte ne doit pas être ajustée aux limites du contenu du calque KmlLayer lors de l'affichage du calque. Par défaut, lors de l'affichage d'un calque KmlLayer, la carte est agrandie et positionnée pour afficher l'intégralité du contenu du calque.
• suppressInfoWindows indique que les composants cliquables du calque KmlLayer ne doivent pas déclencher l'affichage d'objets InfoWindow.

Par ailleurs, une fois le calque KmlLayer rendu, il contient une propriété metadata immuable contenant le nom, la description, le fragment et l'auteur du calque dans un littéral objet KmlLayerMetadata. Vous pouvez inspecter ces informations en utilisant la méthode getMetadata(). Étant donné que le rendu des objets KmlLayer nécessite une communication asynchrone vers un serveur externe, vous devez attendre l'événement metadata_changed, qui indique que la propriété a bien été renseignée.

L'exemple suivant construit un objet KmlLayer à partir du flux GeoRSS fourni :

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

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}

Voir l'exemple GeoRSS

L'exemple suivant construit un objet KmlLayer à partir du flux KML fourni :

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

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}

Voir l'exemple KML

Détail des composants KML

Étant donné que l'élément KML peut inclure un grand nombre de composants, il se peut que vous ne puissiez pas accéder directement aux données des composants à partir de l'objet KmlLayer. À mesure que les composants sont affichés, ils sont rendus de manière à ressembler à des superpositions Maps API cliquables. Lorsque vous cliquez sur des composants individuels, cela affiche par défaut une fenêtre InfoWindow contenant les informations KML <title> et <description> sur le composant en question. Par ailleurs, cliquer sur un composant KML génère un événement KmlMouseEvent définissant les informations suivantes :

• position indique les coordonnées de latitude/longitude sur lesquelles ancrer la fenêtre InfoWindow pour ce composant KML. Cette position est généralement le point géographique cliqué pour les polygones, les polylignes et également les superpositions au sol, mais peut également être la vraie origine des marqueurs.
• pixelOffset indique le décalage à partir de la position ci-dessus pour ancrer la « queue » de la fenêtre InfoWindow. Pour les objets polygonaux, ce décalage est généralement de 0,0, mais pour les marqueurs, il inclut la hauteur du marqueur.
• featureData contient une structure JSON d'objets KmlFeatureData.

Un exemple d'objet KmlFeatureData est illustré ci-dessous :

{
  author: {
    email: "[email protected]",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

Dans l'exemple suivant, le texte de la <Description> du composant KML est affiché dans une « side <div> » lorsque l'on clique sur le composant :

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

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://kml-samples.googlecode.com/svn/trunk/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}

Voir l'exemple KML