Livelli KML e GeoRSS

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

Panoramica

L'API Maps JavaScript 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 accetta l'URL di un file KML o GeoRSS accessibile pubblicamente.

Nota:la classe KmlLayer che genera gli overlay KML nell'API Maps JavaScript utilizza un servizio ospitato da Google per recuperare e analizzare i file KML per il rendering. Di conseguenza, è possibile visualizzare i file KML solo se sono ospitati in 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 la finestra 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 riquadri dell'API Maps JavaScript. Questo KML sembra (e si comporta in modo simile) agli elementi di overlay dell'API Maps JavaScript che conosci. Gli elementi KML <Placemark> e GeoRSS point vengono visualizzati come indicatori, ad esempio gli elementi <LineString> vengono visualizzati come polilinee e gli elementi <Polygon> vengono visualizzati come poligoni. Analogamente, gli elementi <GroundOverlay> vengono visualizzati come immagini rettangolari sulla mappa. Tuttavia, è importante notare che questi oggetti non sono Markers, Polylines, Polygons o GroundOverlays dell'API Maps JavaScript; vengono invece visualizzati come un unico oggetto sulla mappa.

Gli oggetti KmlLayer vengono visualizzati su una mappa una volta impostata la proprietà map. Puoi rimuoverli dalla mappa chiamando setMap() e comunicando 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 limiti cambiano, le funzionalità nel riquadro corrente vengono visualizzate automaticamente.

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

Opzioni del livello KML

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

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

Inoltre, una volta eseguito il rendering di 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 la comunicazione asincrona a un server esterno, devi rimanere in ascolto dell'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 della funzionalità KML

Poiché KML può includere un numero elevato di funzionalità, potresti non accedere direttamente ai dati delle funzionalità dall'oggetto KmlLayer. Al contrario, man mano che vengono visualizzati, gli elementi vengono visualizzati come overlay dell'API Maps JavaScript su cui è possibile fare clic. Se fai clic sulle singole funzionalità, per impostazione predefinita viene visualizzato un InfoWindow contenente informazioni <title> e <description> KML sulla funzionalità specifica. Inoltre, un clic su una funzionalità KML genera un KmlMouseEvent, che trasmette le seguenti informazioni:

• position indica le coordinate di latitudine/longitudine in cui ancorare InfoWindow per questa funzionalità KML. Questa posizione è in genere la posizione in cui è stato fatto clic per poligoni, polilinee e GroundOverlay, ma l'origine effettiva per i marcatori.
• pixelOffset indica l'offset rispetto a position per ancorare la InfoWindow "coda". 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 è mostrato un oggetto KmlFeatureData di esempio:

{
  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 riquadro laterale <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 KML

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

Nota:questi limiti sono soggetti a modifica 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 corsi KmlLayer creati 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 varia in base all'applicazione; in media, dovresti essere in grado di caricare tra 10 e 20 livelli senza raggiungere il limite. Se il limite viene ancora raggiunto, utilizza un servizio di abbreviazione degli URL per abbreviare gli URL KML. In alternativa, crea un unico 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 il rendimento per i tuoi utenti, in quanto verrà mostrata una rappresentazione efficiente in termini di spazio dei segmenti appropriati del tuo file KML, man mano che gli utenti fanno clic, spostano e ingrandiscono la mappa.

Per un rendimento ottimale, ti consigliamo di:

• Utilizza un tag <expires> appropriato in KML.
  
  KmlLayer non utilizza le intestazioni HTTP per decidere come memorizzare nella cache i file KML.
• Non generare file in modo dinamico al momento della richiesta.
  
  Genera invece i file prima che siano necessari e pubblicali in modo statico. Se il server impiega molto tempo a trasmettere il file KML, il KmlLayer potrebbe non essere visualizzato.
• Non tentare di bypassare le cache a meno che tu non sappia con certezza che il tuo file è stato aggiornato.
  
  L'aggiramento costante delle cache (ad esempio aggiungendo un numero casuale o l'ora dell'orologio dell'utente come parametro di query) può facilmente sovraccaricare i tuoi server se il tuo sito diventa improvvisamente popolare e servi file KML di grandi dimensioni.
  
  Può anche causare la pubblicazione di dati obsoleti nella cache per gli utenti, se l'orologio di un utente non è corretto e il tag <expires> non è stato impostato correttamente.
  
  Pubblica invece i file statici aggiornati con un nuovo numero di revisione discreto 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 al minuto.
  
  Se le dimensioni totali di tutti i file superano 1 MB (non compressi), limita le modifiche a una volta ogni 5 minuti.
• Quando utilizzi un server di dati geospaziali, evita di utilizzare i parametri di query per limitare la visualizzazione 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 nel server di dati geospaziali è presente una grande quantità di dati, valuta la possibilità di utilizzare i livelli di dati.
• Quando utilizzi un server di dati geospaziali, utilizza più KmlLayer per ogni gruppo di funzionalità che vuoi consentire agli utenti di attivare/disattivare, piuttosto che 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 cloud, evita di utilizzare funzionalità come URL firmati o token temporanei per applicare i controlli dell'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 la finestra 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.

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 dell'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 i dettagli completi degli elementi KML supportati.