Migrationspfade für KmlLayer

Einführung

In dieser Anleitung werden die häufigsten Anwendungsfälle von KmlLayer behandelt und entsprechende Migrationspfade zu alternativen Implementierungen bereitgestellt. Diese Informationen richten sich an Entwickler, die aufgrund der geplanten Einstellung von KmlLayer auf eine andere Lösung umstellen müssen. Die letzte Version, die KmlLayer unterstützt, ist 3.65. Sie wird im Mai 2027 eingestellt.

Ihr Migrationspfad hängt davon ab, wie Sie KmlLayer verwenden:

KML-Datei zum Formatieren von Informationen zu Grenzen, Grenzlinien und Gebieten von Interesse

Entwicklern, die KmlLayer verwenden, um administrative Grenzen darzustellen oder zu gestalten, z. B. um ein bestimmtes Land, einen bestimmten Bundesstaat oder einen bestimmten Ort hervorzuheben, empfiehlt die Google Maps Platform, zu datengestützten Stilen für Grenzen zu migrieren.

Migrationsempfehlung: Datengestützte Stile für Grenzen

Datengestützte Stile für Grenzen bieten direkten Zugriff auf die Polygone für Verwaltungsgrenzen von Google. So können Sie benutzerdefinierte Stile (Füllung und Strich) auf diese Regionen anwenden, ohne externe KML-Dateien hosten oder verwalten zu müssen.

Verfügbarer FeatureType

Verwaltungsgebiete sind nach Funktion kategorisiert und nach Ebenen geordnet. Die folgenden Elementtypen werden für die Gestaltung unterstützt:

  • COUNTRY: Die nationale politische Einheit.
  • ADMINISTRATIVE_AREA_LEVEL_1: Eine öffentliche Verwaltungseinheit eine Stufe unterhalb der Landesebene (z.B. Bundesstaaten in den USA).
  • ADMINISTRATIVE_AREA_LEVEL_2: Eine öffentliche Verwaltungseinheit der zweiten Ebene unterhalb der Landesebene (z.B. Countys in den USA).
  • LOCALITY: Eine politische Einheit in Form einer Stadt oder Gemeinde.
  • POSTAL_CODE: Postleitzahlen, wie sie für die Post verwendet werden.
  • SCHOOL_DISTRICT: Schulbezirke für Gesamtschulen, Grundschulen oder weiterführende Schulen.

Unter Abdeckung von Grenzen finden Sie Informationen zur Verfügbarkeit dieser Elementtypen nach Region.

Bereich hervorheben

Wenn Sie eine bestimmte Region gestalten möchten, müssen Sie sie anhand ihrer Orts-ID ansprechen.

  • Einrichtung: Sie müssen eine Karten-ID verwenden, die für den JavaScript-Kartentyp Vektor konfiguriert ist, und die Element-Ebene in der Google Cloud Console aktivieren.
  • Implementierung: Verwenden Sie den Beispielcode unter Grenzpolygon formatieren.

Schwenken auf einen Bereich beschränken

Wenn Sie verhindern möchten, dass Nutzer den Begrenzungsrahmen des hervorgehobenen Bereichs verlassen, können Sie die Option restriction in MapOptions verwenden.

Das restriction-Objekt definiert ein latLngBounds, das den sichtbaren Bereich der Karte begrenzt. Weitere Informationen zur Funktionsweise der Einschränkung

// Restrict panning to a specific bounding box
restriction: {
  latLngBounds: {
    north: 47.8,
    south: 45.8,
    east: 10.5,
    west: 5.9,
  },
  strictBounds: true,
},

Zusammenfassung der Migrationsimplementierung

Hier sehen Sie ein vollständiges Beispiel für die Verwendung von datengestützten Stilen für Grenzen und einer Regionsbeschränkung, um die Karte auf einen bestimmten Bereich zu konzentrieren.

const myTargetRegion = "ChIJYW1Zb-9kjEcRFXvLDxG1Vlw"; // Place ID for Switzerland

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 46.8, lng: 8.2 },
    zoom: 9,
    mapId: "YOUR_MAP_ID", // Required for DDS
    // Restrict panning to a specific bounding box
    restriction: {
    // Bounding box for Switzerland
      latLngBounds: {
        north: 47.8,
        south: 45.8,
        east: 10.5,
        west: 5.9,
      },
      strictBounds: true,
    },
  });

  // Access the Country layer and style a specific region by Place ID
  const countryLayer = map.getFeatureLayer("COUNTRY");
  countryLayer.style = (options) => {
    if (options.feature.placeId === myTargetRegion) {
      return {
        fillColor: "#FF0000",
        fillOpacity: 0.5,
        strokeColor: "#FF0000",
        strokeWeight: 2,
      };
    } else {
    // Style everything else whited out, to make the area of interest pop out more.
      return {
        fillColor: '#ffffff',
        fillOpacity: 0.8,
      };
    }
  };
}

KML-Datei mit Vektordaten (Punkte/Polylinien/Grenzen/Polygone)

Migrationsempfehlung: Datengestützte Stile für Datasets

Google empfiehlt den folgenden Ansatz, um öffentlich verfügbare geografische Daten darzustellen und gleichzeitig mehr Kontrolle über das Styling und die Leistung zu erhalten.

Mit datengestützten Stilen für Datasets können Sie eigene raumbezogene Daten (KML, GeoJSON oder CSV) hochladen, benutzerdefinierte Stile auf Grundlage von Datenattributen anwenden und Elemente auf Vektorkarten darstellen.

1. Einrichtung und Upload

Im Gegensatz zu KmlLayer, bei dem eine URL zur Laufzeit abgerufen wird, müssen Sie die Daten für DDS als Dataset in der Google Cloud Console hosten.

2. Darstellungsbereich auf die Daten festlegen

KmlLayer schwenkt und zoomt standardmäßig automatisch zum Datenstandort. Bei DDS für Datasets erfolgt dieses Verhalten nicht automatisch und muss manuell implementiert werden.

  • Fest codierte Einschränkungen: Wenn der Datenbereich statisch ist, verwenden Sie die Option restriction in MapOptions, um das Sichtfeld auf bestimmte Grenzen zu beschränken.
  • Dynamisches Zoomen: Wenn Sie den Darstellungsbereich dynamisch festlegen möchten, können Sie map.fitBounds() mit dem Begrenzungsrahmen Ihres Datasets verwenden.

3. Stile aus Feature-Attributen

KML-Dateien enthalten oft Stilinformationen (z. B. Farben), die in DDS nicht automatisch angewendet werden. Sie müssen eine clientseitige Stilfunktion erstellen, mit der Attribute aus den Dataset-Elementen gelesen werden, um Farben und Deckkraft anzuwenden. Weitere Informationen zum Formatieren von Daten

Beispiel: Funktion mit Attributen gestalten

Im folgenden Beispiel wird gezeigt, wie Sie eine Stilfunktion erstellen, die die Attribute background_color und opacity direkt aus dem hochgeladenen Dataset liest:

/**
 * Migration example: Styling features from dataset attributes.
 */
function styleDDSLayer(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Set the style function
  datasetLayer.style = (params) => {
    // Access attributes defined in your KML/Dataset
    const featureAttributes = params.feature.datasetAttributes;

    // Read style values from attributes, with fallback defaults
    const fillColor = featureAttributes['background_color'] || '#4285F4';
    const fillOpacity = parseFloat(featureAttributes['opacity']) || 0.5;
    const strokeColor = featureAttributes['border_color'] || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: fillOpacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
    };
  };
}

Weitere Informationen zum Implementieren von Interaktionen und Stilen finden Sie in der Übersicht über datengestützte Stile für Datasets und in der Datasets API für dynamische Daten.

Empfehlung für die Migration: Clientseitiges Rendering mit GeoJSON

Entwicklern, die von KmlLayer zur clientseitigen Darstellung mit GeoJSON migrieren, empfiehlt die Google Maps Platform einen Migrationspfad, bei dem das Datenformat konvertiert und die Datenebene verwendet wird, um Features direkt im Browser darzustellen und zu gestalten.

Das clientseitige Rendern mit der Datenschicht bietet eine sehr flexible Möglichkeit, geografische Daten darzustellen. Im Gegensatz zu KmlLayer, das auf den Servern von Google gerendert wird, können Sie mit der Datenschicht mit Funktionen als Standard-JavaScript-Objekte interagieren. Bei großen Datasets sollten Sie jedoch die serverseitige Verarbeitung und das serverseitige Rendern Ihrer Daten bevorzugen, z. B. mit dem datengesteuerten Styling für Datasets.

1. KML in GeoJSON konvertieren

Im ersten Schritt müssen Sie Ihre KML-Dateien in GeoJSON konvertieren. Dazu können Sie verschiedene gängige Open-Source-Tools verwenden:

  • ogr2ogr: Dieses leistungsstarke Befehlszeilentool ist Teil der GDAL-Suite und kann zwischen vielen Vektorformaten konvertieren.
ogr2ogr -f GeoJSON output.json input.kml
  • togeojson: Ein kleines, gut getestetes Tool, das speziell für die Konvertierung von KML und GPX in GeoJSON entwickelt wurde.
togeojson input.kml > output.json

2. Darstellungsbereich auf die Daten festlegen

Während KmlLayer automatisch schwenkt und zoomt, um den Datenstandort zu zeigen, geschieht dies beim Datenlayer nicht. Wenn Sie den Darstellungsbereich an Ihre GeoJSON-Daten anpassen möchten, müssen Sie den Begrenzungsrahmen manuell berechnen und map.fitBounds() aufrufen.

3. Stile aus Feature-Attributen

In der Datenebene können Sie eine style-Funktion definieren, mit der Attribute (Eigenschaften) direkt aus jedem GeoJSON-Element gelesen werden, um das Erscheinungsbild des Elements zu bestimmen.

Beispiel: Formatierungsfunktion und Anpassung des Viewports

Im folgenden Beispiel wird gezeigt, wie Sie GeoJSON-Daten laden, die Grenzen berechnen, um den Darstellungsbereich festzulegen, und Elemente anhand ihrer Attribute gestalten:

/**
 * Migration example: Loading GeoJSON, fitting viewport, and styling from attributes.
 */
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -28, lng: 137 },
  });

  // Load the GeoJSON data
  map.data.loadGeoJson('path/to/your/data.json', null, (features) => {
    // Adjust viewport to show all loaded features
    const bounds = new google.maps.LatLngBounds();
    features.forEach((feature) => {
      feature.getGeometry().forEachLatLng((latlng) => {
        bounds.extend(latlng);
      });
    });
    map.fitBounds(bounds);
  });

  // Set the style function to read from GeoJSON properties
  map.data.setStyle((feature) => {
    // Access attributes defined in your GeoJSON properties
    const fillColor = feature.getProperty('background_color') || '#4285F4';
    const opacity = parseFloat(feature.getProperty('opacity')) || 0.5;
    const strokeColor = feature.getProperty('border_color') || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: opacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
      visible: true
    };
  });
}

Weitere Informationen zur Verwendung der Datenschicht finden Sie in der Dokumentation zum Importieren von GeoJSON in Maps.

Migrationspfad: Clientseitiges Rendering mit Drittanbieterbibliotheken

Entwickler, die nach anderen Alternativen zu KmlLayer suchen, können auf mehrere von der Community verwaltete Bibliotheken zurückgreifen, mit denen KML-Daten in der Google Maps Platform JavaScript API gerendert werden.

1. deck.gl

deck.gl ist ein leistungsstarkes WebGL-gestütztes Visualisierungsframework. Es kann durch seine GoogleMapsOverlay und GeoJsonLayer als nahezu direkter Ersatz für das KML-Rendering verwendet werden.

  • Canvas-Anforderung:Damit Sie deck.gl effektiv nutzen können, müssen Sie Ihre Karte in den Vektorkartentyp konvertieren, der mit seinen WebGL-Renderingfunktionen in einem Canvas-Element gerendert wird.
  • KML-Unterstützung:Das Parsen von Geometrien wird von @loaders.gl/kml übernommen, das KML in GeoJSON konvertiert. Beachten Sie, dass für einige KML-Funktionen wie komplexe Stile, Symbole und NetworkLinks möglicherweise eine zusätzliche manuelle Implementierung erforderlich ist.
  • Dokumentation:deck.gl-Dokumentation | loaders.gl KML Loader.
  • Beispiele:
    • Im deckgl-kml-updated-Beispiel im Google Maps-GitHub-Repository wird gezeigt, wie Sie mit deck.gl KML-Daten rendern, die in Echtzeit aktualisiert werden.
    • Im Beispiel deckgl-kml wird gezeigt, wie Sie mit deck.gl KML-Daten rendern.

2. geoxml3

geoxml3 ist ein KML-Prozessor, der speziell für die Google Maps JavaScript API v3 entwickelt wurde. Sie parst KML lokal im Browser und rendert die Daten als Standardobjekte der Google Maps API wie Markierungen, Polylinien und Polygone.

  • Unterstützung von Standardkarten:Im Gegensatz zu WebGL-basierten Lösungen funktioniert geoxml3 mit Standardkarten der Google Maps JavaScript API v3, ohne dass ein bestimmter Rendermodus erforderlich ist.
  • Einschränkungen:
    • Eingeschränkte KMZ-Unterstützung:Die Bibliothek unterstützt KMZ-Dateien nicht vollständig. Das Entzippen von KMZ-Archiven erfordert in der Regel die Integration zusätzlicher Drittanbieterskripts wie ZipFile.complete.js.
    • Nicht unterstützte Elemente:Funktionen wie 3D-Geometrien, komplexe Labels und bestimmte neuere KML-Elemente werden nicht unterstützt.
  • Dokumentation:GitHub-Repository für geoxml3.

KML-Datei mit interaktiven Elementen

Migrationsempfehlung: Datengestützte Stile für Datasets

Entwickler, die von KmlLayer zu datengestützten Stilen (Data-driven styling, DDS) für Datasets migrieren, erfahren in dieser Anleitung, wie sie von automatischen KML-Interaktionen zu benutzerdefinierten, leistungsstarken Interaktionen wie Mausklicks und Hover wechseln können.

Ersteinrichtung

Bevor Sie Interaktionen implementieren, müssen Sie die Einrichtungsanleitung unter KML-Migration: Vektordaten befolgt haben:

  • Karten-ID:Konfigurieren Sie eine Karten-ID für den Typ Vektorkarte.
  • Hochladen:Laden Sie Ihre KML-Daten in die Google Cloud Console hoch, um eine Dataset-ID zu erhalten.
  • Ebenenzugriff:Verwenden Sie map.getDatasetFeatureLayer(datasetId), um auf die interaktive Ebene zuzugreifen.

1. Interaktionsereignisse verarbeiten

In KmlLayer werden Klicks auf Funktionen automatisch von der API verarbeitet, um ein Infofenster einzublenden. Bei DDS für Datasets müssen Sie Listener für Mausereignisse in der Dataset-Ebene manuell registrieren.

  • click:Wird ausgelöst, wenn ein Nutzer auf eine Funktion klickt.
  • mousemove:Wird ausgelöst, wenn der Cursor über ein Element bewegt wird. Das ist nützlich für Hover-Effekte.

2. Dynamische Gestaltung (Hover-Effekt)

Da DDS-Stile global auf die Ebene angewendet werden, sollten Sie eine Statusvariable verwenden, um zu verfolgen, mit welchem Feature interagiert wird, und den Stil noch einmal anwenden.

let currentFeatureId = null;

function initInteraction(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Apply the style function
  datasetLayer.style = (params) => {
    const isHovered = params.feature.datasetAttributes['id'] === currentFeatureId;
    return {
      strokeColor: 'green',
      strokeWeight: isHovered ? 4.0 : 2.0, // Bold border on hover
      fillColor: 'green',
      fillOpacity: isHovered ? 0.5 : 0.3,
    };
  };

  // Add interaction listeners
  datasetLayer.addListener('mousemove', (event) => {
    if (event.features.length > 0) {
      currentFeatureId = event.features[0].datasetAttributes['id'];
      datasetLayer.style = datasetLayer.style; // Re-apply style to reflect changes
    }
  });

  // Clear hover state when the mouse leaves the features
  map.addListener('mousemove', () => {
    if (currentFeatureId !== null) {
      currentFeatureId = null;
      datasetLayer.style = datasetLayer.style;
    }
  });
}

3. HTML aus dem Attribut description anzeigen

In KML enthält das <description>-Tag häufig HTML-Code für das Standardinfofenster. Wenn diese Daten als Dataset importiert werden, wird description zu einem Attribut des Features. Um ihn zu rendern, übergeben Sie den String direkt an ein Standard-google.maps.InfoWindow.

const infoWindow = new google.maps.InfoWindow();

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const feature = event.features[0];
    // Access the HTML description attribute
    const htmlContent = feature.datasetAttributes['description'];

    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. Benutzerdefiniertes Infofenster mit ExtendedData

Wenn in Ihrer KML-Datei <ExtendedData> zum Speichern benutzerdefinierter Name/Wert-Paare verwendet wird, werden diese datasetAttributes zugeordnet. Sie können diese Attribute durchlaufen, um eine benutzerdefinierte HTML-Anzeige zu erstellen.

function createCustomContent(feature) {
  const attributes = feature.datasetAttributes;
  const container = document.createElement("div");
  container.style.padding = "10px";
  container.innerHTML = "<h3>Feature Details</h3><dl></dl>";

  const dl = container.querySelector("dl");

  // Iterate through all data attributes imported from KML ExtendedData
  for (const key in attributes) {
    const dt = document.createElement("dt");
    dt.style.fontWeight = "bold";
    dt.textContent = key;

    const dd = document.createElement("dd");
    dd.textContent = attributes[key];

    dl.appendChild(dt);
    dl.appendChild(dd);
  }
  return container;
}

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const content = createCustomContent(event.features[0]);
    infoWindow.setContent(content);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

Weitere Informationen zu erweiterten Visualisierungstechniken finden Sie in der Entwicklerdokumentation zum Formatieren von Datenfunktionen.

Empfehlung für die Migration: Clientseitiges Rendering mit GeoJSON

Dieser Leitfaden richtet sich an Entwickler, die von KmlLayer zur clientseitigen Darstellung mit GeoJSON und der Datenebene migrieren. Er beschreibt, wie Sie von automatischen KML-Interaktionen zu benutzerdefinierten, ereignisgesteuerten Interaktionen und dynamischem Styling wechseln.

Ersteinrichtung

Bevor Sie Interaktionen implementieren, müssen Sie Ihre KML-Daten in GeoJSON konvertieren und in die Datenschicht laden. Weitere Informationen zur Verwendung von Tools wie ogr2ogr oder togeojson und zur Initialisierung der Karte mit map.data.loadGeoJson() finden Sie im Leitfaden Migrationsempfehlung: Clientseitiges Rendern mit GeoJSON.

1. Automatische und manuelle Interaktionen

Ein wichtiger Unterschied zwischen diesen Ebenen besteht darin, wie sie Nutzereingaben verarbeiten:

  • KmlLayer: Verarbeitet automatisch Klicks auf Elemente und zeigt ein InfoWindow mit den KML-- und -Daten an.
  • Data Layer (Datenschicht): InfoWindow-Objekte werden nicht automatisch angezeigt. Sie müssen Ereignis-Listener manuell hinzufügen, um Nutzerinteraktionen zu erfassen, und Code schreiben, um Daten darzustellen.

2. Interaktionsereignisse verarbeiten

Wenn Sie GeoJSON-Features interaktiv gestalten möchten, verwenden Sie die Methode addListener() für das map.data-Objekt. Häufige Ereignisse:

  • click: Wird verwendet, um Infofenster oder Auswahllogik auszulösen.
  • mouseover / mouseout: Wird für Hover-Effekte und Hervorhebungen verwendet.

3. HTML-Beschreibungen in einem Infofenster anzeigen

Wenn KML in GeoJSON konvertiert wird, wird das <description>-Tag (das häufig HTML enthält) in der Regel dem Attribut description zugeordnet. Mit feature.getProperty('description') können Sie diesen String abrufen und in einem Standard-google.maps.InfoWindow rendern.

const infoWindow = new google.maps.InfoWindow();

// Handle clicks to show the HTML description
map.data.addListener('click', (event) => {
  // Access the 'description' property from the GeoJSON feature
  const htmlContent = event.feature.getProperty('description');

  if (htmlContent) {
    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. Benutzerdefinierte Infofenster und ExtendedData

Wenn in Ihrer ursprünglichen KML-Datei <ExtendedData> verwendet wurde, werden diese Name/Wert-Paare in GeoJSON-Attribute konvertiert. Da die Datenschicht keine Standard-Benutzeroberfläche für diese Elemente hat, müssen Sie ein benutzerdefiniertes InfoWindow implementieren, um sie zu durchlaufen und anzuzeigen.

Sie können mit event.feature.getProperty('attribute_name') auf diese Attribute zugreifen und einen benutzerdefinierten HTML-String oder ein DOM-Element erstellen, das an die Methode infoWindow.setContent() übergeben wird.

5. Dynamische Gestaltung (Hover-Effekte)

Mit der Datenschicht können Sie die Formatierung von Elementen programmatisch als Reaktion auf Ereignisse aktualisieren. Mit overrideStyle() können Sie das Aussehen eines Elements vorübergehend ändern, z.B. beim Hovern mit der Maus, und mit revertStyle() kehren Sie zum globalen Stil zurück.

// Set a base style for all features
map.data.setStyle({
  fillColor: 'blue',
  strokeWeight: 1
});

// Highlight feature on mouseover
map.data.addListener('mouseover', (event) => {
  map.data.revertStyle(); // Clear previous highlights
  map.data.overrideStyle(event.feature, {strokeWeight: 8});
});

// Revert style on mouseout
map.data.addListener('mouseout', (event) => {
  map.data.revertStyle();
});

Weitere Informationen zur Implementierung finden Sie in der Dokumentation zu Datenschicht: Ereignisverarbeitung und Datenschicht: Dynamisches Styling.

Migrationspfad: Clientseitiges Rendering mit Drittanbieterbibliotheken

Für Entwickler, die von KmlLayer zu Drittanbieterlösungen migrieren, konzentriert sich dieser Leitfaden auf die Verarbeitung interaktiver Daten wie Mausklicks und dynamischer Ereignisse mit deck.gl und geoxml3.

Ersteinrichtung

Bevor Sie Interaktionen implementieren, müssen Sie die Einrichtungsschritte aus dem Leitfaden Migrationspfad: Clientseitiges Rendering mit Drittanbieterbibliotheken ausführen. Dazu zählen:

  • deck.gl: Konvertieren Sie Ihre Karte, damit der Vektorkartentyp verwendet wird (Canvas-Anforderung).
  • geoxml3: Die Bibliotheksskripts werden von Ihrem eigenen Host bereitgestellt und Cross-Origin Resource Sharing (CORS) wird verwaltet.

1. Interaktive Daten mit deck.gl

deck.gl unterstützt KML als direktes Eingabeformat und verarbeitet automatisch Funktionen wie Klicks basierend auf den in der KML-Datei bereitgestellten Daten.

  • KMLLoader-Verarbeitung: Mit dem @loaders.gl/kml-Modul werden Geometrie und Eigenschaften in ein Format geparst, das von deck.gl verwendet wird, um Interaktionsereignisse nativ auszulösen.
  • Funktionsklicks: Wenn auf eine Funktion geklickt wird, kann deck.gl das Ereignis erfassen und zugehörige Metadaten wie <name> oder <description> anzeigen.
  • Beispiel: Im Beispiel deckgl-kml-updated wird das KML-Rendering in Echtzeit demonstriert. Wenn Sie den Mauszeiger auf Erdbebenmarkierungen bewegen, werden detaillierte Ereignisinformationen angezeigt.

2. Interaktive Daten mit geoxml3

geoxml3 parst das KML lokal im Browser, extrahiert Stilinformationen und generiert Standardobjekte der Google Maps API, die ihre Interaktivität beibehalten.

  • Native Style Extraction (Extrahieren von nativen Stilen): Die Bibliothek ruft <Style>- und <StyleMap>-Elemente aus dem KML ab, um sie auf die generierten Markierungen, Polylinien und Polygone anzuwenden.
  • Klick-Handler: Standardmäßig stellt geoxml3 Klick-Handler für diese Objekte bereit. Sie können auch benutzerdefinierte Callback-Funktionen (createMarker, createOverlay) bei der Parser-Instanziierung definieren, um Ihre eigene Auswahl- oder Seitenleistenlogik zu implementieren.
  • Beispiel:In diesem Beispiel wird gezeigt, wie Sie mit geoxml3 KML rendern können. Dabei werden Anpassungen wie Kreismarkierungen mit Interaktion verwendet. Wenn Sie beispielsweise auf die Markierungen klicken, werden Informationen zu Erdbeben angezeigt.
  • Nutzungsmuster:
var myParser = new geoXML3.parser({
  map: map,
  processStyles: true, // Automatically handle KML styles
  afterParse: function(doc) {
    // Code to run after the KML is fully parsed
  }
});
myParser.parse('interactive_data.kml');

KML-Datei mit Bildern

Für Entwickler, die KmlLayer verwenden, um Bilder wie Karten mit aus Satellitendaten abgeleiteten Informationen, Wettervorhersagen oder historischen Blaupausen anzuzeigen, werden in diesem Leitfaden die Migrationspfade zu GroundOverlays oder Drittanbieter-Parsern beschrieben.

Migrationsempfehlung: Maps JavaScript API GroundOverlay

Für die Migration von Bildern wird die Verwendung der Klasse google.maps.GroundOverlay empfohlen. So können Sie ein Bild direkt in Ihrem Code an bestimmten geografischen Koordinaten auf der Karte platzieren.

1. Implementierung

Anstatt sich auf eine KML-Datei zu verlassen, um die Grenzen zu definieren, geben Sie die Bild-URL und ein LatLngBounds-Objekt an, das das Rechteck auf der Karte darstellt.

  • Dokumentation: Leitfaden für Boden-Overlays.
  • Bildvorbereitung: Wenn Ihr Bild georeferenziert ist, aber nicht die richtige Projektion (EPSG:4326) hat, können Sie das Open-Source-Tool gdalwarp verwenden, um das Bild für die Verwendung mit der Maps JavaScript API zu verzerren.
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

Migrationspfad: Bibliotheken von Drittanbietern verwenden

Wenn Sie Ihre Daten im KML-Format speichern müssen, können Sie mit Drittanbieterbibliotheken wie geoxml3 oder deck.gl Bild-Overlays rendern.

Haftungsausschluss:Diese Drittanbieterlösungen werden nicht von Google unterstützt. Sie wurden jedoch getestet und sollten für die meisten Anwendungsfälle funktionieren.

1. geoxml3

geoxml3 ist eine gute Option, um einfache GroundOverlay-Elemente lokal im Browser zu parsen und in Google Maps API-Objekte zu konvertieren.

Beispiel für die Verwendung:

const geoXmlParser = new geoXML3.parser({
    map: map,
    afterParse: function(doc) {
        console.log("Parsing complete. Number of documents: " + doc.length);
        const bounds = doc[0].gbounds;
        if (bounds && !bounds.isEmpty()) {
           map.fitBounds(bounds);
        }
    },
    createOverlay: function(groundOverlayData) {
        // Extract bounds and URL from parsed KML data
        const imageUrl = groundOverlayData.icon.href;
        const imageBounds = {
            north: parseFloat(groundOverlayData.latLonBox.north),
            south: parseFloat(groundOverlayData.latLonBox.south),
            east: parseFloat(groundOverlayData.latLonBox.east),
            west: parseFloat(groundOverlayData.latLonBox.west)
        };

        // Create the Google Maps GroundOverlay
        const nativeOverlay = new google.maps.GroundOverlay(imageUrl, imageBounds);
        nativeOverlay.setMap(map);
    }
});
geoXmlParser.parse('your_file.kml');

2. deck.gl

Der Standard-GeoJsonLayer von deck.gl verarbeitet Vektordaten, kann aber auch GroundOverlays unterstützen. Dazu ist eine manuelle Implementierung mit dem BitmapLayer erforderlich.

Bei diesem Ansatz wird KMLLoader verwendet, um die Datei zu parsen. Anschließend wird explizit ein BitmapLayer mit der Bild-URL und den aus den KML-Daten extrahierten Koordinaten definiert.

  • Voraussetzung:Für die Verwendung von deck.gl ist der Kartentyp Vektorkarte erforderlich.
  • Dokumentation:deck.gl Bitmap Layer

Erweiterter Anwendungsfall: Kacheln von Pyramiden mit gdal2tiles

Bei komplexen KML-Dateien mit Bildkachelpyramiden ist die Migration schwieriger und erfordert das Extrahieren der Bilddaten.

  • Tool: Mit gdal2tiles können Daten aus einer KMZ-Pyramide extrahiert und Standardcode für die Maps JavaScript API generiert werden, um die Kacheln anzuzeigen. Das Endergebnis muss möglicherweise manuell angepasst werden, damit es in eine vorhandene Karte eingefügt werden kann.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

Für die Verarbeitung von KML-Dateien mit Netzwerklinks ist eine Umstellung von der automatischen, cloudseitigen Abrufung von KmlLayer auf explizitere Strategien zur Datenverwaltung erforderlich.

Unterstützte Lösung: Datengestützte Stile für Datasets

Da Google Maps Platform-Datasets <NetworkLink>-Elemente nicht nativ parsen, müssen Sie eine Migrationsstrategie basierend auf Ihrer Datenstruktur auswählen:

  • Strategie A: Separate Datasets (am besten für benutzergesteuerte Ebenen): Laden Sie jede KML-Datei, die zuvor ein Netzwerk-Link war, als eigenes Dataset in die Google Cloud Console hoch. Anschließend können Sie mit JavaScript diese Ebenen bei Bedarf dynamisch laden und anzeigen, indem Sie map.getDatasetFeatureLayer(datasetId) aufrufen und die Sichtbarkeit oder den Stil anpassen.
  • Strategie B: Reduzierte KML-Datei (am besten für die leistungsstarke Darstellung) Kombinieren Sie alle Features aus Ihren verschiedenen netzwerkgebundenen Dateien in einer einzigen, umfassenden KML-Datei, bevor Sie sie als Dataset hochladen. Anschließend können Sie dynamische Formatierung basierend auf Attributen von Elementen verwenden, um bestimmte Datenteilmengen im Handumdrehen zu filtern und darzustellen.

Dynamische Daten aktualisieren:Wenn Sie das automatische Aktualisieren von Netzwerklinks simulieren möchten, können Sie die Datasets API verwenden, um bei jeder Änderung der Quelldaten programmatisch eine neue Version Ihres Datasets hochzuladen.

Open-Source-Lösungen: deck.gl und geoxml3

Weder deck.gl noch geoxml3 bieten eine robuste Unterstützung für das Parsen und automatische Abrufen von KML-<NetworkLink>-Elementen.

deck.gl

deck.gl verwendet die KMLLoader (basierend auf togeojson), die NetworkLinks ausdrücklich nicht unterstützt.

  • Warum ist das keine gute Lösung? Der Parser ist als synchroner, unkomplizierter Konverter konzipiert, der keine eigenen Netzwerkanfragen stellt, um Zuverlässigkeit und Einfachheit zu gewährleisten. Wenn Ihre Anwendung auf KML-Dateien angewiesen ist, die auf mehrere andere URLs verweisen, werden diese von deck.gl nicht automatisch aufgelöst.

geoxml3

geoxml3 wurde zwar entwickelt, um KML für die Maps JS API zu parsen, die Unterstützung für Netzwerklinks ist jedoch experimentell und wird nicht gewartet.

  • Warum ist das keine gute Lösung? Die Funktion ist nur in einem bestimmten „network_link“-Zweig vorhanden, der alt und nicht gut getestet ist. Die Verwendung für die Migration von Produktionsdaten wird nicht empfohlen, da komplexe Linkstrukturen oder moderne Sicherheitsanforderungen wie CORS möglicherweise nicht berücksichtigt werden.

Zusammenfassende Empfehlung

Für eine zuverlässige Migration sollten Entwickler Drittanbieter-Parser für Dateien mit Netzwerklinks vermeiden und stattdessen die Logik zum Abrufen von Daten mit der Datasets API neu erstellen. So werden Ihre Daten sicher in der Google Maps Platform-Infrastruktur verwaltet, anstatt auf nicht gewartete clientseitige Parser angewiesen zu sein.

Bildschirm-Overlays mit KML anzeigen

Für Entwickler, die von KmlLayer zu modernen Alternativen wie datengestützten Stilen (Data-driven Styling, DDS) migrieren, ist es wichtig zu beachten, dass Bildschirm-Overlays in Datasets nicht unterstützt werden. Wenn Sie dieselbe Wirkung erzielen möchten, indem Sie statische Bilder, Logos oder Legenden über der Karte anzeigen, müssen Sie mit der Maps JavaScript API benutzerdefinierte Steuerelemente erstellen.

1. Worauf Sie in Ihrer KML-Datei achten sollten

Wenn Sie ein entsprechendes benutzerdefiniertes Steuerelement erstellen möchten, sehen Sie sich das <ScreenOverlay>-Element in Ihrer KML-Datei an und suchen Sie nach den folgenden wichtigen Attributen:

  • <Icon>&lt;href>: Die URL des Bildes, das Sie anzeigen möchten.
  • <screenXY>: Hiermit wird festgelegt, wo das Overlay auf dem Bildschirm positioniert wird.
    • x=0, y=1 (Brüche) entspricht Oben links.
    • x=1, y=1 entspricht Oben rechts.
    • x=0, y=0 entspricht Unten links.
    • x=1, y=0 entspricht Rechts unten.
  • <size>: Definiert die Breite und Höhe des Overlays.
  • <rotation>: Gibt an, ob das Bild gedreht werden soll.

2. Implementierung: Benutzerdefiniertes Steuerelement erstellen

Ein benutzerdefiniertes Steuerelement ist im Grunde ein Standard-HTML-Element (z. B. <div> oder <img>), das Sie an einer der vordefinierten Positionen auf der Karte platzieren.

KML-Positionen ControlPosition zuordnen

In der Maps JavaScript API wird die ControlPosition-Enumeration verwendet, um Steuerelemente zu verankern. In der folgenden Tabelle finden Sie die entsprechenden JS API-Konstanten für Ihre KML-<screenXY>-Elemente:

KML-Position (screenXY) JS API ControlPosition
Oben links (x:0, y:1) TOP_LEFT (Legacy) oder BLOCK_START_INLINE_START (Logisch)
Oben rechts (x:1, y:1) TOP_RIGHT oder BLOCK_START_INLINE_END
Unten links (x:0, y:0) BOTTOM_LEFT oder BLOCK_END_INLINE_START
Unten rechts (x:1, y:0) BOTTOM_RIGHT oder BLOCK_END_INLINE_END

3. Beispiel für die Migration: Festes Logo-Overlay

Im folgenden Beispiel wird ein KML-ScreenOverlay-Logo im Top Right (oben rechts) der Karte simuliert.

CSS-Formatierung

Verwenden Sie CSS, um die Größe und das Aussehen des Overlays zu definieren.

#logo-control {
  padding: 10px;
  background-color: rgba(255, 255, 255, 0.8);
  margin: 10px;
  border-radius: 2px;
  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
}

#logo-control img {
  width: 150px; /* Equivalent to KML <size> */
  display: block;
}

JavaScript-Implementierung

Fügen Sie das Element dem Array map.controls hinzu.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 41.85, lng: -87.65 },
  });

  // 1. Create the container for the overlay
  const logoControlDiv = document.createElement("div");
  logoControlDiv.id = "logo-control";

  // 2. Create the image (KML <Icon>)
  const logoImage = document.createElement("img");
  logoImage.src = "https://example.com/logo.png";
  logoImage.alt = "Company Logo";

  logoControlDiv.appendChild(logoImage);

  // 3. Position the control (KML <screenXY>)
  // In this case, we use TOP_RIGHT
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(logoControlDiv);
}

Weitere Informationen