Afficher un KML

Présentation

Ce tutoriel explique comment afficher les informations d'un fichier KML dans une carte Google et une barre latérale. Pour en savoir plus sur l'utilisation de fichiers KML dans les cartes, consultez le guide sur les calques KML. Cliquez sur un repère sur la carte ci-dessous pour afficher les données dans la barre latérale.

La section ci-dessous affiche l'intégralité du code dont vous avez besoin pour créer la carte et la barre latérale.

var map;
var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });

  var kmlLayer = new google.maps.KmlLayer(src, {
    suppressInfoWindows: true,
    preserveViewport: false,
    map: map
  });
  kmlLayer.addListener('click', function(event) {
    var content = event.featureData.infoWindowHtml;
    var testimonial = document.getElementById('capture');
    testimonial.innerHTML = content;
  });
}
<div id="map"></div>
<div id="capture"></div>
html, body {
  height: 370px;
  padding: 0;
  margin: 0;
  }
#map {
 height: 360px;
 width: 300px;
 overflow: hidden;
 float: left;
 border: thin solid #333;
 }
#capture {
 height: 360px;
 width: 480px;
 overflow: hidden;
 float: left;
 background-color: #ECECFB;
 border: thin solid #333;
 border-left: none;
 }
<!-- Replace the value of the key parameter with your own API key. -->
<script async
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

Essayez par vous-même

Vous pouvez tester ce code dans JSFiddle en cliquant sur l'icône <> dans l'angle supérieur droit de la fenêtre de code.

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no">
    <meta charset="utf-8">
    <title>KML Click Capture Sample</title>
    <style>
      html, body {
        height: 370px;
        padding: 0;
        margin: 0;
        }
      #map {
       height: 360px;
       width: 300px;
       overflow: hidden;
       float: left;
       border: thin solid #333;
       }
      #capture {
       height: 360px;
       width: 480px;
       overflow: hidden;
       float: left;
       background-color: #ECECFB;
       border: thin solid #333;
       border-left: none;
       }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <div id="capture"></div>
    <script>
      var map;
      var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: new google.maps.LatLng(-19.257753, 146.823688),
          zoom: 2,
          mapTypeId: 'terrain'
        });

        var kmlLayer = new google.maps.KmlLayer(src, {
          suppressInfoWindows: true,
          preserveViewport: false,
          map: map
        });
        kmlLayer.addListener('click', function(event) {
          var content = event.featureData.infoWindowHtml;
          var testimonial = document.getElementById('capture');
          testimonial.innerHTML = content;
        });
      }
    </script>
    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
  </body>
</html>

Premiers pas

Voici les étapes nécessaires à la création de la carte et de la barre latérale pour ce tutoriel :

  1. Configurer le fichier KML
  2. Afficher le KMLLayer
  3. Afficher des données dans la barre latérale

Configurer le fichier KML à importer

Votre fichier KML doit être conforme à la norme KML. Pour en savoir plus sur cette norme, consultez le site Web de l'Open Geospatial Consortium. La documentation KML de Google décrit également le langage. Il s'agit d'une documentation de référence et conceptuelle dédiée aux développeurs.

Si vous êtes simplement là pour apprendre et ne disposez pas d'un fichier KML, vous pouvez :

  • Utilisez le fichier KML suivant pour ce tutoriel :

    https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml

  • Trouvez un fichier KML sur le Web. Vous pouvez utiliser l'opérateur de recherche filetype de Google.

    Remplacez velodromes par un terme de recherche ou omettez-le pour trouver tous les fichiers KML.

Si vous créez votre propre fichier, voici les prérequis pour utiliser le code de cet exemple :

  • Votre fichier doit être publiquement hébergé sur Internet. Il s'agit d'une exigence pour toutes les applications qui chargent un KML dans un KMLLayer, afin que les serveurs de Google puissent trouver et récupérer le contenu, et l'afficher sur la carte.
  • Le fichier ne doit pas se trouver sur une page protégée par mot de passe.
  • Vos éléments géographiques doivent inclure du contenu pour la fenêtre d'informations. Vous pouvez inclure ce contenu dans un élément description ou l'inclure à l'aide d'un élément ExtendedData et du remplacement d'entité (voir ci-dessous pour en savoir plus). Les deux sont accessibles en tant que propriété infoWindowHtml de l'élément géographique.

Éléments ExtendedData

Le fichier KML de ce tutoriel inclut des informations sur l'élément géographique dans un élément ExtendedData. Pour inclure ces informations dans la description de l'élément géographique, utilisez le remplacement d'entité, qui est essentiellement une variable dans le tag BalloonStyle.

Le tableau ci-dessous décrit le code pour cette section.

Code et description 

<Style id="west_campus_style">
  <IconStyle>
    <Icon>
      <href>https://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png
      </href>
    </Icon>
  </IconStyle>
  <BalloonStyle>
    <text>$[video]</text>
  </BalloonStyle>
</Style>

Le fichier KML comporte un seul élément Style qui est appliqué à tous les repères.
Cet élément Style attribue une valeur #[video] à l'élément de texte de BalloonStyle.
Le format $[x] indique à l'analyseur KML de rechercher un élément Data nommé video et de l'utiliser comme texte d'infobulle.		 

<Placemark>
    <name>Google West Campus 1</name>
    <styleUrl>#west_campus_style</styleUrl>
    <ExtendedData>
      <Data name="video">
        <value><![CDATA[<iframe width="640" height="360"
          src="https://www.youtube.com/embed/ZE8ODPL2VPI" frameborder="0"
          allowfullscreen></iframe><br><br>]]></value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-122.0914977709329,37.42390182131783,0</coordinates>
    </Point>
</Placemark>

Chaque Placemark contient un élément ExtendedData, qui contient l'élément Data. Notez que chaque élément Placemark comporte un seul élément Data avec un attribut "name" correspondant à video.
Pour les besoins de ce tutoriel, le fichier utilise la vidéo intégrée YouTube comme valeur de texte d'infobulle pour chaque repère.

Pour en savoir plus sur le remplacement d'entité, consultez le chapitre Ajouter des données personnalisées de la documentation KML.

Afficher le KMLLayer

Initialiser la carte

Ce tableau présente le code de cette section.

Code et description 

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });
}

Pour afficher les données KML sur une carte, vous devez d'abord la créer.
Ce code crée un objet de carte Google, lui indique où centrer et zoomer, et l'associe au div.
Pour en savoir plus sur les bases de la création d'une carte Google, consultez le tutoriel Ajouter une carte Google à votre site Web.

Créer le KMLLayer

Ce tableau décrit le code qui crée un KMLLayer.

Code et description 

var kmlLayer = new google.maps.KmlLayer();

Crée un objet KMLLayer pour afficher votre KML.		 

var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';
var kmlLayer = new google.maps.KmlLayer(src, {
  suppressInfoWindows: true,
  preserveViewport: false,
  map: map
});

Le constructeur KMLLayer définit l'URL de votre fichier KML. Il définit également les propriétés de l'objet KMLLayer qui :
  • indique au calque de ne pas afficher de fenêtre d'informations lorsque l'utilisateur clique dessus ;
  • Demande à la carte de centrer et de zoomer sur le cadre de délimitation des contenus du calque ;
  • définit la carte sur l'objet Map créé précédemment.
Le guide de référence de l'API Maps JavaScript liste toutes les options disponibles pour ce calque.
Chargez votre fichier HTML pour afficher le contenu du fichier KML en tant que calque sur la carte de base. Toutefois, pour le moment, si vous cliquez sur un quelconque composant, rien ne se passe.

Afficher des données dans la barre latérale

Cette section décrit les paramètres qui permettent d'afficher le contenu de la fenêtre d'informations dans la barre latérale lorsque vous cliquez sur un élément géographique sur la carte. Voici les étapes à suivre :

  • Écouter un événement de clic sur n'importe quel élément géographique du KMLLayer
  • Récupérer les données de l'élément géographique sur lequel l'utilisateur a cliqué
  • Écrire ces données dans la barre latérale

Ajouter un écouteur d'événements

Google Maps fournit une fonction permettant d'écouter les événements utilisateur sur la carte (tels que les clics ou les appuis sur des touches du clavier) et d'y répondre. Cette fonction ajoute un écouteur pour ces événements de click.

Le tableau ci-dessous décrit le code pour cette section.

Code et description 

kmlLayer.addListener('click', function(event) {});

L'écouteur d'événements kmlLayer.addListener se concentre sur ce qui suit :
  • Type d'événement à écouter. Dans ce tutoriel, il s'agit de l'événement click.
  • Fonction à appeler lorsque l'événement se produit.
Pour en savoir plus sur les événements, consultez le guide du développeur.

Écrire les données d'un élément géographique KML dans la barre latérale

À cette étape du tutoriel, vous avez capturé des événements de clic sur les éléments géographiques du calque. Vous pouvez maintenant configurer l'application pour qu'elle écrive les données de l'élément géographique et le contenu de la fenêtre d'informations dans la barre latérale.

Le tableau ci-dessous décrit le code pour cette section.

Code et description 

var content = event.featureData.infoWindowHtml;

Écrit le contenu de la fenêtre d'informations dans une variable. 

var testimonial = document.getElementById('capture');
testimonial.innerHTML = content;

Identifie le div approprié et écrit le contenu de l'élément géographique à la place du HTML qu'il contient. 

kmlLayer.addListener('click', function(event) {
  var content = event.featureData.infoWindowHtml;
  var testimonial = document.getElementById('capture');
  testimonial.innerHTML = content;
});

Ces lignes de code deviennent la fonction dans le constructeur addListener.

Désormais, chaque fois que vous cliquez sur un élément géographique KML de la carte, la barre latérale est mise à jour pour afficher le contenu de la fenêtre d'informations.

En savoir plus

En savoir plus sur l'utilisation des fichiers KML