KML- und GeoRSS-Ebenen

KmlLayer rendert KML- und GeoRSS-Elemente in ein Maps JavaScript API-Kachel-Overlay.

Übersicht

Die Maps JavaScript API unterstützt die KML- und GeoRSS-Datenformate zum Anzeigen geografischer Informationen. Diese Datenformate werden auf der Karte mithilfe eines KmlLayer-Objekts dargestellt, für dessen Konstruktor die URL einer öffentlich verfügbaren KML- oder GeoRSS-Datei angegeben wird.

Hinweis: Die Klasse KmlLayer, über die KML-Overlays in der Maps JavaScript API generiert werden, verwendet einen von Google gehosteten Dienst, um KML-Dateien zum Rendern abzurufen und zu parsen. Daher können KML-Dateien nur angezeigt werden, wenn sie unter einer öffentlich zugänglichen URL gehostet werden, für deren Zugriff keine Authentifizierung erforderlich ist.

Wenn Sie auf private Dateien zugreifen, Caches detailgenau kontrollieren oder den Darstellungsbereich des Browsers als Abfrageparameter an ein Geoinformationssystem senden müssen, sollten Sie Data-Ebenen anstelle von KmlLayer verwenden. Dadurch werden die Browser Ihrer Nutzer angewiesen, Ressourcen direkt von Ihrem Webserver anzufordern.

Die Maps JavaScript API wandelt die bereitgestellten geografischen XML-Daten in eine KML-Darstellung um, die mithilfe eines Maps JavaScript API-Kachel-Overlays auf der Karte angezeigt wird. Die KML-Darstellung sieht wie bekannte Overlay-Elemente der Maps JavaScript API aus und verhält sich auch ähnlich. KML-<Placemark>- und GeoRSS-point-Elemente werden als Markierungen gerendert, <LineString>-Elemente z. B. als Polylinien und <Polygon>-Elemente als Polygone. In ähnlicher Weise werden <GroundOverlay>-Elemente als rechteckige Bilder auf der Karte gerendert. Diese Objekte sind jedoch keine Markers-, Polylines-, Polygons- oder GroundOverlays-Elemente der Maps JavaScript API. Sie werden stattdessen als einzelnes Objekt auf der Karte gerendert.

KmlLayer-Objekte werden auf einer Karte dargestellt, sobald ihre map-Eigenschaft festgelegt wurde. Sie können sie von der Karte entfernen, indem Sie setMap() aufrufen und dabei null übergeben. Das KmlLayer-Objekt verwaltet das Rendern dieser untergeordneten Elemente, indem es automatisch die passenden Kartenelemente für die gegebenen Grenzen der Karte abruft. Wenn sich die Grenzen ändern, werden die Elemente im aktuellen Darstellungsbereich automatisch gerendert.

Da die Komponenten innerhalb einer KmlLayer auf Anfrage gerendert werden, können Sie mit der Ebene ganz einfach das Rendern Tausender Markierungen, Polylinien und Polygone verwalten. Sie können nicht direkt auf die zugehörigen Objekte zugreifen. Stattdessen werden diese in Form von Click-Events verfügbar, die Daten zu den einzelnen Objekten liefern.

Optionen für KML-Ebenen

Der KmlLayer()-Konstruktor übergibt optional eine Reihe von KmlLayerOptions:

• map definiert die Map, auf der die KmlLayer gerendert werden soll. Sie können eine KmlLayer ausblenden, indem Sie in der setMap()-Methode null für diesen Wert festlegen.
• preserveViewport gibt an, dass die Karte nicht an die Grenzen der KmlLayer-Inhalte angepasst werden soll, wenn die Ebene angezeigt wird. Beim Anzeigen einer KmlLayer wird die Karte standardmäßig so gezoomt und positioniert, dass alle Inhalte der Ebene angezeigt werden.
• suppressInfoWindows gibt an, dass anklickbare Kartenelemente innerhalb der KmlLayer nicht die Anzeige von InfoWindow-Objekten auslösen sollen.

Sobald die KmlLayer gerendert ist, enthält sie außerdem eine unveränderliche metadata-Eigenschaft, die den Namen, die Beschreibung, das Snippet und den Autor der Ebene in einem KmlLayerMetadata-Objektliteral enthält. Sie können diese Informationen mithilfe der getMetadata()-Methode einsehen. Da für das Rendern von KmlLayer-Objekten eine asynchrone Kommunikation mit einem externen Server erforderlich ist, sollten Sie auf das metadata_changed-Ereignis warten. Es zeigt an, dass ein Wert für die Eigenschaft gesetzt wurde.

Im folgenden Beispiel wird eine KmlLayer aus dem angegebenen GeoRSS-Feed erstellt:

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

Im folgenden Beispiel wird eine KmlLayer aus dem angegebenen KML-Feed erstellt:

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

Details zu KML-Elementen

KML kann sehr viele Kartenelemente enthalten. Daher ist es nicht möglich, direkt über das KmlLayer-Objekt auf die Elementdaten zuzugreifen. Werden Elemente angezeigt, werden sie stattdessen als anklickbare Maps JavaScript API-Overlays gerendert. Wenn ein Element angeklickt wird, wird standardmäßig ein InfoWindow mit KML-<title> und -<description> des jeweiligen Elements eingeblendet. Außerdem wird ein KmlMouseEvent generiert, das folgende Informationen übergibt:

• position gibt die Breiten- und Längengradkoordinaten an, bei denen das InfoWindow für dieses KML-Element verankert werden soll. Bei Polygonen, Polylinien und Boden-Overlays ist das in der Regel die Klickposition, bei Markierungen jedoch der tatsächliche Ursprung.
• pixelOffset gibt die Abweichung zur position oben an, an der die Sprechblasenspitze des InfoWindow verankert werden soll. Bei Polygonobjekten ist das in der Regel 0,0; bei Markierungen enthält sie jedoch die Höhe der Markierung.
• featureData enthält eine JSON-Struktur mit KmlFeatureData.

Hier ein Beispiel für ein KmlFeatureData-Objekt:

{
  author: {
    email: "nobody@google.com",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

Mit folgendem Beispiel wird beim Anklicken eines KML-Elements der entsprechende <Description>-Text in einem seitlichen <div>-Bereich angezeigt:

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

Größen- und Komplexitätsbeschränkungen für das KML-Rendering

Für die Maps JavaScript API gelten Einschränkungen hinsichtlich der Größe und Komplexität von geladenen KML-Dateien. Hier eine Übersicht der aktuellen Limits:

Hinweis: Diese Limits können sich jederzeit ändern.

Maximale Größe für abgerufene Dateien (RAW-KML-, RAW-GeoRSS- oder komprimierte KMZ-Datei)

3 MB

Maximale Größe für nicht komprimierte KML-Dateien

10 MB

Maximale Größe für nicht komprimierte Bilddateien in KMZ-Dateien

500 KB pro Datei

Maximale Anzahl der Netzwerk-Links

10

Maximale Anzahl von Elementen im Dokument

1.000

Anzahl der KML-Ebenen

Es gibt ein Limit für die Anzahl der KML-Ebenen, die auf einer Google-Karte angezeigt werden können. Wenn Sie das Limit überschreiten, werden keine Ihrer Ebenen auf der Karte angezeigt und es wird ein Fehler in der JavaScript-Konsole Ihres Webbrowsers ausgegeben. Das Limit beruht auf einer Kombination aus der Anzahl der erstellten KmlLayer-Klassen und der Gesamtlänge aller URLs, die zum Erstellen dieser Ebenen verwendet wurden. Jede neu erstellte KmlLayer beansprucht einen Teil des Limits für die Ebene sowie einen weiteren Teil, der sich nach der Länge der URL richtet, von der die KML-Datei geladen wurde. Daher kann die Anzahl der Ebenen, die sich hinzufügen lassen, je nach Anwendung variieren. Sie sollten durchschnittlich 10 bis 20 Ebenen laden können, ohne das Limit zu überschreiten. Falls Sie es doch erreichen, können Sie die KML-URLs mit einem Kurz-URL-Dienst verkürzen. Alternativ haben Sie die Möglichkeit, eine einzelne KML-Datei mit Netzwerk-Links zu den einzelnen KML-URLs zu erstellen.

Überlegungen zu Leistung und Caching

Die Google-Server speichern KML-Dateien vorübergehend im Cache, um Ihre Server zu entlasten. Dadurch verbessert sich auch die Leistung für Ihre Nutzer, da eine speichereffiziente Darstellung der entsprechenden Segmente Ihrer KML-Datei angezeigt wird, wenn die Nutzer die Karte anklicken, verschieben und zoomen.

Für optimale Leistung empfehlen wir Folgendes:

• Verwenden Sie in KML ein geeignetes <expires>-Tag.
  
  KmlLayer verwendet keine HTTP-Header, um zu entscheiden, wie KML-Dateien im Cache gespeichert werden sollen.
• Lassen Sie Dateien nicht zur Zeit der Anfrage dynamisch generieren.
  
  Generieren Sie die Dateien stattdessen, bevor sie benötigt werden, und stellen Sie sie statisch bereit. Wenn die Übertragung der KML-Datei durch Ihren Server zu lange dauert, wird die KmlLayer möglicherweise nicht angezeigt.
• Versuchen Sie nicht, Caches zu umgehen, es sei denn, Sie sind sicher, dass Ihre Datei aktualisiert wurde.
  
  Wenn Sie Caches immer umgehen, indem Sie z. B. eine Zufallszahl oder die Uhrzeit des Nutzers als Abfrageparameter anhängen, können Ihre Server leicht überlastet werden, wenn Ihre Website plötzlich stark frequentiert wird und Sie große KML-Dateien bereitstellen.
  
  Es kann auch dazu führen, dass der Cache Nutzern veraltete Daten liefert, wenn die Uhr des Nutzers falsch eingestellt ist und das <expires>-Tag nicht korrekt gesetzt wurde.
  
  Veröffentlichen Sie stattdessen aktualisierte statische Dateien mit einer neuen, eindeutigen Überarbeitungsnummer und verwenden Sie serverseitigen Code, um die an die KmlLayer übergebene URL dynamisch mit der aktuellen Version zu aktualisieren.
• KML-Dateien sollten höchstens einmal pro Minute aktualisiert werden.
  
  Wenn alle Dateien zusammen mehr als 1 MB groß sind (unkomprimiert), sollten Änderungen maximal alle 5 Minuten stattfinden.
• Bei Nutzung eines Geoinformationssystems sollten Sie keine Abfrageparameter verwenden, um den Darstellungsbereich von Ebenen zu begrenzen.
  
  Stattdessen können Sie den Darstellungsbereich der Karte mit dem Ereignis bounds_changed einschränken. Nutzer erhalten dann nur Kartenelemente, die automatisch angezeigt werden können.
  
  Wenn Ihr Geoinformationssystem eine große Menge an Daten enthält, sollten Sie stattdessen Datenschichten verwenden.
• Wenn Sie ein Geoinformationssystem verwenden, sollten Sie mehrere KmlLayer für jede Gruppe von Elementen verwenden, die Nutzer ein- und ausblenden können sollen, und keine einzelne KmlLayer mit unterschiedlichen Abfrageparametern.
• Verwenden Sie komprimierte KMZ-Dateien, um die Dateigröße zu verringern.
• Wenn Sie Google Cloud Storage oder eine andere Cloud-Speicherlösung nutzen, verwenden Sie möglichst keine Features wie signierte URLs oder temporäre Tokens für die Zugriffssteuerung. Sie könnten das Caching ungewollt verhindern.
• Verringern Sie die Genauigkeit aller Punkte auf eine ausreichende Genauigkeit.
• Führen Sie die Geometrie ähnlicher Kartenelemente, wie z. B. Polygone und Polylinien, zusammen und vereinfachen Sie sie.
• Entfernen Sie alle Elemente oder Bildressourcen, die nicht verwendet werden.
• Entfernen Sie alle nicht unterstützten Elemente.

Wenn Sie auf private Daten zugreifen, das Caching verhindern oder den Darstellungsbereich des Browsers als Abfrageparameter an ein Geoinformationssystem senden müssen, sollten Sie Datenschichten anstelle von KmlLayer verwenden. Dadurch werden die Browser Ihrer Nutzer angewiesen, Ressourcen direkt von Ihrem Webserver anzufordern.

Unterstützte KML-Elemente

Die Maps JavaScript API unterstützt die folgenden KML-Elemente. In der Regel ignoriert der KML-Parser XML-Tags, die er nicht parsen kann, ohne Meldung.

• Ortsmarkierungen
• Symbole
• Ordner
• HTML-Beschreibungen: Ersetzen von Entitäten über <BalloonStyle> und <text>
• KMZ (komprimierter KML-Code, einschließlich angefügter Bilder)
• Polylinien und Polygone
• Stile für Polylinien und Polygone, einschließlich Farbe, Füllung und Deckkraft
• Netzwerk-Links für den dynamischen Import von Daten
• Boden- und Bildschirm-Overlays

Die folgende Tabelle enthält alle Details zu den unterstützten KML-Elementen.