Livelli KML e GeoRSS

Seleziona la piattaforma: Android iOS JavaScript

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

Panoramica

L'API Maps JavaScript supporta i formati di dati KML e GeoRSS per la visualizzazione delle 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 pubblicamente accessibile.

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

Se hai bisogno di accedere a file privati, di avere un controllo granulare sulle cache o di inviare l'area visibile del browser a un server di dati geospaziali come parametro di query, ti consigliamo di utilizzare i livelli dati anziché KmlLayer. Questo indirizzerà i browser degli utenti a richiedere risorse direttamente al 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 l'aspetto (e in qualche modo si comporta) come elementi di overlay dell'API Maps JavaScript. Gli elementi KML <Placemark> e GeoRSS point vengono visualizzati come indicatori, ad esempio gli elementi <LineString> come polilinee, mentre gli elementi <Polygon> come poligoni. In modo simile, gli elementi <GroundOverlay> vengono visualizzati come immagini rettangolari sulla mappa. È importante sottolineare, 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 oggetti vengono visualizzati su una mappa dopo aver impostato la relativa proprietà map. Puoi rimuoverle dalla mappa chiamando setMap() superando null. L'oggetto KmlLayer gestisce il rendering di questi elementi secondari recuperando automaticamente le caratteristiche appropriate per i limiti specificati della mappa. Al variare dei limiti, viene eseguito automaticamente il rendering delle caratteristiche nell'area visibile corrente.

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

Opzioni livello KML

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

  • map specifica il valore Map su cui eseguire il rendering di KmlLayer. Puoi nascondere un valore KmlLayer impostando questo valore su null all'interno del metodo setMap().
  • preserveViewport specifica che la mappa non deve essere regolata ai limiti dei contenuti di KmlLayer quando viene mostrato il livello. Per impostazione predefinita, quando visualizzi un KmlLayer, la mappa viene ingrandita e posizionata in modo da mostrare la totalità dei contenuti del livello.
  • suppressInfoWindows indica che le funzionalità cliccabili all'interno di KmlLayer non devono attivare la visualizzazione degli 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 controllare queste informazioni utilizzando il metodo getMetadata(). Poiché il rendering degli oggetti KmlLayer richiede la comunicazione asincrona con un server esterno, conviene ascoltare l'evento metadata_changed, che indica che la proprietà è stata compilata.

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

TypeScript

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

JavaScript

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

CSS

/* 
 * 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

<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

Prova Sample

L'esempio seguente genera un KmlLayer dal feed KML specificato:

TypeScript

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

JavaScript

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

CSS

/* 
 * 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

<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

Prova Sample

Dettagli delle funzionalità KML

Poiché il file KML può includere un numero elevato di funzionalità, potresti non essere in grado di accedere ai dati delle funzionalità direttamente dall'oggetto KmlLayer. Al contrario, man mano che vengono visualizzate, le caratteristiche vengono visualizzate come overlay cliccabili dell'API Maps JavaScript. Se fai clic sulle singole funzionalità, per impostazione predefinita viene visualizzato un elemento InfoWindow contenente informazioni su <title> e <description> KML relative alla funzionalità in questione. Inoltre, un clic su una funzionalità KML genera un KmlMouseEvent, che trasmette le seguenti informazioni:

  • position indica le coordinate di latitudine/longitudine su cui ancorare InfoWindow per questa funzionalità KML. Questa posizione è generalmente la posizione su cui è stato fatto clic per poligoni, polilinee e GroundOverlay, ma la vera origine degli indicatori.
  • pixelOffset indica l'offset del valore position sopra 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 è 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 lato <div> quando l'utente fa clic sulla funzionalità:

TypeScript

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

JavaScript

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

CSS

/* 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

<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

Prova Sample

Limitazioni di dimensioni e complessità per il rendering KML

L'API Maps JavaScript presenta limitazioni in termini di dimensioni e complessità dei file KML caricati. Di seguito è riportato un riepilogo degli attuali limiti.

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
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 Google. Se superi questo limite, nessuno dei livelli sarà visualizzato sulla mappa e verrà segnalato un errore nella console JavaScript del tuo browser web. Il limite si basa su una combinazione tra il numero di classi KmlLayer create e la lunghezza totale di tutti gli URL utilizzati per creare questi livelli. Ogni nuovo elemento KmlLayer che crei occuperà una parte del limite per il livello e un'altra 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 raggiungi ancora il limite, utilizza uno strumento di abbreviazione di URL per abbreviare gli URL KML. In alternativa, crea un singolo file KML costituito da NetworkLinks che rimandano 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. Ciò migliorerà anche le prestazioni per i tuoi utenti mediante la pubblicazione di una rappresentazione efficiente dello spazio dei segmenti appropriati del file KML, mentre gli utenti fanno clic, eseguono 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 come memorizzare nella cache i file KML.
  • Non generare i file in modo dinamico al momento della richiesta.

    Devi generare i file prima che siano necessari e pubblicarli in modo statico. Se il server impiega molto tempo per trasmettere il file KML, KmlLayer potrebbe non essere visualizzato.
  • Non tentare di bypassare le cache a meno che tu non abbia la certezza assoluta dell'aggiornamento del file.

    Ignorare sempre le cache (ad esempio, aggiungendo un numero casuale o l'ora dell'orologio dell'utente come parametro di query) può facilmente causare il sovraccaricamento dei tuoi server se il tuo sito diventa improvvisamente popolare e pubblichi file KML di grandi dimensioni.

    Inoltre, la cache può fornire dati inattivi agli 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 discreto e utilizza il codice lato server per aggiornare in modo dinamico l'URL trasmesso 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 supera 1 MB (non compresso), limita la modifica a una volta ogni 5 minuti.
  • Quando utilizzi un server di dati geospaziali, evita di utilizzare parametri di query per limitare l'area visibile 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 server dei dati geospaziali contiene 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, 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 cloud, evita di utilizzare funzionalità come URL firmati o token temporanei per applicare i controlli dell'accesso. Questi elementi 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 eventuali elementi o risorse immagine inutilizzati.
  • Rimuovi tutti gli elementi non supportati.

Se hai bisogno di accedere a dati privati, impedire la memorizzazione nella cache o inviare l'area visibile del browser a un server di dati geospaziali come parametro di query, ti consigliamo di utilizzare i livelli dati anziché KmlLayer. In questo modo, i browser degli utenti potranno richiedere risorse direttamente 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 seguente tabella fornisce i dettagli completi degli elementi KML supportati.

Elemento KML Supportato nell'API? Commento
<address> no
<AddressDetails> no
<Alias> N/A <Model> non è supportato
<altitude> no
<altitudeMode> no
<atom:author> sì
<atom:link> sì
<atom:name> sì
<BalloonStyle> parzialmente è supportato solo <text>
<begin> N/A Il valore <TimeSpan> non è supportato
<bgColor> no
<bottomFov> N/A <PhotoOverlay> non è supportato
<Camera> no
<Modifica> parzialmente sono supportate solo le modifiche dello stile
<color> parzialmente include #AABBGGRR e #BBGGRR; non supportato in <IconStyle>, <ScreenOverlay> e <GroundOverlay>
<colorMode> no
<cookie> no
<coordinates> sì
<Crea> no
<Data> sì
<Elimina> no
<description> sì I contenuti HTML sono consentiti, ma sono sottoposti a sanitizzazione per proteggere gli utenti da attacchi cross-browser. Le sostituzioni di entità nel formato $[dataName] non sono supportate.
<displayMode> no
<displayName> no
<Document> parzialmente implicitamente, gli elementi secondari sono supportati; nessun effetto come elemento secondario di altre funzionalità
<drawOrder> no
<east> sì
<end> N/A Il valore <TimeSpan> non è supportato
<expires> sì consulta la sezione Riepilogo per maggiori dettagli
<ExtendedData> parzialmente solo <Data> non digitati, nessun <SimpleData> o <Schema> e le sostituzioni di entità del modulo $[dataName] non sono supportate.
<extrude> no
<fill> sì
<flyToView> no
<Cartella> sì
<geomColor> no ritirato
<GeometryCollection> no ritirato
<geomScale> no ritirato
<gridOrigin> N/A <PhotoOverlay> non è supportato
<GroundOverlay> sì non possono essere ruotati
<h> sì ritirato
<heading> sì
suggerimento sì target=... supportati
<hotSpot> sì
<href> sì
<httpQuery> no
<Icon> sì non possono essere ruotati
<IconStyle> sì
<ImagePyramid> N/A <PhotoOverlay> non è supportato
<innerBoundaryIs> sì implicitamente dall'ordine <LinearRing>
<ItemIcon> N/A <ListStyle> non è supportato
<key> N/A <StyleMap> non è supportato
<kml> sì
<labelColor> no ritirato
<LabelStyle> no
<latitude> sì
<LatLonAltBox> sì
<LatLonBox> sì
<leftFov> N/A <PhotoOverlay> non è supportato
<LinearRing> sì
<LineString> sì
<LineStyle> sì
<Link> sì
<linkDescription> no
<linkName> no
<linkSnippet> no
<listItemType> N/A <ListStyle> non è supportato
<ListStyle> no
<Località> N/A <Model> non è supportato
<Lod> sì
<longitude> sì
<LookAt> no
<maxAltitude> sì
<maxFadeExtent> sì
<maxHeight> N/A <PhotoOverlay> non è supportato
<maxLodPixels> sì
<maxSessionLength> no
<maxWidth> N/A <PhotoOverlay> non è supportato
<message> no
<Metadata> no ritirato
<minAltitude> sì
<minFadeExtent> sì
<minLodPixels> sì
<minRefreshPeriod> no <NetworkLink>
<Modello> no
<MultiGeometry> parzialmente sottoposti a rendering, ma mostrati come funzionalità separate nel riquadro laterale a sinistra
<name> sì
<vicino> N/A <PhotoOverlay> non è supportato
<NetworkLink> sì  
<NetworkLinkControl> parzialmente Le funzionalità <Update> e <expires> sono parzialmente supportate. L'API ignora le impostazioni di scadenza nelle intestazioni HTTP ma utilizza le impostazioni di scadenza specificate nel file KML. In assenza di impostazioni per la scadenza o entro l'intervallo di validità temporale, Google Maps potrebbe memorizzare nella cache i dati recuperati da internet per periodi di tempo non specificati. Il recupero dei dati da internet può essere forzato rinominando il documento e recuperandolo con un URL diverso oppure assicurandoti che il documento contenga le impostazioni di scadenza appropriate.
<north> sì
<open> sì
<Orientation> N/A <Model> non è supportato
<outerBoundaryIs> sì implicitamente dall'ordine <LinearRing>
<outline> sì
<overlayXY> no
<Pair> N/A <StyleMap> non è supportato
<phoneNumber> no
<PhotoOverlay> no
<Placemark> sì
<Point> sì
<Polygon> sì
<PolyStyle> sì
<range> sì
<refreshInterval> parzialmente Solo <Link>; non in <Icon>
<refreshMode> sì Intestazioni HTTP non supportate per la modalità "onExpire". Vedi le note relative a <Update> e <expires> sopra.
<refreshVisibility> no
<Region> sì
<ResourceMap> N/A <Model> non è supportato
<rightFov> N/A <PhotoOverlay> non è supportato
<roll> N/A <Camera> e <Model> non sono supportati
<rotation> no
<rotationXY> no
<Scala> N/A <Model> non è supportato
<scale> no
<Schema> no
<SchemaData> no
<ScreenOverlay> sì non possono essere ruotati
<screenXY> no
<shape> N/A <PhotoOverlay> non è supportato
<SimpleData> N/A Il campo <SchemaData> non è supportato
<SimpleField> N/A Il campo <Schema> non è supportato
<size> sì
<Snippet> sì
<south> sì
<state> N/A <ListStyle> non è supportato
<Style> sì
<StyleMap> no gli effetti di riporto (evidenziazione) non sono supportati
<styleUrl> N/A <StyleMap> non è supportato
<targetHref> parzialmente supportato in <Update>, non in <Alias>
<tessellate> no
<text> sì sostituzione di $[geDirections] non supportata
<textColor> no
<tileSize> N/A <PhotoOverlay> non è supportato
<tilt> no
<TimeSpan> no
<TimeStamp> no
<topFov> N/A <PhotoOverlay> non è supportato
<Aggiorna> parzialmente solo modifiche di stile, non <Create> o <Delete>
<Url> sì ritirato
<value> sì
<viewBoundScale> no
<viewFormat> no
<viewRefreshMode> parzialmente "onStop" è supportato
<viewRefreshTime> sì
<ViewVolume> N/A <PhotoOverlay> non è supportato
<visibility> parzialmente sì su <Cartella>: i segnaposto secondari ereditano la loro visibilità
<w> sì ritirato
<west> sì
<when> N/A Il valore <TimeStamp> non è supportato
<width> sì
<x> sì ritirato
<y> sì ritirato