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 valoreMap
su cui eseguire il rendering diKmlLayer
. Puoi nascondere un valoreKmlLayer
impostando questo valore sunull
all'interno del metodosetMap()
.preserveViewport
specifica che la mappa non deve essere regolata ai limiti dei contenuti diKmlLayer
quando viene mostrato il livello. Per impostazione predefinita, quando visualizzi unKmlLayer
, la mappa viene ingrandita e posizionata in modo da mostrare la totalità dei contenuti del livello.suppressInfoWindows
indica che le funzionalità cliccabili all'interno diKmlLayer
non devono attivare la visualizzazione degli oggettiInfoWindow
.
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;
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> <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>
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;
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> <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>
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 ancorareInfoWindow
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 valoreposition
sopra per ancorare la "coda" diInfoWindow
. Per gli oggetti poligonali, questo offset è in genere0,0
, ma per gli indicatori include l'altezza dell'indicatore.featureData
contiene una struttura JSON diKmlFeatureData
.
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;
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> <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>
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 elementoKmlLayer
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 aKmlLayer
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'eventobounds_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 singoloKmlLayer
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 |