Livelli KML e GeoRSS

KmlLayer esegue il rendering degli elementi KML e GeoRSS in un overlay di riquadri dell'API Maps JavaScript.

Panoramica

L'API JavaScript di Maps supporta i formati di dati KML e GeoRSS per la visualizzazione di informazioni geografiche. Questi formati di dati vengono visualizzati su una mappa utilizzando un oggetto KmlLayer, il cui costruttore prende l'URL di un file KML o GeoRSS accessibile al pubblico.

Nota:la classe KmlLayer che genera overlay KML nell'API Maps JavaScript utilizza un servizio in hosting su Google per recuperare e analizzare i file KML per il rendering. Di conseguenza, è possibile visualizzare i file KML solo se sono ospitati su un URL accessibile pubblicamente che non richiede l'autenticazione per l'accesso.

Se hai bisogno di accedere a file privati, di un controllo granulare delle cache o di inviare il viewport del browser a un server di dati geospaziali come parametro di query, ti consigliamo di utilizzare i livelli di dati anziché KmlLayer. In questo modo, i browser degli utenti richiederanno direttamente le risorse dal tuo server web.

L'API Maps JavaScript converte i dati XML geografici forniti in una rappresentazione KML che viene visualizzata sulla mappa utilizzando un overlay di riquadri dell'API Maps JavaScript. Questo file KML ha un aspetto simile (e si comporta in modo simile) agli elementi in overlay dell'API Maps JavaScript. Gli elementi KML <Placemark> e GeoRSS point vengono visualizzati come indicatori, ad esempio gli elementi <LineString> vengono visualizzati come polilinee e gli elementi <Polygon> come poligoni. Analogamente, gli elementi <GroundOverlay> vengono visualizzati come immagini rettangolari sulla mappa. È importante sottolineare, tuttavia, che questi oggetti non sono Markers, Polylines, Polygons o GroundOverlays dell'API Maps JavaScript; vengono invece visualizzati come un singolo oggetto sulla mappa.

Gli oggetti KmlLayer vengono visualizzati su una mappa dopo che è stata impostata la proprietà map. Puoi rimuoverli dalla mappa chiamando setMap() passando null. L'oggetto KmlLayer gestisce il rendering di questi elementi secondari recuperando automaticamente le funzionalità appropriate per i limiti specificati della mappa. Man mano che i confini cambiano, gli elementi nell'area visibile corrente vengono visualizzati automaticamente.

Poiché i componenti all'interno di un KmlLayer vengono visualizzati su richiesta, il livello consente di gestire facilmente il rendering di migliaia di indicatori, linee polilinee e poligoni. Tieni presente che non puoi accedere direttamente a questi oggetti costituenti, anche se ognuno di essi fornisce eventi di clic che restituiscono dati su questi singoli oggetti.

Opzioni del livello KML

Il costruttore KmlLayer() passa facoltativamente un numero di KmlLayerOptions:

• map specifica il Map su cui eseguire il rendering del KmlLayer. Puoi nascondere un KmlLayer impostando questo valore su null all'interno del metodo setMap().
• preserveViewport specifica che la mappa non deve essere aggiustata in base ai limiti dei contenuti di KmlLayer quando viene visualizzato il livello. Per impostazione predefinita, quando viene visualizzato un KmlLayer, la mappa viene aumentata e posizionata in modo da mostrare l'intera gamma di contenuti del livello.
• suppressInfoWindows indica che le funzionalità selezionabili all'interno di KmlLayer non devono attivare la visualizzazione di oggetti InfoWindow.

Inoltre, una volta visualizzato, KmlLayer contiene una proprietà metadata immutabile contenente il nome, la descrizione, lo snippet e l'autore del livello all'interno di un valore letterale dell'oggetto KmlLayerMetadata. Puoi esaminare queste informazioni utilizzando il metodo getMetadata(). Poiché il rendering degli oggetti KmlLayer richiede una comunicazione asincrona con un server esterno, ti consigliamo di monitorare l'evento metadata_changed, che indica che la proprietà è stata compilata.

L'esempio seguente crea un KmlLayer dal feed GeoRSS specificato:

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: 49.496675, lng: -102.65625 },
    }
  );

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: 49.496675, lng: -102.65625 },
  });
  const 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);
}

window.initMap = initMap;
index.js

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

<html>
  <head>
    <title>GeoRSS Layers</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

L'esempio seguente crea un KmlLayer dal feed KML fornito:

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 41.876, lng: -87.624 },
    }
  );

  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 41.876, lng: -87.624 },
  });
  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

window.initMap = initMap;
index.js

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

<html>
  <head>
    <title>KML Layers</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Dettagli degli elementi KML

Poiché il file KML può includere un numero elevato di elementi, potresti non riuscire ad accedere direttamente ai dati degli elementi dall'oggetto KmlLayer. Al contrario, quando vengono visualizzate, le funzionalità vengono visualizzate come overlay dell'API Maps JavaScript cliccabili. Se fai clic su singole funzionalità, per impostazione predefinita viene visualizzato un InfoWindow contenente informazioni KML <title> e <description> sulla funzionalità specificata. Inoltre, un clic su un elemento KML genera un KmlMouseEvent, che trasmette le seguenti informazioni:

• position indica le coordinate di latitudine/longitudine a cui ancorare InfoWindow per questa funzionalità KML. In genere, questa posizione è la posizione su cui è stato fatto clic per poligoni, polilinee e overlay sul terreno, ma l'origine effettiva per gli indicatori.
• pixelOffset indica lo spazio dal valore sopra riportato position per ancorare la "coda" di InfoWindow. Per gli oggetti poligonali, questo offset è in genere 0,0, ma per gli indicatori include l'altezza dell'indicatore.
• featureData contiene una struttura JSON di KmlFeatureData.

Di seguito è riportato un esempio di oggetto KmlFeatureData:

{
  author: {
    email: "nobody@google.com",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

L'esempio seguente mostra il testo della funzionalità KML <Description> all'interno di un lato <div> quando si fa clic sulla funzionalità:

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 12,
      center: { lat: 37.06, lng: -95.68 },
    }
  );

  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text: string) {
    const sidebar = document.getElementById("sidebar") as HTMLElement;

    sidebar.innerHTML = text;
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 37.06, lng: -95.68 },
  });
  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    const sidebar = document.getElementById("sidebar");

    sidebar.innerHTML = text;
  }
}

window.initMap = initMap;
index.js

/* Optional: Makes the sample page fill the window. */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#container {
  height: 100%;
  display: flex;
}

#sidebar {
  flex-basis: 15rem;
  flex-grow: 1;
  padding: 1rem;
  max-width: 30rem;
  height: 100%;
  box-sizing: border-box;
  overflow: auto;
}

#map {
  flex-basis: 0;
  flex-grow: 4;
  height: 100%;
}
style.css

<html>
  <head>
    <title>KML Feature Details</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="container">
      <div id="map"></div>
      <div id="sidebar"></div>
    </div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Limitazioni di dimensioni e complessità per il rendering in KML

L'API Maps JavaScript presenta limitazioni per le dimensioni e la complessità dei file KML caricati. Di seguito è riportato un riepilogo dei limiti attuali.

Nota:questi limiti sono soggetti a modifiche in qualsiasi momento.

Dimensione massima del file recuperato (KML non elaborato, GeoRSS non elaborato o KMZ compresso)

3MB

Massima dimensione del file KML non compresso

10MB

Dimensioni massime dei file immagine non compressi nei file KMZ

500KB per file

Numero massimo di link di rete

10

Numero massimo di funzioni a livello di documento

1000

Numero di livelli KML

Esiste un limite al numero di livelli KML che possono essere visualizzati su una singola mappa di Google. Se superi questo limite, nessuno dei tuoi livelli verrà visualizzato sulla mappa e verrà segnalato un errore nella console JavaScript del browser web. Il limite si basa su una combinazione del numero di classi KmlLayer create e della lunghezza totale di tutti gli URL utilizzati per creare questi livelli. Ogni nuovo KmlLayer che crei occuperà una parte del limite per il livello e un'ulteriore parte del limite a seconda della lunghezza dell'URL da cui è stato caricato il file KML. Di conseguenza, il numero di livelli che puoi aggiungere varierà in base all'applicazione. In media, dovresti essere in grado di caricare tra 10 e 20 livelli senza raggiungere il limite. Se continui a raggiungere il limite, utilizza un servizio di accorciamento degli URL per accorciare gli URL KML. In alternativa, crea un singolo file KML costituito da NetworkLinks ai singoli URL KML.

Considerazioni sulle prestazioni e sulla memorizzazione nella cache

I server di Google memorizzeranno temporaneamente nella cache i file KML per ridurre il carico sui tuoi server. In questo modo, migliorerai anche le prestazioni per gli utenti perché verrà visualizzata una rappresentazione in termini di spazio dei segmenti appropriati del tuo file KML, man mano che gli utenti fanno clic sulla mappa, eseguono la panoramica e lo zoom.

Per ottenere il massimo rendimento, ti consigliamo di:

• Utilizza un tag <expires> appropriato in KML.
  
  KmlLayer non utilizzerà le intestazioni HTTP per decidere come memorizzare nella cache i file KML.
• Non generare file dinamicamente al momento della richiesta.
  
  Genera invece i file prima che siano necessari e pubblicali staticamente. Se il server impiega molto tempo a trasmettere il file KML, il simbolo KmlLayer potrebbe non essere visualizzato.
• Non tentare di bypassare le cache, a meno che tu non sappia con certezza che il file è stato aggiornato.
  
  Se ignori sempre le cache (ad esempio aggiungendo un numero casuale o l'ora del sistema dell'utente come parametro di query), i tuoi server potrebbero essere facilmente sovraccaricati se il tuo sito diventa improvvisamente popolare e se stai pubblicando file KML di grandi dimensioni.
  
  Inoltre, può causare la pubblicazione di dati non aggiornati nella cache per gli utenti se l'orologio di un utente non è corretto e il tag <expires> non è stato impostato correttamente.
  
  Pubblica invece file statici aggiornati con un nuovo numero di revisione distinto e utilizza il codice lato server per aggiornare dinamicamente l'URL passato a KmlLayer con la versione corrente.
• Limita le modifiche ai file KML a una volta al minuto.
  
  Se la dimensione totale di tutti i file è superiore a 1 MB (non compressi), il limite diventa una volta ogni 5 minuti.
• Quando utilizzi un server di dati geospaziali, evita di utilizzare i parametri di query per limitare il viewport dei livelli.
  
  Puoi invece limitare l'area visibile della mappa con l'evento bounds_changed. Agli utenti verranno inviate solo le funzionalità che possono essere visualizzate automaticamente.
  
  Se il tuo server di dati geospaziali contiene una grande quantità di dati, valuta la possibilità di utilizzare livelli di dati.
• Quando utilizzi un server di dati geospaziali, utilizza più KmlLayer per ogni gruppo di elementi che vuoi consentire agli utenti di attivare/disattivare, anziché un singolo KmlLayer con parametri di query diversi.
• Utilizza file KMZ compressi per ridurre le dimensioni dei file.
• Se utilizzi Google Cloud Storage o un'altra soluzione di archiviazione sul cloud, evita di utilizzare funzionalità come URL firmati o token temporanei per applicare i controlli di accesso. Questi possono impedire involontariamente la memorizzazione nella cache.
• Riduci la precisione di tutti i punti a una precisione appropriata.
• Unisci e semplifica la geometria di elementi simili, come poligoni e polilinee.
• Rimuovi gli elementi o le risorse immagine non utilizzati.
• Rimuovi eventuali elementi non supportati.

Se devi accedere a dati privati, impedire la memorizzazione nella cache o inviare il viewport del browser a un server di dati geospaziali come parametro di query, ti consigliamo di utilizzare i livelli di dati anziché KmlLayer. In questo modo, i browser degli utenti richiederanno direttamente le risorse al tuo server web.

Elementi KML supportati

L'API Maps JavaScript supporta i seguenti elementi KML. L'analizzatore sintattico KML generalmente ignora in silenzio i tag XML che non capisce.

• Segnaposto
• Icone
• Cartelle
• HTML descrittivo: sostituzione delle entità tramite <BalloonStyle> e <text>
• KMZ (KML compresso, tra cui immagini allegate)
• Polilinee e poligoni
• Stili per polilinee e poligoni, tra cui colore, riempimento e opacità
• Link alla rete per importare i dati in modo dinamico
• Sovrapposizioni del terreno e dello schermo

La tabella seguente fornisce tutti i dettagli degli elementi KML supportati.