Chemins de migration de KmlLayer

Introduction

L'objectif de ce guide est de couvrir les utilisations les plus courantes de KmlLayer et de fournir les chemins de migration correspondants vers d'autres implémentations. Ces informations s'adressent aux développeurs qui doivent arrêter d'utiliser KmlLayer en raison de son abandon prévu. La dernière version compatible avec KmlLayer est la version 3.65, qui sera abandonnée en mai 2027.

Votre chemin de migration dépend de la façon dont vous utilisez KmlLayer :

Fichier KML pour styliser les informations sur les limites/bordures/zones d'intérêt

Pour les développeurs qui utilisent KmlLayer pour afficher ou styliser les limites administratives (par exemple, pour mettre en évidence un pays, un État ou une localité spécifique), Google Maps Platform recommande de migrer vers le style basé sur les données pour les limites.

Recommandation de migration : style basé sur les données pour les limites

Le style basé sur les données pour les limites permet d'accéder directement aux polygones de limites administratives de Google. Vous pouvez ainsi appliquer des styles personnalisés (remplissage et contour) à ces régions sans avoir à héberger ni à gérer des fichiers KML externes.

FeatureType disponible

Les régions administratives sont classées par fonction et organisées par niveaux. Les types d'éléments suivants sont compatibles avec le style :

  • COUNTRY : entité politique nationale.
  • ADMINISTRATIVE_AREA_LEVEL_1 : entité civile de premier ordre en dessous du niveau du pays (par exemple, les États aux États-Unis).
  • ADMINISTRATIVE_AREA_LEVEL_2 : entité civile de deuxième ordre en dessous du niveau du pays (par exemple, les comtés aux États-Unis).
  • LOCALITY : ville ou municipalité incorporée.
  • POSTAL_CODE : codes postaux utilisés pour le courrier.
  • SCHOOL_DISTRICT : districts scolaires unifiés, primaires ou secondaires.

Consultez la couverture des limites pour connaître les régions où ces types de fonctionnalités sont disponibles.

Mettre en surbrillance une zone

Pour styliser une région spécifique, vous devez la cibler par son ID de lieu.

  • Configuration : vous devez utiliser un ID de carte configuré pour le type de carte Vector JavaScript et activer le calque d'éléments disponible dans la console Google Cloud.
  • Implémentation : utilisez l'exemple de code Styliser un polygone de limite.

Limiter le panoramique à une zone

Pour empêcher les utilisateurs de naviguer en dehors du cadre de sélection de la zone que vous avez mise en évidence, vous pouvez utiliser l'option restriction dans MapOptions.

L'objet restriction définit un latLngBounds qui limite la zone visible de la carte. Pour en savoir plus sur le fonctionnement de cette restriction, consultez la documentation.

// Restrict panning to a specific bounding box
restriction: {
  latLngBounds: {
    north: 47.8,
    south: 45.8,
    east: 10.5,
    west: 5.9,
  },
  strictBounds: true,
},

Résumé de l'implémentation de la migration

Voici un exemple complet d'utilisation du style basé sur les données pour les limites et d'une restriction de région afin de centrer la carte sur une zone spécifique.

const myTargetRegion = "ChIJYW1Zb-9kjEcRFXvLDxG1Vlw"; // Place ID for Switzerland

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 46.8, lng: 8.2 },
    zoom: 9,
    mapId: "YOUR_MAP_ID", // Required for DDS
    // Restrict panning to a specific bounding box
    restriction: {
    // Bounding box for Switzerland
      latLngBounds: {
        north: 47.8,
        south: 45.8,
        east: 10.5,
        west: 5.9,
      },
      strictBounds: true,
    },
  });

  // Access the Country layer and style a specific region by Place ID
  const countryLayer = map.getFeatureLayer("COUNTRY");
  countryLayer.style = (options) => {
    if (options.feature.placeId === myTargetRegion) {
      return {
        fillColor: "#FF0000",
        fillOpacity: 0.5,
        strokeColor: "#FF0000",
        strokeWeight: 2,
      };
    } else {
    // Style everything else whited out, to make the area of interest pop out more.
      return {
        fillColor: '#ffffff',
        fillOpacity: 0.8,
      };
    }
  };
}

Fichier KML avec des données vectorielles (points/polylignes/limites/polygones)

Recommandation de migration : style basé sur les données pour les ensembles de données

Google recommande la méthode ci-dessous pour afficher les données géographiques accessibles au public tout en bénéficiant d'un meilleur contrôle sur le style et les performances.

Avec un style basé sur les données pour les ensembles de données, vous pouvez importer vos propres données géospatiales (KML, GeoJSON ou CSV), appliquer un style personnalisé en fonction des attributs de données et afficher les éléments sur des cartes vectorielles.

1. Configurer et importer

Contrairement à KmlLayer, qui récupère une URL au moment de l'exécution, DDS vous oblige à héberger les données en tant qu'ensemble de données dans la console Google Cloud.

2. Définir la fenêtre d'affichage sur les données

KmlLayer effectue automatiquement un panoramique et un zoom sur l'emplacement des données par défaut. Avec DDS pour les ensembles de données, ce comportement n'est pas automatique et doit être implémenté manuellement.

  • Restrictions codées en dur : si la zone de données est statique, utilisez l'option restriction dans MapOptions pour verrouiller la fenêtre d'affichage sur des limites spécifiques.
  • Zoom dynamique : pour définir la fenêtre d'affichage de manière dynamique, vous pouvez utiliser map.fitBounds() avec le cadre englobant de votre ensemble de données.

3. Styliser à partir des attributs d'entités

Les fichiers KML contiennent souvent des informations de style (comme des couleurs) que DDS n'applique pas automatiquement. Vous devez créer une fonction de style côté client qui lit les attributs des éléments de l'ensemble de données pour appliquer des couleurs et de l'opacité. Pour en savoir plus, consultez la documentation pour les développeurs sur la façon de styliser vos données.

Exemple : Fonction de style utilisant des attributs

L'exemple suivant montre comment créer une fonction de style qui lit les attributs background_color et opacity directement à partir de l'ensemble de données importé :

/**
 * Migration example: Styling features from dataset attributes.
 */
function styleDDSLayer(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Set the style function
  datasetLayer.style = (params) => {
    // Access attributes defined in your KML/Dataset
    const featureAttributes = params.feature.datasetAttributes;

    // Read style values from attributes, with fallback defaults
    const fillColor = featureAttributes['background_color'] || '#4285F4';
    const fillOpacity = parseFloat(featureAttributes['opacity']) || 0.5;
    const strokeColor = featureAttributes['border_color'] || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: fillOpacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
    };
  };
}

Pour en savoir plus sur l'implémentation des interactions et du style, consultez Présentation des styles basés sur les données pour les ensembles de données et l'API Datasets pour les données dynamiques.

Recommandation de migration : rendu côté client avec GeoJSON

Pour les développeurs qui migrent de KmlLayer vers le rendu côté client avec GeoJSON, Google Maps Platform recommande un chemin de migration qui consiste à convertir votre format de données et à utiliser la couche de données pour afficher et styliser les entités directement dans le navigateur.

Le rendu côté client à l'aide de la couche de données offre un moyen très flexible d'afficher des données géographiques. Contrairement à KmlLayer, qui est affiché sur les serveurs de Google, la couche de données vous permet d'interagir avec les fonctionnalités en tant qu'objets JavaScript standards. Toutefois, pour les ensembles de données volumineux, vous préférerez peut-être le traitement et le rendu côté serveur de vos données, par exemple avec le style basé sur les données pour les ensembles de données.

1. Convertir un fichier KML au format GeoJSON

La première étape consiste à convertir vos fichiers KML au format GeoJSON. Pour ce faire, vous pouvez utiliser plusieurs outils Open Source populaires :

  • ogr2ogr : cet utilitaire de ligne de commande puissant, qui fait partie de la suite GDAL, peut convertir de nombreux formats vectoriels.
ogr2ogr -f GeoJSON output.json input.kml
  • togeojson : outil petit et bien testé, conçu spécifiquement pour convertir les fichiers KML et GPX au format GeoJSON.
togeojson input.kml > output.json

2. Définir la fenêtre d'affichage sur les données

Alors que KmlLayer effectue automatiquement un panoramique et un zoom sur l'emplacement des données, la couche de données ne le fait pas. Pour définir la fenêtre d'affichage afin qu'elle s'adapte à vos données GeoJSON, vous devez calculer manuellement le cadre englobant et appeler map.fitBounds().

3. Styliser à partir des attributs d'entités

Dans le calque Data, vous pouvez définir une fonction style qui lit les attributs (propriétés) directement à partir de chaque élément GeoJSON pour déterminer son apparence.

Exemple : Fonction de style et ajustement de la fenêtre d'affichage

L'exemple suivant montre comment charger des données GeoJSON, calculer leurs limites pour définir la fenêtre d'affichage et styliser les éléments en fonction de leurs attributs :

/**
 * Migration example: Loading GeoJSON, fitting viewport, and styling from attributes.
 */
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -28, lng: 137 },
  });

  // Load the GeoJSON data
  map.data.loadGeoJson('path/to/your/data.json', null, (features) => {
    // Adjust viewport to show all loaded features
    const bounds = new google.maps.LatLngBounds();
    features.forEach((feature) => {
      feature.getGeometry().forEachLatLng((latlng) => {
        bounds.extend(latlng);
      });
    });
    map.fitBounds(bounds);
  });

  // Set the style function to read from GeoJSON properties
  map.data.setStyle((feature) => {
    // Access attributes defined in your GeoJSON properties
    const fillColor = feature.getProperty('background_color') || '#4285F4';
    const opacity = parseFloat(feature.getProperty('opacity')) || 0.5;
    const strokeColor = feature.getProperty('border_color') || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: opacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
      visible: true
    };
  });
}

Pour en savoir plus sur l'utilisation de la couche de données, consultez la documentation Importer des données GeoJSON dans Maps.

Chemin de migration : rendu côté client avec des bibliothèques tierces

Pour les développeurs qui recherchent d'autres alternatives à KmlLayer, il existe plusieurs bibliothèques gérées par la communauté qui affichent les données KML sur l'API JavaScript Google Maps Platform.

1. deck.gl

deck.gl est un framework de visualisation hautes performances basé sur WebGL. Il peut être utilisé comme remplacement presque direct pour le rendu KML via ses GoogleMapsOverlay et GeoJsonLayer.

  • Exigence concernant le canevas : pour utiliser deck.gl efficacement, vous devez convertir votre carte pour qu'elle utilise le type de carte vectorielle (qui s'affiche dans un élément de canevas) avec ses fonctionnalités de rendu WebGL.
  • Compatibilité avec KML : l'analyse de la géométrie est gérée par @loaders.gl/kml, qui convertit KML en GeoJSON. Notez que certaines fonctionnalités KML, comme les styles complexes, les icônes et les liens réseau, peuvent nécessiter une implémentation manuelle supplémentaire.
  • Documentation : Documentation deck.gl | Chargeur KML loaders.gl.
  • Exemples :
    • L'exemple deckgl-kml-updated du dépôt GitHub Google Maps montre comment utiliser deck.gl pour afficher des données KML mises à jour en temps réel.
    • L'exemple deckgl-kml montre comment utiliser deck.gl pour afficher des données KML.

2. geoxml3

geoxml3 est un processeur KML spécialement conçu pour l'API Google Maps JavaScript v3. Il analyse le KML localement dans le navigateur et affiche les données sous forme d'objets standards de l'API Google Maps, tels que des repères, des polylignes et des polygones.

  • Compatibilité avec les cartes standards : contrairement aux solutions basées sur WebGL, geoxml3 fonctionne sur les cartes standards de l'API Maps JavaScript v3 sans nécessiter de mode de rendu spécifique.
  • Mises en garde :
    • Compatibilité limitée avec les fichiers KMZ : la bibliothèque n'est pas entièrement compatible avec les fichiers KMZ de manière native. La décompression des archives KMZ nécessite généralement une intégration avec des scripts tiers supplémentaires tels que ZipFile.complete.js.
    • Éléments non acceptés : les fonctionnalités telles que les géométries 3D, les libellés complexes et certains éléments KML récents ne sont pas acceptées.
  • Documentation : dépôt GitHub geoxml3.

Fichier KML avec des éléments interactifs

Recommandation de migration : style basé sur les données pour les ensembles de données

Ce guide explique aux développeurs qui migrent de KmlLayer vers le style basé sur les données pour les ensembles de données comment passer des interactions KML automatiques à des interactions personnalisées et performantes, comme les clics de souris et le survol.

Configuration initiale

Avant d'implémenter des interactions, assurez-vous d'avoir suivi les étapes de configuration du guide Migration KML : données vectorielles :

  • ID de carte : configurez un ID de carte pour le type Carte vectorielle.
  • Importer : importez vos données KML dans la console Google Cloud pour obtenir un ID d'ensemble de données.
  • Accès aux calques : utilisez map.getDatasetFeatureLayer(datasetId) pour accéder au calque interactif.

1. Gérer les événements d'interaction

Dans KmlLayer, les clics sur les entités sont gérés automatiquement par l'API pour afficher une fenêtre d'informations. Avec DDS pour les ensembles de données, vous devez enregistrer manuellement les écouteurs pour les événements de souris sur la couche de l'ensemble de données.

  • click : déclenché lorsqu'un utilisateur clique sur une fonctionnalité.
  • mousemove : déclenché lorsque le curseur se déplace sur une fonctionnalité, utile pour les effets de survol.

2. Style dynamique (effet de survol)

Étant donné que les styles DDS sont appliqués globalement au calque, vous devez conserver une variable d'état pour suivre la fonctionnalité avec laquelle l'utilisateur interagit et réappliquer le style.

let currentFeatureId = null;

function initInteraction(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Apply the style function
  datasetLayer.style = (params) => {
    const isHovered = params.feature.datasetAttributes['id'] === currentFeatureId;
    return {
      strokeColor: 'green',
      strokeWeight: isHovered ? 4.0 : 2.0, // Bold border on hover
      fillColor: 'green',
      fillOpacity: isHovered ? 0.5 : 0.3,
    };
  };

  // Add interaction listeners
  datasetLayer.addListener('mousemove', (event) => {
    if (event.features.length > 0) {
      currentFeatureId = event.features[0].datasetAttributes['id'];
      datasetLayer.style = datasetLayer.style; // Re-apply style to reflect changes
    }
  });

  // Clear hover state when the mouse leaves the features
  map.addListener('mousemove', () => {
    if (currentFeatureId !== null) {
      currentFeatureId = null;
      datasetLayer.style = datasetLayer.style;
    }
  });
}

3. Afficher le code HTML de l'attribut description

Dans KML, la balise <description> contient souvent du code HTML pour la fenêtre d'informations par défaut. Lorsque ces données sont importées en tant qu'ensemble de données, description devient un attribut de caractéristique. Pour l'afficher, transmettez la chaîne directement à un google.maps.InfoWindow standard.

const infoWindow = new google.maps.InfoWindow();

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const feature = event.features[0];
    // Access the HTML description attribute
    const htmlContent = feature.datasetAttributes['description'];

    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. InfoWindow personnalisée avec ExtendedData

Si votre fichier KML utilise <ExtendedData> pour stocker des paires nom/valeur personnalisées, celles-ci sont mappées sur datasetAttributes. Vous pouvez parcourir ces attributs pour créer un affichage HTML personnalisé.

function createCustomContent(feature) {
  const attributes = feature.datasetAttributes;
  const container = document.createElement("div");
  container.style.padding = "10px";
  container.innerHTML = "<h3>Feature Details</h3><dl></dl>";

  const dl = container.querySelector("dl");

  // Iterate through all data attributes imported from KML ExtendedData
  for (const key in attributes) {
    const dt = document.createElement("dt");
    dt.style.fontWeight = "bold";
    dt.textContent = key;

    const dd = document.createElement("dd");
    dd.textContent = attributes[key];

    dl.appendChild(dt);
    dl.appendChild(dd);
  }
  return container;
}

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const content = createCustomContent(event.features[0]);
    infoWindow.setContent(content);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

Pour en savoir plus sur les techniques de visualisation avancées, consultez la documentation pour les développeurs sur la façon de styliser les caractéristiques des données.

Recommandation de migration : rendu côté client avec GeoJSON

Ce guide explique aux développeurs qui migrent de KmlLayer vers le rendu côté client avec GeoJSON et la couche de données comment passer des interactions KML automatiques aux interactions personnalisées basées sur des événements et au style dynamique.

Configuration initiale

Avant d'implémenter des interactions, vous devez convertir vos données KML au format GeoJSON et les charger dans la couche de données. Consultez le guide Recommandation de migration : rendu côté client avec GeoJSON pour en savoir plus sur l'utilisation d'outils tels que ogr2ogr ou togeojson, et sur l'initialisation de la carte avec map.data.loadGeoJson().

1. Interactions automatiques et manuelles

La principale différence entre ces couches réside dans la façon dont elles gèrent les entrées utilisateur :

  • KmlLayer : gère automatiquement les clics sur les entités et affiche un InfoWindow contenant les données KML et .
  • Couche de données : n'affiche pas automatiquement les objets InfoWindow. Vous devez ajouter manuellement des écouteurs d'événements pour capturer les interactions utilisateur et écrire du code pour afficher les données.

2. Gérer les événements d'interaction

Pour rendre les éléments GeoJSON interactifs, utilisez la méthode addListener() sur l'objet map.data. Voici quelques exemples d'événements courants :

  • click : utilisé pour déclencher des info-bulles ou une logique de sélection.
  • mouseover / mouseout : utilisé pour les effets de survol et la mise en surbrillance.

3. Afficher des descriptions HTML dans une fenêtre d'informations

Lorsque le format KML est converti en GeoJSON, la balise <description> (qui contient souvent du code HTML) est généralement mappée à une propriété nommée description. Vous pouvez utiliser feature.getProperty('description') pour récupérer cette chaîne et l'afficher dans un google.maps.InfoWindow standard.

const infoWindow = new google.maps.InfoWindow();

// Handle clicks to show the HTML description
map.data.addListener('click', (event) => {
  // Access the 'description' property from the GeoJSON feature
  const htmlContent = event.feature.getProperty('description');

  if (htmlContent) {
    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. Fenêtres d'informations personnalisées et ExtendedData

Si votre fichier KML d'origine utilisait <ExtendedData>, ces paires nom/valeur sont converties en propriétés GeoJSON. Étant donné que la couche de données ne dispose pas d'UI par défaut pour ces éléments, vous devez implémenter une InfoWindow personnalisée pour les parcourir et les afficher.

Vous pouvez accéder à ces attributs à l'aide de event.feature.getProperty('attribute_name') et créer une chaîne HTML personnalisée ou un élément DOM à transmettre à la méthode infoWindow.setContent().

5. Style dynamique (effets de survol)

La couche de données vous permet de mettre à jour les styles de caractéristiques de manière programmatique en réponse à des événements. Utilisez overrideStyle() pour modifier temporairement l'apparence d'une fonctionnalité (par exemple, au passage de la souris) et revertStyle() pour revenir au style global.

// Set a base style for all features
map.data.setStyle({
  fillColor: 'blue',
  strokeWeight: 1
});

// Highlight feature on mouseover
map.data.addListener('mouseover', (event) => {
  map.data.revertStyle(); // Clear previous highlights
  map.data.overrideStyle(event.feature, {strokeWeight: 8});
});

// Revert style on mouseout
map.data.addListener('mouseout', (event) => {
  map.data.revertStyle();
});

Pour en savoir plus sur l'implémentation, consultez la documentation sur la couche de données : gestion des événements et la couche de données : style dynamique.

Chemin de migration : rendu côté client avec des bibliothèques tierces

Pour les développeurs qui migrent de KmlLayer vers des solutions tierces, ce guide se concentre sur la gestion des données interactives telles que les clics de souris et les événements dynamiques à l'aide de deck.gl et geoxml3.

Configuration initiale

Avant d'implémenter des interactions, assurez-vous d'avoir suivi les étapes de configuration du guide Parcours de migration : rendu côté client avec des bibliothèques tierces. Par exemple :

  • deck.gl : conversion de votre carte pour utiliser le type de carte vectorielle (exigence de canevas).
  • geoxml3 : diffusion des scripts de la bibliothèque depuis votre propre hôte et gestion du partage des ressources entre origines multiples (CORS).

1. Données interactives avec deck.gl

deck.gl accepte le format KML comme format d'entrée direct et gère automatiquement les interactions avec les entités, comme les clics, en fonction des données fournies dans le fichier KML.

  • Gestion de KMLLoader : à l'aide du module @loaders.gl/kml, la géométrie et les propriétés sont analysées dans un format que deck.gl utilise pour déclencher des événements d'interaction de manière native.
  • Clics sur les fonctionnalités : lorsqu'une fonctionnalité est sélectionnée, deck.gl peut capturer l'événement et afficher les métadonnées associées (comme <name> ou <description>).
  • Exemple : L'exemple deckgl-kml-updated montre le rendu KML en temps réel, où le pointeur de la souris sur les repères de tremblement de terre affiche des informations détaillées sur l'événement.

2. Données interactives avec geoxml3

geoxml3 analyse le fichier KML localement dans le navigateur, extrait les informations de style et génère des objets standards de l'API Google Maps qui conservent leur interactivité.

  • Extraction de style natif : la bibliothèque récupère les éléments <Style> et <StyleMap> du KML pour les appliquer aux repères, polylignes et polygones générés.
  • Gestionnaires de clics : par défaut, geoxml3 fournit des gestionnaires de clics pour ces objets. Vous pouvez également définir des fonctions de rappel personnalisées (createMarker, createOverlay) lors de l'instanciation du parseur pour implémenter votre propre logique de sélection ou vos propres mises à jour de la barre latérale.
  • Exemple : cet exemple montre comment utiliser geoxml3 pour afficher du code KML, avec des personnalisations telles que des repères circulaires avec interaction (par exemple, en cliquant sur les repères pour afficher des informations sur les séismes).
  • Schéma d'utilisation :
var myParser = new geoXML3.parser({
  map: map,
  processStyles: true, // Automatically handle KML styles
  afterParse: function(doc) {
    // Code to run after the KML is fully parsed
  }
});
myParser.parse('interactive_data.kml');

Fichier KML avec des images

Ce guide décrit les chemins de migration vers GroundOverlays ou des analyseurs tiers pour les développeurs qui utilisent KmlLayer pour afficher des images, telles que des cartes avec des données issues de satellites, des modèles météorologiques ou des plans historiques.

Recommandation de migration : Maps JavaScript API GroundOverlay

Le chemin recommandé pour migrer des images consiste à utiliser la classe google.maps.GroundOverlay. Cela vous permet de placer une image sur la carte à des coordonnées géographiques spécifiques directement dans votre code.

1. Implémentation

Au lieu de vous appuyer sur un fichier KML pour définir les limites, vous spécifiez l'URL de l'image et un objet LatLngBounds représentant le rectangle sur la carte.

  • Documentation : Guide sur les superpositions au sol.
  • Préparation des images : si votre image est géoréférencée, mais pas dans la bonne projection (EPSG:4326), vous pouvez utiliser l'outil Open Source gdalwarp pour déformer l'image et l'utiliser avec l'API Maps JavaScript.
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

Chemin de migration : utiliser des bibliothèques tierces

Si votre workflow vous oblige à conserver vos données au format KML, vous pouvez utiliser des bibliothèques tierces telles que geoxml3 ou deck.gl pour afficher les calques d'imagerie.

Clause de non-responsabilité : Google ne fournit pas d'assistance pour ces solutions tierces. Toutefois, elles ont été testées et devraient fonctionner pour la plupart des cas d'utilisation.

1. geoxml3

geoxml3 est une bonne option pour analyser des éléments GroundOverlay simples en local dans le navigateur et les convertir en objets de l'API Google Maps.

Exemple d'utilisation :

const geoXmlParser = new geoXML3.parser({
    map: map,
    afterParse: function(doc) {
        console.log("Parsing complete. Number of documents: " + doc.length);
        const bounds = doc[0].gbounds;
        if (bounds && !bounds.isEmpty()) {
           map.fitBounds(bounds);
        }
    },
    createOverlay: function(groundOverlayData) {
        // Extract bounds and URL from parsed KML data
        const imageUrl = groundOverlayData.icon.href;
        const imageBounds = {
            north: parseFloat(groundOverlayData.latLonBox.north),
            south: parseFloat(groundOverlayData.latLonBox.south),
            east: parseFloat(groundOverlayData.latLonBox.east),
            west: parseFloat(groundOverlayData.latLonBox.west)
        };

        // Create the Google Maps GroundOverlay
        const nativeOverlay = new google.maps.GroundOverlay(imageUrl, imageBounds);
        nativeOverlay.setMap(map);
    }
});
geoXmlParser.parse('your_file.kml');

2. deck.gl

Bien que le GeoJsonLayer standard de deck.gl gère les données vectorielles, il peut également prendre en charge GroundOverlays via une implémentation manuelle à l'aide de BitmapLayer.

Cette approche consiste à utiliser KMLLoader pour analyser le fichier, puis à définir explicitement un BitmapLayer avec l'URL et les coordonnées de l'image extraites des données KML.

  • Exigence : L'utilisation de deck.gl nécessite un type de carte vectorielle.
  • Documentation : Calque bitmap deck.gl

Cas avancé : pyramides de tuiles avec gdal2tiles

La migration des fichiers KML complexes contenant des pyramides de tuiles d'imagerie est plus difficile et nécessite l'extraction des données d'imagerie.

  • Outil : gdal2tiles peut extraire des données d'une pyramide KMZ et générer du code standard de l'API Maps JavaScript pour afficher les tuiles. Notez que le résultat final peut nécessiter une modification manuelle pour être intégré à une carte existante.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

La gestion des fichiers KML avec des liens réseau nécessite de passer de la récupération automatique côté cloud de KmlLayer à des stratégies de gestion des données plus explicites.

Solution compatible : style basé sur les données pour les ensembles de données

Étant donné que les ensembles de données Google Maps Platform n'analysent pas nativement les éléments <NetworkLink>, vous devez choisir une stratégie de migration en fonction de la structure de vos données :

  • Stratégie A : Ensembles de données distincts (idéal pour les calques contrôlés par l'utilisateur) : importez chaque fichier KML qui était auparavant un lien réseau en tant qu'ensemble de données individuel dans la console Google Cloud. Vous pouvez ensuite utiliser JavaScript pour charger et afficher dynamiquement ces calques si nécessaire en appelant map.getDatasetFeatureLayer(datasetId) et en ajustant leur visibilité ou leur style.
  • Stratégie B : Fichier KML aplati (idéal pour un affichage performant) Combinez toutes les entités de vos différents fichiers liés au réseau dans un seul fichier KML complet avant de l'importer en tant qu'ensemble de données. Vous pouvez ensuite utiliser le style dynamique basé sur les attributs des entités pour filtrer et afficher des sous-ensembles de données spécifiques à la volée.

Mise à jour des données dynamiques : pour imiter le comportement d'actualisation automatique des liens réseau, utilisez l'API Datasets pour importer de manière programmatique une nouvelle version de votre ensemble de données chaque fois que les données sources changent.

Solutions Open Source : deck.gl et geoxml3

Ni deck.gl ni geoxml3 ne sont compatibles avec l'analyse et la récupération automatique des éléments KML <NetworkLink>.

deck.gl

deck.gl utilise KMLLoader (basé sur togeojson), qui ne prend pas en charge les NetworkLinks.

  • Pourquoi cette solution n'est-elle pas idéale ? Le parseur est conçu pour être un convertisseur synchrone et "sans tracas" qui évite de faire ses propres requêtes réseau pour garantir la fiabilité et la simplicité. Si votre application s'appuie sur des fichiers KML qui pointent vers plusieurs autres URL, deck.gl ne les résoudra pas automatiquement.

geoxml3

Bien que geoxml3 ait été développé pour analyser le KML pour l'API Maps JavaScript, sa prise en charge des liens réseau est expérimentale et non maintenue.

  • Pourquoi cette solution n'est pas idéale : la fonctionnalité n'existe que dans une branche "network_link" spécifique, qui est ancienne et peu testée. Nous vous déconseillons d'utiliser cette méthode pour la migration des données de production, car elle peut ne pas être en mesure de gérer les structures de liens complexes ou les exigences de sécurité modernes telles que CORS.

Recommandation récapitulative

Pour une migration fiable, les développeurs doivent éviter les analyseurs tiers pour les fichiers avec des liens réseau et, à la place, reconstruire la logique de récupération des données à l'aide de l'API Datasets. Vos données sont ainsi gérées de manière sécurisée dans l'infrastructure Google Maps Platform, au lieu de s'appuyer sur des analyseurs côté client non gérés.

Utiliser KML pour afficher les superpositions d'écran

Pour les développeurs qui migrent de KmlLayer vers des alternatives modernes comme le style basé sur les données (DDS), il est important de noter que les calques d'écran ne sont pas compatibles avec les ensembles de données. Pour obtenir le même effet que l'affichage d'images, de logos ou de légendes fixes au-dessus de la carte, vous devez créer des commandes personnalisées à l'aide de l'API Maps JavaScript.

1. Éléments à rechercher dans votre fichier KML

Pour créer un contrôle personnalisé équivalent, examinez l'élément <ScreenOverlay> de votre fichier KML pour les attributs clés suivants :

  • <Icon>&lt;href> : URL de l'image que vous souhaitez afficher.
  • <screenXY> : définit l'emplacement de la superposition sur l'écran.
    • x=0, y=1 (fractions) correspond à en haut à gauche.
    • x=1, y=1 correspond à en haut à droite.
    • x=0, y=0 correspond à En bas à gauche.
    • x=1, y=0 correspond à En bas à droite.
  • <size> : définit la largeur et la hauteur de l'overlay.
  • <rotation> : indique si l'image doit être pivotée.

2. Implémentation : créer un contrôle personnalisé

Une commande personnalisée est essentiellement un élément HTML standard (comme <div> ou <img>) que vous "insérez" dans l'une des positions prédéfinies de la carte.

Mappage des positions KML à ControlPosition

L'API Maps JavaScript utilise l'énumération ControlPosition pour ancrer les commandes. Utilisez le tableau ci-dessous pour faire correspondre votre <screenXY> KML à la constante appropriée de l'API JavaScript :

Position KML (screenXY) API JS ControlPosition
En haut à gauche (x:0, y:1) TOP_LEFT (ancienne) ou BLOCK_START_INLINE_START (logique)
En haut à droite (x:1, y:1) TOP_RIGHT ou BLOCK_START_INLINE_END
En bas à gauche (x:0, y:0) BOTTOM_LEFT ou BLOCK_END_INLINE_START
En bas à droite (x:1, y:0) BOTTOM_RIGHT ou BLOCK_END_INLINE_END

3. Exemple de migration : superposition de logo fixe

L'exemple suivant imite un logo KML ScreenOverlay positionné en haut à droite de la carte.

Style CSS

Utilisez CSS pour définir la taille et l'apparence de votre "calque".

#logo-control {
  padding: 10px;
  background-color: rgba(255, 255, 255, 0.8);
  margin: 10px;
  border-radius: 2px;
  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
}

#logo-control img {
  width: 150px; /* Equivalent to KML <size> */
  display: block;
}

Implémentation JavaScript

Ajoutez l'élément au tableau map.controls.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 41.85, lng: -87.65 },
  });

  // 1. Create the container for the overlay
  const logoControlDiv = document.createElement("div");
  logoControlDiv.id = "logo-control";

  // 2. Create the image (KML <Icon>)
  const logoImage = document.createElement("img");
  logoImage.src = "https://example.com/logo.png";
  logoImage.alt = "Company Logo";

  logoControlDiv.appendChild(logoImage);

  // 3. Position the control (KML <screenXY>)
  // In this case, we use TOP_RIGHT
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(logoControlDiv);
}

Plus d'infos