Percorsi di migrazione di KmlLayer

Introduzione

Lo scopo di questa guida è illustrare gli utilizzi più comuni di KmlLayer e fornire i percorsi di migrazione corrispondenti a implementazioni alternative. Queste informazioni sono rivolte agli sviluppatori che devono eseguire la transizione dall'utilizzo di KmlLayer a causa del ritiro pianificato. L'ultima versione che supporta KmlLayer è la 3.65, che verrà ritirata a maggio 2027.

Il percorso di migrazione dipende dal modo in cui utilizzi KmlLayer:

File KML per definire lo stile delle informazioni su confini/bordi/aree di interesse

Per gli sviluppatori che utilizzano KmlLayer per visualizzare o applicare stili ai confini amministrativi, ad esempio per evidenziare un paese, uno stato o una località specifici, Google Maps Platform consiglia di eseguire la migrazione allo stile basato sui dati (DDS) per i confini.

Consiglio per la migrazione: stili basati sui dati per i confini

Stile basato sui dati per i confini fornisce l'accesso diretto ai poligoni dei confini amministrativi di Google, consentendoti di applicare stili personalizzati (riempimento e tratto) a queste regioni senza dover ospitare o gestire file KML esterni.

Disponibile FeatureType

Le aree amministrative sono classificate per funzione e organizzate per livelli. Per lo stile sono supportati i seguenti tipi di funzionalità:

  • COUNTRY: l'entità politica nazionale.
  • ADMINISTRATIVE_AREA_LEVEL_1: un'entità civile di primo ordine al di sotto del livello paese (ad es. gli stati degli Stati Uniti).
  • ADMINISTRATIVE_AREA_LEVEL_2: una divisione amministrativa di secondo livello al di sotto del livello paese (ad es. le contee negli Stati Uniti).
  • LOCALITY: una città o un paese incorporato.
  • POSTAL_CODE: codici postali utilizzati per la posta.
  • SCHOOL_DISTRICT: distretti scolastici unificati, elementari o secondari.

Consulta la copertura dei confini per le regioni in cui sono disponibili questi tipi di funzionalità.

Come evidenziare un'area

Per applicare uno stile a una regione specifica, devi scegliere come target il relativo ID luogo.

Limitare lo spostamento panoramico a un'area

Per impedire agli utenti di spostarsi al di fuori del riquadro di delimitazione dell'area evidenziata, puoi utilizzare l'opzione restriction all'interno di MapOptions.

L'oggetto restriction definisce un latLngBounds che limita l'area visibile della mappa. Per ulteriori dettagli sul funzionamento della limitazione, consulta la documentazione.

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

Implementazione della migrazione del riepilogo

Di seguito è riportato un esempio completo di come utilizzare lo stile basato sui dati per i confini e una limitazione della regione per centrare la mappa su un'area specifica.

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,
      };
    }
  };
}

File KML con dati vettoriali (punti/polilinee/confini/poligoni)

Consiglio per la migrazione: stili basati sui dati per i set di dati

Google consiglia il percorso riportato di seguito per visualizzare i dati geografici disponibili pubblicamente e ottenere un maggiore controllo su stile e prestazioni.

Gli stili basati sui dati per i set di dati ti consentono di caricare i tuoi dati geospaziali (KML, GeoJSON o CSV), applicare stili personalizzati in base agli attributi dei dati e visualizzare le funzionalità sulle mappe vettoriali.

1. Configurazione e caricamento

A differenza di KmlLayer, che recupera un URL in fase di runtime, DDS richiede di ospitare i dati come set di dati nella console Google Cloud.

2. Impostazione dell'area visibile sui dati

KmlLayer esegue automaticamente la panoramica e lo zoom sulla posizione dei dati per impostazione predefinita. Con DDS per i set di dati, questo comportamento non è automatico e deve essere implementato manualmente.

  • Limitazioni hardcoded: se l'area dati è statica, utilizza l'opzione restriction in MapOptions per bloccare la visualizzazione su limiti specifici.
  • Zoom dinamico: per impostare dinamicamente l'area visibile, puoi utilizzare map.fitBounds() con il riquadro di delimitazione del set di dati.

3. Stili dagli attributi delle caratteristiche

I file KML spesso contengono informazioni sullo stile (come i colori) che DDS non applica automaticamente. Devi creare una funzione di stile lato client che legga gli attributi dalle caratteristiche del set di dati per applicare colori e opacità. Per tutti i dettagli, consulta la documentazione per gli sviluppatori su come applicare uno stile ai dati.

Esempio: funzione di stile che utilizza gli attributi

L'esempio seguente mostra come creare una funzione di stile che legge gli attributi background_color e opacity direttamente dal set di dati caricato:

/**
 * 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,
    };
  };
}

Per ulteriori dettagli sull'implementazione di interazioni e stili, consulta la Panoramica degli stili basati sui dati per i set di dati e l'API Datasets per i dati dinamici.

Consiglio per la migrazione: rendering lato client con GeoJSON

Per gli sviluppatori che eseguono la migrazione da KmlLayer al rendering lato client con GeoJSON, Google Maps Platform consiglia un percorso di migrazione che prevede la conversione del formato dei dati e l'utilizzo del livello di dati per eseguire il rendering e applicare lo stile alle funzionalità direttamente nel browser.

Il rendering lato client che utilizza il livello dati offre un modo molto flessibile per visualizzare i dati geografici. A differenza di KmlLayer, che viene visualizzato sui server di Google, il livello dati ti consente di interagire con le funzionalità come oggetti JavaScript standard. Tieni presente, tuttavia, che per i set di dati di grandi dimensioni potresti preferire l'elaborazione e il rendering lato server dei dati, ad esempio con lo stile basato sui dati per i set di dati.

1. Convertire KML in GeoJSON

Il primo passaggio consiste nel convertire i file KML in GeoJSON. Puoi farlo utilizzando diversi strumenti open source popolari:

  • ogr2ogr: Parte della suite GDAL, questa potente utilità a riga di comando può convertire molti formati vettoriali.
ogr2ogr -f GeoJSON output.json input.kml
  • togeojson: Uno strumento piccolo e ben testato progettato specificamente per convertire KML e GPX in GeoJSON.
togeojson input.kml > output.json

2. Impostazione dell'area visibile sui dati

Mentre KmlLayer esegue automaticamente la panoramica e lo zoom sulla posizione dei dati, il livello Dati non lo fa. Per impostare l'area visibile in modo che si adatti ai dati GeoJSON, devi calcolare manualmente il riquadro di delimitazione e chiamare map.fitBounds().

3. Stili dagli attributi delle caratteristiche

Nel livello dati, puoi definire una funzione style che legge gli attributi (proprietà) direttamente da ogni funzionalità GeoJSON per determinarne l'aspetto.

Esempio: funzione di stile e regolazione della finestra

L'esempio seguente mostra come caricare i dati GeoJSON, calcolarne i limiti per impostare il riquadro e applicare uno stile alle funzionalità in base ai relativi attributi:

/**
 * 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
    };
  });
}

Per ulteriori informazioni sull'utilizzo del livello dati, consulta la documentazione relativa all'importazione di GeoJSON in Maps.

Percorso di migrazione: rendering lato client con librerie di terze parti

Per gli sviluppatori che cercano altre alternative all'KmlLayer, esistono diverse librerie gestite dalla community che eseguono il rendering dei dati KML nell'API Google Maps Platform JavaScript.

1. deck.gl

deck.gl è un framework di visualizzazione ad alte prestazioni basato su WebGL. Può essere utilizzato come sostituto quasi immediato per il rendering KML tramite GoogleMapsOverlay e GeoJsonLayer.

  • Requisito di Canvas: per utilizzare deck.gl in modo efficace, devi convertire la mappa in modo che utilizzi il tipo di mappa vettoriale (che viene visualizzata in un elemento canvas) con le relative funzionalità di rendering WebGL.
  • Supporto KML:l'analisi della geometria viene gestita da @loaders.gl/kml, che converte KML in GeoJSON. Tieni presente che alcune funzionalità KML come stili complessi, icone e NetworkLink potrebbero richiedere un'implementazione manuale aggiuntiva.
  • Documentazione:Documentazione di deck.gl | Caricatore KML di loaders.gl.
  • Esempi:
    • L'esempio deckgl-kml-updated nel repository GitHub di Google Maps mostra come utilizzare deck.gl per eseguire il rendering dei dati KML aggiornati in tempo reale.
    • L'esempio deckgl-kml mostra come utilizzare deck.gl per il rendering dei dati KML.

2. geoxml3

geoxml3 è un processore KML progettato specificamente per l'API Maps JavaScript v3 di Google Maps. Analizza KML localmente nel browser e visualizza i dati come oggetti API di Google Maps standard, ad esempio indicatori, polilinee e poligoni.

  • Supporto delle mappe standard:a differenza delle soluzioni basate su WebGL, geoxml3 funziona su mappe API Google Maps JavaScript v3 standard senza richiedere una modalità di rendering specifica.
  • Avvertenze:
    • Supporto KMZ limitato: la libreria non supporta completamente i file KMZ in modo nativo; la decompressione degli archivi KMZ in genere richiede l'integrazione con script di terze parti aggiuntivi come ZipFile.complete.js.
    • Elementi non supportati: funzionalità come geometrie 3D, etichette complesse e alcuni elementi KML più recenti non sono supportati.
  • Documentazione: Repository GitHub di geoxml3.

File KML con elementi interattivi

Consiglio per la migrazione: stili basati sui dati per i set di dati

Per gli sviluppatori che eseguono la migrazione da KmlLayer allo stile basato sui dati (DDS) per i set di dati, questa guida spiega come passare dalle interazioni KML automatiche a interazioni personalizzate e ad alte prestazioni come clic del mouse e passaggio del mouse.

Configurazione iniziale

Prima di implementare le interazioni, assicurati di aver seguito i passaggi di configurazione della guida Migrazione KML: dati vettoriali:

  • ID mappa:configura un ID mappa per il tipo Mappa vettoriale.
  • Carica:carica i tuoi dati KML nella console Google Cloud per ottenere un ID dataset.
  • Accesso al livello:utilizza map.getDatasetFeatureLayer(datasetId) per accedere al livello interattivo.

1. Gestione degli eventi di interazione

In KmlLayer, i clic sulle funzionalità vengono gestiti automaticamente dall'API per visualizzare una finestra informativa. Con DDS per i set di dati, devi registrare manualmente i listener per gli eventi del mouse sul livello del set di dati.

  • click: attivato quando un utente fa clic su una funzionalità.
  • mousemove: attivato quando il cursore si sposta su una funzionalità, utile per gli effetti al passaggio del mouse.

2. Stile dinamico (effetto al passaggio del mouse)

Poiché gli stili DDS vengono applicati globalmente al livello, devi mantenere una variabile di stato per monitorare con quale funzionalità viene interagito e riapplicare lo stile.

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. Visualizzazione dell'HTML dall'attributo description

In KML, il tag <description> spesso contiene HTML per la finestra informativa predefinita. Quando questi dati vengono importati come set di dati, description diventa un attributo della funzionalità. Per eseguirne il rendering, passa la stringa direttamente a 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. Finestra informativa personalizzata con ExtendedData

Se il tuo KML utilizza <ExtendedData> per memorizzare coppie nome/valore personalizzate, queste vengono mappate a datasetAttributes. Puoi scorrere questi attributi per creare una visualizzazione HTML personalizzata.

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);
  }
});

Per tecniche di visualizzazione più avanzate, consulta la documentazione per gli sviluppatori su come applicare stili alle funzionalità dei dati.

Consiglio per la migrazione: rendering lato client con GeoJSON

Per gli sviluppatori che eseguono la migrazione da KmlLayer al rendering lato client con GeoJSON e il Livello dati, questa guida spiega come passare dalle interazioni KML automatiche a interazioni personalizzate basate su eventi e a stili dinamici.

Configurazione iniziale

Prima di implementare le interazioni, devi convertire i dati KML in GeoJSON e caricarli nel livello dati. Per informazioni dettagliate sull'utilizzo di strumenti come ogr2ogr o togeojson e sull'inizializzazione della mappa con map.data.loadGeoJson(), consulta la guida Consigli per la migrazione: rendering lato client con GeoJSON.

1. Interazioni automatiche e manuali

Una differenza fondamentale tra questi livelli è il modo in cui gestiscono l'input dell'utente:

  • KmlLayer: gestisce automaticamente i clic sulle funzionalità e visualizza un InfoWindow contenente i dati e KML.
  • Livello dati: non mostra automaticamente gli oggetti InfoWindow. Devi aggiungere manualmente i listener di eventi per acquisire le interazioni degli utenti e scrivere codice per visualizzare i dati.

2. Gestione degli eventi di interazione

Per rendere interattive le funzionalità GeoJSON, utilizza il metodo addListener() sull'oggetto map.data. Gli eventi comuni includono:

  • click: utilizzato per attivare finestre informative o logica di selezione.
  • mouseover / mouseout: utilizzato per effetti al passaggio del mouse ed evidenziazione.

3. Visualizzazione di descrizioni HTML in una finestra informativa

Quando il formato KML viene convertito in GeoJSON, il tag <description> (che spesso contiene HTML) viene in genere mappato a una proprietà denominata description. Puoi utilizzare feature.getProperty('description') per recuperare questa stringa e visualizzarla all'interno di 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. Finestre informative personalizzate e ExtendedData

Se il file KML originale utilizzava <ExtendedData>, queste coppie nome-valore vengono convertite in proprietà GeoJSON. Poiché il livello dati non dispone di un'interfaccia utente predefinita per questi elementi, devi implementare una finestra informativa personalizzata per scorrere e visualizzarli.

Puoi accedere a questi attributi utilizzando event.feature.getProperty('attribute_name') e creare una stringa HTML personalizzata o un elemento DOM da passare al metodo infoWindow.setContent().

5. Stili dinamici (effetti al passaggio del mouse)

Il livello dati ti consente di aggiornare gli stili delle funzionalità in modo programmatico in risposta agli eventi. Utilizza overrideStyle() per modificare temporaneamente l'aspetto di una funzionalità (ad es. al passaggio del mouse) e revertStyle() per tornare allo stile globale.

// 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();
});

Per informazioni più dettagliate sull'implementazione, consulta la documentazione su Livello dati: gestione degli eventi e Livello dati: stile dinamico.

Percorso di migrazione: rendering lato client con librerie di terze parti

Per gli sviluppatori che eseguono la migrazione da KmlLayer a soluzioni di terze parti, questa guida si concentra sulla gestione dei dati interattivi, come i clic del mouse e gli eventi dinamici, utilizzando deck.gl e geoxml3.

Configurazione iniziale

Prima di implementare le interazioni, assicurati di aver seguito i passaggi di configurazione della guida Percorso di migrazione: rendering lato client con librerie di terze parti. È incluso quanto segue:

  • deck.gl: conversione della mappa per utilizzare il tipo di mappa vettoriale (requisito canvas).
  • geoxml3: pubblicazione degli script della libreria dal tuo host e gestione della condivisione delle risorse tra origini (CORS).

1. Dati interattivi con deck.gl

deck.gl supporta KML come formato di input diretto e gestisce automaticamente le interazioni con le funzionalità, come i clic, in base ai dati forniti nel file KML.

  • Gestione di KMLLoader: utilizzando il modulo @loaders.gl/kml, la geometria e le proprietà vengono analizzate in un formato che deck.gl utilizza per attivare gli eventi di interazione in modo nativo.
  • Clic sulle funzionalità: quando si fa clic su una funzionalità, deck.gl può acquisire l'evento e visualizzare i metadati associati (ad esempio <name> o <description>).
  • Esempio: l'esempio deckgl-kml-updated mostra il rendering KML in tempo reale in cui il passaggio del mouse sopra i marcatori di terremoto visualizza informazioni dettagliate sull'evento.

2. Dati interattivi con geoxml3

geoxml3 analizza il KML localmente nel browser, estrae le informazioni sullo stile e genera oggetti API di Google Maps standard che mantengono la loro interattività.

  • Estrazione dello stile nativo: la libreria acquisisce gli elementi <Style> e <StyleMap> dal KML per applicarli ai marcatori, alle polilinee e ai poligoni generati.
  • Gestori di clic: per impostazione predefinita, geoxml3 fornisce gestori di clic per questi oggetti. Puoi anche definire funzioni di callback personalizzate (createMarker, createOverlay) durante l'istanza del parser per implementare la tua logica di selezione o gli aggiornamenti della barra laterale.
  • Esempio: questo esempio mostra come utilizzare geoxml3 per eseguire il rendering di KML, con personalizzazioni come indicatori circolari con interazione, ad esempio facendo clic sugli indicatori per visualizzare le informazioni sui terremoti.
  • Modello di utilizzo:
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');

File KML con immagini

Per gli sviluppatori che utilizzano KmlLayer per visualizzare immagini, ad esempio mappe con dati derivati da satelliti, modelli meteorologici o progetti storici, questa guida descrive i percorsi di migrazione a GroundOverlays o analizzatori di terze parti.

Consiglio per la migrazione: GroundOverlay dell'API Maps JavaScript

Il percorso consigliato per la migrazione delle immagini è l'utilizzo della classe google.maps.GroundOverlay. In questo modo, puoi posizionare un'immagine sulla mappa in corrispondenza di coordinate geografiche specifiche direttamente nel codice.

1. Implementazione

Anziché fare affidamento su un file KML per definire i limiti, devi specificare l'URL immagine e un oggetto LatLngBounds che rappresenta il rettangolo sulla mappa.

  • Documentazione: Guida agli overlay a terra.
  • Preparazione dell'immagine: se l'immagine è georeferenziata, ma non nella proiezione corretta (EPSG:4326), puoi utilizzare lo strumento open source gdalwarp per deformare l'immagine e utilizzarla con l'API Maps JavaScript.
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

Percorso di migrazione: utilizzo di librerie di terze parti

Se il tuo flusso di lavoro richiede di conservare i dati in formato KML, puoi utilizzare librerie di terze parti come geoxml3 o deck.gl per eseguire il rendering delle sovrapposizioni di immagini.

Disclaimer:queste soluzioni di terze parti non sono supportate da Google. Tuttavia, sono stati testati e dovrebbero funzionare per la maggior parte dei casi d'uso.

1. geoxml3

geoxml3 è una buona opzione per analizzare gli elementi GroundOverlay semplici localmente nel browser e convertirli in oggetti API di Google Maps.

Esempio di utilizzo:

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

Sebbene deck.gl's standard GeoJsonLayer gestisca i dati vettoriali, può anche supportare GroundOverlays tramite un'implementazione manuale utilizzando BitmapLayer.

Questo approccio prevede l'utilizzo di KMLLoader per analizzare il file e quindi definire esplicitamente un BitmapLayer con l'URL e le coordinate dell'immagine estratti dai dati KML.

Caso avanzato: riquadri piramidali utilizzando gdal2tiles

Per i file KML complessi contenenti piramidi di riquadri di immagini, la migrazione è più difficile e richiede l'estrazione dei dati delle immagini.

  • Strumento: gdal2tiles può estrarre dati da una piramide KMZ e produrre codice API Maps JavaScript standard per visualizzare i riquadri. Tieni presente che il risultato finale potrebbe richiedere una modifica manuale per essere incorporato in una mappa esistente.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

La gestione dei file KML con link di rete richiede un passaggio dal recupero automatico lato cloud di KmlLayer a strategie di gestione dei dati più esplicite.

Soluzione supportata: stili basati sui dati per i set di dati

Poiché i set di dati di Google Maps Platform non analizzano in modo nativo gli elementi <NetworkLink>, devi scegliere una strategia di migrazione in base alla struttura dei dati:

  • Strategia A: set di dati distinti (ideale per i livelli controllati dall'utente). Carica ogni file KML che in precedenza era un link di rete come set di dati individuale nella console Google Cloud. Puoi quindi utilizzare JavaScript per caricare e visualizzare dinamicamente questi livelli quando necessario chiamando map.getDatasetFeatureLayer(datasetId) e modificandone la visibilità o lo stile.
  • Strategia B: file KML compresso (ideale per la visualizzazione ad alte prestazioni) Combina tutte le funzionalità dei vari file collegati alla rete in un unico file KML completo prima di caricarlo come set di dati. Puoi quindi utilizzare lo stile dinamico in base agli attributi delle funzionalità per filtrare e visualizzare sottoinsiemi di dati specifici al volo.

Aggiornamento dei dati dinamici:per simulare il comportamento di "aggiornamento automatico" dei link di rete, utilizza l'API Datasets per caricare in modo programmatico una nuova versione del tuo set di dati ogni volta che i dati di origine cambiano.

Soluzioni open source: deck.gl e geoxml3

Né deck.gl né geoxml3 forniscono un supporto efficace per l'analisi e il recupero automatico degli elementi KML <NetworkLink>.

deck.gl

deck.gl utilizza KMLLoader (basato su togeojson), che non supporta esplicitamente NetworkLink.

  • Perché non è una buona soluzione: il parser è progettato per essere un convertitore sincrono e "semplice" che evita di effettuare richieste di rete per garantire affidabilità e semplicità. Se la tua applicazione si basa su file KML che rimandano a più URL, deck.gl non li risolve automaticamente.

geoxml3

Sebbene geoxml3 sia stato sviluppato per analizzare KML per l'API Maps JavaScript, il supporto dei collegamenti di rete è sperimentale e non gestito.

  • Perché non è una buona soluzione: la funzionalità esiste solo in un ramo "network_link" specifico, vecchio e non testato a fondo. L'utilizzo di questo per la migrazione dei dati di produzione è sconsigliato, in quanto potrebbe non riuscire a gestire strutture di link complesse o requisiti di sicurezza moderni come CORS.

Consiglio di riepilogo

Per una migrazione affidabile, gli sviluppatori devono evitare i parser di terze parti per i file con link di rete e ricostruire la logica di recupero dei dati utilizzando l'API Datasets. In questo modo, i tuoi dati vengono gestiti in modo sicuro all'interno dell'infrastruttura di Google Maps Platform anziché fare affidamento su parser lato client non gestiti.

Utilizzare KML per visualizzare gli overlay schermo

Per gli sviluppatori che eseguono la migrazione da KmlLayer ad alternative moderne come lo stile basato sui dati (DDS), è importante notare che le sovrimpressioni dello schermo non sono supportate nei set di dati. Per ottenere lo stesso effetto di visualizzazione di immagini, loghi o legende fisse sopra la mappa, devi creare controlli personalizzati utilizzando l'API Maps JavaScript.

1. Cosa cercare nel file KML

Per creare un controllo personalizzato equivalente, esamina l'elemento <ScreenOverlay> nel file KML per i seguenti attributi chiave:

  • <Icon>&lt;href>: l'URL dell'immagine che vuoi visualizzare.
  • <screenXY>: definisce la posizione dell'overlay sullo schermo.
    • x=0, y=1 (frazioni) corrisponde a In alto a sinistra.
    • x=1, y=1 corrisponde a In alto a destra.
    • x=0, y=0 corrisponde a In basso a sinistra.
    • x=1, y=0 corrisponde a In basso a destra.
  • <size>: definisce la larghezza e l'altezza dell'overlay.
  • <rotation>: indica se l'immagine deve essere ruotata.

2. Implementazione: creazione di un controllo personalizzato

Un controllo personalizzato è essenzialmente un elemento HTML standard (come <div> o <img>) che "inserisci" in una delle posizioni predefinite della mappa.

Mappatura delle posizioni KML su ControlPosition

L'API Maps JavaScript utilizza l'enumerazione ControlPosition per ancorare i controlli. Utilizza la tabella seguente per mappare il tuo <screenXY> KML alla costante API JS appropriata:

Posizione KML (screenXY) API JS ControlPosition
In alto a sinistra (x:0, y:1) TOP_LEFT (legacy) o BLOCK_START_INLINE_START (logico)
In alto a destra (x:1, y:1) TOP_RIGHT o BLOCK_START_INLINE_END
In basso a sinistra (x:0, y:0) BOTTOM_LEFT o BLOCK_END_INLINE_START
In basso a destra (x:1, y:0) BOTTOM_RIGHT o BLOCK_END_INLINE_END

3. Esempio di migrazione: overlay del logo fisso

L'esempio seguente simula un logo ScreenOverlay KML posizionato in alto a destra della mappa.

Stili CSS

Utilizza CSS per definire le dimensioni e l'aspetto della "sovrapposizione".

#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;
}

Implementazione JavaScript

Aggiungi l'elemento all'array 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);
}

Ulteriori informazioni