Livelli KML e GeoRSS

L'elemento KmlLayer esegue il rendering degli elementi KML e GeoRSS in un Overlay del riquadro 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 viene mappata utilizzando un oggetto KmlLayer, il cui costruttore prende l'URL di un file KML o GeoRSS pubblicamente accessibile.

Nota: il corso KmlLayer che genera overlay KML utilizzando l'API Maps JavaScript un servizio ospitato da Google per il recupero e l'analisi dei file KML per il rendering. Di conseguenza, i file KML possono essere visualizzati solo se ospitati presso un URL pubblicamente accessibile che non richiede l'autenticazione per l'accesso.

Se hai bisogno di accedere a file privati, di avere un controllo granulare sulle cache inviare l'area visibile del browser a un server di dati geospaziali come parametro di query consigliamo di usare i dati anziché KmlLayer. Questa operazione consentirà di indirizzare per richiedere risorse direttamente al tuo server web.

L'API Maps JavaScript converte l'area geografica fornita dati XML in una rappresentazione KML che viene visualizzata sulla mappa utilizzando un Overlay del riquadro dell'API Maps JavaScript. Questo file KML ha (e in qualche modo si comporta) come la nota API Maps JavaScript di overlay. KML <Placemark> e GeoRSS point elementi vengono visualizzati come indicatori, ad esempio: vengono visualizzati elementi <LineString> visualizzato come polilinee e viene eseguito il rendering di <Polygon> elementi come poligoni. In modo simile, gli elementi <GroundOverlay> vengono visualizzate come immagini rettangolari sulla mappa. È importante, tuttavia, che questi oggetti non sono l'API Maps JavaScript Markers, Polylines, Polygons o GroundOverlays; vengono invece visualizzati in un singolo oggetto sulla mappa.

KmlLayer oggetto viene visualizzato su una mappa dopo il suo map è stata impostata. Puoi rimuoverle dalla mappa chiamando setMap(): superamento di null. KmlLayer gestisce il rendering di questi elementi secondari recuperare le caratteristiche appropriate per i limiti dati della mappa. Come i limiti cambiano, le caratteristiche nell'area visibile corrente vengono automaticamente eseguire il rendering.

Poiché i componenti all'interno di un KmlLayer vengono visualizzati on demand, il livello permette di gestire facilmente il rendering di migliaia di indicatori, polilinee e poligoni. Tieni presente che non puoi accedere a questi direttamente, sebbene ciascuno fornisca eventi di clic che restituiscono dati per i singoli oggetti.

Opzioni livello KML

Il costruttore KmlLayer() passa facoltativamente un numero KmlLayerOptions:

• map specifica il valore Map su cui eseguire il rendering KmlLayer. Puoi nascondere un elemento KmlLayer impostando questa opzione su null all'interno del metodo setMap().
• preserveViewport specifica che la mappa non deve essere adattato ai limiti dei contenuti di KmlLayer quando che mostra il livello. Per impostazione predefinita, quando visualizzi un KmlLayer, la mappa viene ingrandita e posizionata in modo da mostrare la totalità del livello contenuti.
• suppressInfoWindows indica che le funzionalità cliccabili all'interno KmlLayer non deve attivare la visualizzazione InfoWindow oggetti.

Inoltre, una volta eseguito il rendering, KmlLayer contiene una proprietà metadata immutabile contenente il nome del livello, descrizione, snippet e autore all'interno di un oggetto KmlLayerMetadata letterale. Puoi controllare queste informazioni utilizzando l'getMetadata() . Poiché il rendering degli oggetti KmlLayer richiede comunicazione asincrona con un server esterno, vorrai rimanere in ascolto l'evento metadata_changed, che indicherà che la proprietà è stato compilato.

L'esempio seguente crea un KmlLayer dall'elemento Feed GeoRSS:

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 file KML specificato feed:

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 delle funzionalità KML

Poiché il file KML può includere molte funzionalità, potresti non accedervi dei dati delle caratteristiche direttamente dall'oggetto KmlLayer. Invece, gli elementi vengono mostrati, diventano cliccabili Overlay dell'API Maps JavaScript. Facendo clic sulle singole funzionalità, per impostazione predefinita, viene visualizzata una InfoWindow con file KML <title> e <description> sulla funzionalità specificata. Inoltre, un clic su una funzionalità KML genera un KmlMouseEvent, che trasmette le seguenti informazioni:

• position indica le coordinate di latitudine/longitudine alla che ancorare il InfoWindow per questa funzionalità KML. Questo è la posizione su cui è stato fatto clic per poligoni, polilinee e GroundOverlay, ma la vera origine degli indicatori.
• pixelOffset indica l'offset da quanto riportato sopra position per ancorare 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 tipo 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 la funzionalità KML <Description> testo all'interno di un lato <div> quando l'utente 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 a dimensioni e complessità dei file KML caricati. Di seguito è riportato un riepilogo degli attuali limiti.

Nota: questi limiti sono soggetti a modifica in qualsiasi nel tempo.

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

3MB

Massima dimensione del file KML non compresso

10MB

Dimensione massima del file immagine non compresso nei file KMZ

500 kB 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 i livelli vengono mostrati sulla mappa e nel tuo sito web viene segnalato un errore. nella console JavaScript del browser. Il limite si basa su una combinazione di numero di KmlLayer corsi creati e la lunghezza totale tutti gli URL utilizzati per creare questi livelli. Ogni nuovo KmlLayer che crei occuperà una parte del limite per il livello e ulteriore parte del limite a seconda della lunghezza dell'URL in cui File KML caricato da. Di conseguenza, il numero di strati che puoi aggiungere varierà in base all'applicazione; in media, dovresti essere in grado di caricare 10 e 20 livelli senza raggiungere il limite. Se raggiungi comunque il limite, utilizzare uno strumento di abbreviazione di URL per abbreviare gli URL KML. In alternativa, crea un'istanza un singolo file KML composto da NetworkLinks ai singoli URL KML.

Considerazioni sulle prestazioni e sulla memorizzazione nella cache

I server di Google memorizzano temporaneamente nella cache i file KML per ridurre il carico sui tuoi server web. Questo migliorerà anche il rendimento per i tuoi utenti grazie alla pubblicazione di un efficiente in termini di spazio dei segmenti appropriati per il file KML, gli utenti possono fare clic, eseguire la panoramica e lo zoom della mappa.

Per un rendimento ottimale, ti consigliamo di:

• Utilizza un tag <expires> appropriato nel file KML.
  
  KmlLayer non utilizzerà le intestazioni HTTP per decidere in che modo per memorizzare nella cache i file KML.
• Non generare i 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 per trasmettere il file KML il file KmlLayer potrebbe non essere visualizzato.
• Non tentare di bypassare le cache a meno che tu non abbia la certezza assoluta è stato aggiornato.
  
  Ignorando sempre le cache (ad esempio, aggiungendo un numero casuale o orario dell'utente come parametro di query) può facilmente causare il tuo di essere sovraccarichi se il tuo sito diventa improvvisamente popolare e tu per gestire file KML di grandi dimensioni.
  
  Può anche fare in modo che la cache fornisca dati inattivi agli utenti, qualora l'orologio non è corretto e il tag <expires> non è stato siano impostati correttamente.
  
  Pubblica invece file statici aggiornati con un nuovo numero di revisione discreto, e utilizzare il codice lato server per aggiornare dinamicamente l'URL trasmesso KmlLayer con la versione corrente.
• Limita le modifiche ai file KML a una volta al minuto.
  
  Se la dimensione totale dei file supera 1 MB (non compressi), il limite è pari a una volta ogni 5 minuti.
• Quando utilizzi un server di dati geospaziali, evita di utilizzare parametri di query per limita l'area visibile dei livelli.
  
  Puoi invece limitare l'area visibile della mappa con Evento bounds_changed. Agli utenti verranno inviate soltanto le funzionalità possono essere visualizzati automaticamente.
  
  Se il server dei dati geospaziali contiene una grande quantità di dati, considera utilizzando i livelli dati .
• Quando utilizzi un server di dati geospaziali, usa più KmlLayer per ogni gruppo di funzionalità che vuoi consentire agli utenti di attivare, anziché rispetto a un singolo KmlLayer con parametri di query diversi.
• Utilizza file KMZ compressi per ridurre le dimensioni dei file.
• Se usi Google Cloud Storage o un'altra soluzione di archiviazione sul cloud, evitare 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 un la precisione appropriata.
• Unisci e semplifica la geometria di elementi simili, come i poligoni e le polilinee.
• Rimuovi eventuali elementi o risorse immagine inutilizzati.
• Rimuovi tutti gli elementi non supportati.

Se devi accedere a dati privati, impedire la memorizzazione nella cache o inviare al browser visibile a un server di dati geospaziali come parametro di query, consigliamo di usare livelli di dati anziché KmlLayer. Questa operazione consentirà di indirizzare browser per aprire direttamente richiedere 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 &lt;text&gt;
• 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 seguente tabella fornisce i dettagli completi degli elementi KML supportati.