Livelli KML e GeoRSS

Seleziona la piattaforma: Android iOS JavaScript

KmlLayer esegue il rendering degli elementi KML e GeoRSS in un overlay di riquadri 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 di Google per recuperare e analizzare i file KML per il rendering. Di conseguenza, i file KML possono essere visualizzati solo se sono ospitati in un URL accessibile pubblicamente che non richiede l'autenticazione per l'accesso.

Se hai bisogno dell'accesso a file privati, di un controllo granulare sulle cache o se vuoi inviare l'area visibile del browser a un server di dati geospaziale come parametro di ricerca, ti consigliamo di utilizzare i livelli di dati anziché KmlLayer. In questo modo i browser degli utenti verranno indirizzati alla richiesta diretta di risorse 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 KML ha l'aspetto (e un po' il comportamento) di elementi in overlay dell'API Maps JavaScript familiari. 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. Tuttavia, è importante sottolineare che questi oggetti non sono l'API Maps JavaScript Markers, Polylines, Polygons o GroundOverlays, ma vengono visualizzati in un singolo oggetto sulla mappa.

KmlLayer oggetti vengono visualizzati su una mappa una volta impostata la relativa proprietà map. Puoi rimuoverle 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. Quando i limiti cambiano, le caratteristiche nell'area visibile corrente vengono visualizzate automaticamente.

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 che lo compongono, anche se ognuno fornisce eventi di clic che restituiscono dati su quei singoli oggetti.

Opzioni dei livelli KML

Facoltativamente, il costruttore KmlLayer() passa un numero di KmlLayerOptions:

  • map specifica il Map su cui eseguire il rendering di KmlLayer. Puoi nascondere un KmlLayer impostando questo valore su null nel metodo setMap().
  • preserveViewport specifica che la mappa non deve essere regolata in base ai limiti dei contenuti di KmlLayer quando viene mostrato il livello. Per impostazione predefinita, quando visualizzi un elemento KmlLayer, la mappa viene ingrandita e posizionata in modo da mostrare l'intero contenuto del livello.
  • suppressInfoWindows indica che gli elementi cliccabili all'interno di KmlLayer non devono attivare la visualizzazione degli oggetti InfoWindow.

Inoltre, una volta eseguito il rendering, 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, dovrai rimanere in ascolto dell'evento metadata_changed, che indica che la proprietà è stata completata.

L'esempio seguente crea un elemento 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;

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;

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

HTML

<html>
  <head>
    <title>GeoRSS Layers</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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>

Prova Samples

L'esempio seguente crea un elemento 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;

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;

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

HTML

<html>
  <head>
    <title>KML Layers</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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>

Prova Samples

Dettagli delle funzionalità KML

Poiché il file KML può includere un numero elevato di funzionalità, potresti non accedere ai relativi dati direttamente dall'oggetto KmlLayer. Man mano che vengono visualizzate, le funzionalità vengono visualizzate in modo da sembrare overlay cliccabili dell'API Maps JavaScript. Se fai clic sulle singole funzionalità, per impostazione predefinita viene visualizzato un InfoWindow contenente informazioni KML <title> e <description> sull'elemento in questione. 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 il InfoWindow per questo elemento KML. Questa posizione corrisponde in genere alla posizione selezionata per i poligoni, le polilinee e i GroundOverlay, ma la vera origine degli indicatori.
  • pixelOffset indica lo sfasamento rispetto al precedente 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 è 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 dell'elemento KML <Description> all'interno di un lato <div> quando viene fatto clic sull'elemento:

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;

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;

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

HTML

<html>
  <head>
    <title>KML Feature Details</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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>

Prova Samples

Limitazioni di dimensioni e complessità per il rendering KML

L'API Maps JavaScript è soggetta a 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 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 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 tuoi livelli verrà visualizzato sulla mappa e verrà segnalato un errore nella console JavaScript del 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 i livelli. Ogni nuovo elemento 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 a seconda dell'applicazione; in media, dovresti essere in grado di caricare tra 10 e 20 livelli senza raggiungere il limite. Se raggiungi ancora il limite, utilizza un accorciatore di URL per accorciare gli URL KML. In alternativa, crea un singolo file KML composto da NetworkLinks ai singoli URL KML.

Considerazioni su prestazioni e memorizzazione nella cache

I server di Google memorizzano temporaneamente nella cache i file KML per ridurre il carico sui server. Ciò migliorerà anche le prestazioni per i tuoi utenti, poiché ti fornirà una rappresentazione efficiente dello spazio dei segmenti appropriati nel tuo file KML, quando gli utenti fanno clic sulla mappa, eseguono la panoramica e lo zoom.

Per un rendimento ottimale, 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 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, l'elemento KmlLayer potrebbe non essere visualizzato.
  • Non tentare di bypassare le cache a meno che tu non abbia la certezza assoluta che il tuo file è stato aggiornato.

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

    Inoltre, la cache potrebbe fornire dati inattivi agli utenti se l'orologio di un utente non è corretto e se il tag <expires> non è stato impostato correttamente.

    Al contrario, pubblica i 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 (non compressi è superiore a 1 MB), il limite di modifiche sarà applicato a una volta ogni 5 minuti.
  • Se utilizzi un server di dati geospaziali, evita di usare 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 di dati geospaziali contiene una grande quantità di dati, valuta la possibilità di utilizzare invece i 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 ridurne le dimensioni.
  • Se usi Google Cloud Storage o un'altra soluzione di archiviazione sul cloud, evita di utilizzare funzionalità come gli URL firmati o i 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 eventuali elementi o risorse immagine inutilizzati.
  • Rimuovi gli elementi non supportati.

Se devi 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 verranno reindirizzati alla richiesta di risorse direttamente 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 seguente tabella fornisce informazioni dettagliate sugli elementi KML supportati.

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