Ścieżki migracji KmlLayer

Wprowadzenie

Celem tego przewodnika jest omówienie najczęstszych zastosowań klasy KmlLayer i przedstawienie odpowiednich ścieżek migracji do alternatywnych implementacji. Te informacje są przeznaczone dla deweloperów, którzy muszą przejść z używania klasy KmlLayer ze względu na jej planowane wycofanie. Ostatnia wersja obsługująca KmlLayer to 3.65, która zostanie wycofana w maju 2027 r.

Ścieżka migracji zależy od tego, jak używasz warstwy KmlLayer:

plik KML do określania stylu informacji o granicy lub obszarze zainteresowań;

Deweloperom, którzy używają KmlLayer do wyświetlania lub stylowania granic administracyjnych, np. do wyróżniania konkretnego kraju, stanu lub miejscowości, Google Maps Platform zaleca przejście na styl oparty na danych (DDS) dla granic.

Rekomendacja dotycząca migracji: styl oparty na danych dla granic

Stylizacja granic oparta na danych zapewnia bezpośredni dostęp do wielokątów granic administracyjnych Google, co umożliwia stosowanie niestandardowych stylów (wypełnienia i obrysu) w tych regionach bez konieczności hostowania zewnętrznych plików KML ani zarządzania nimi.

Dostępny FeatureType

Obszary administracyjne są podzielone na kategorie według funkcji i uporządkowane według poziomów. W przypadku stylizowania obsługiwane są te typy elementów:

  • COUNTRY: krajowy podmiot polityczny.
  • ADMINISTRATIVE_AREA_LEVEL_1: jednostka administracyjna pierwszego rzędu poniżej poziomu kraju (np. stany w Stanach Zjednoczonych).
  • ADMINISTRATIVE_AREA_LEVEL_2: jednostka administracyjna drugiego rzędu poniżej poziomu kraju (np. hrabstwa w Stanach Zjednoczonych).
  • LOCALITY: miasto lub miejscowość o statusie korporacyjnym.
  • POSTAL_CODE: kody pocztowe używane w przypadku poczty.
  • SCHOOL_DISTRICT: okręgi szkolne obejmujące szkoły podstawowe i średnie.

Zobacz zasięg granic w regionach, w których te typy funkcji są dostępne.

Jak wyróżnić obszar

Aby zastosować styl do konkretnego regionu, musisz kierować na niego reklamy za pomocą identyfikatora miejsca.

  • Konfiguracja: musisz użyć identyfikatora mapy skonfigurowanego dla typu mapy JavaScript wektorowej i włączyć warstwę mapy dostępną w konsoli Google Cloud.
  • Implementacja: użyj przykładowego kodu Style a boundary polygon (Stylizowanie wielokąta granicznego).

Ograniczanie przesuwania do obszaru

Aby uniemożliwić użytkownikom poruszanie się poza ramką ograniczającą wyróżnionego obszaru, możesz użyć opcji restriction w MapOptions.

Obiekt restriction definiuje latLngBounds, który ogranicza widoczny obszar mapy. Więcej informacji o tym, jak działa to ograniczenie, znajdziesz w dokumentacji.

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

Implementacja migracji podsumowującej

Oto pełny przykład użycia stylów opartych na danych w przypadku granic i ograniczenia regionu, aby skupić mapę na określonym obszarze.

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

plik KML z danymi wektorowymi (punkty, polilinie, granice, wielokąty);

Rekomendacja dotycząca migracji: styl oparty na danych w przypadku zbiorów danych

Aby wyświetlać publicznie dostępne dane geograficzne i zyskać większą kontrolę nad stylem i wydajnością, Google zaleca skorzystanie z poniższej ścieżki.

Style oparte na danych w przypadku zbiorów danych umożliwiają przesyłanie własnych danych geoprzestrzennych (KML, GeoJSON lub CSV), stosowanie niestandardowych stylów na podstawie atrybutów danych i wyświetlanie elementów na mapach wektorowych.

1. Konfiguracja i przesyłanie

W przeciwieństwie do KmlLayer, która pobiera adres URL w czasie działania, usługa DDS wymaga hostowania danych jako zbioru danych w konsoli Google Cloud.

  • Utwórz identyfikator mapy: użyj identyfikatora mapy skonfigurowanego dla typu Mapa wektorowa.
  • Prześlij zbiór danych: prześlij plik KML do konsoli Google Cloud, aby wygenerować unikalny identyfikator zbioru danych. Więcej informacji znajdziesz w pełnej dokumentacji zarządzania zbiorami danych w Mapach.
  • Wyświetlanie zbioru danych: po utworzeniu identyfikatora zbioru danych musisz powiązać zbiór danych ze stylem mapy i identyfikatorem mapy. Następnie użyjesz identyfikatora zbioru danych, aby wyświetlić dane na mapie. Więcej informacji znajdziesz w pełnej dokumentacji dodawania zbioru danych do mapy.
  • Pamiętaj o wymaganiach dotyczących formatu KML w przypadku zbiorów danych, jeśli zdecydujesz się zaimportować dane z tego formatu.

2. Ustawianie widocznego obszaru na dane

KmlLayer domyślnie automatycznie przesuwa i powiększa widok do lokalizacji danych. W przypadku DDS dla zbiorów danych to zachowanie nie jest automatyczne i musi zostać zaimplementowane ręcznie.

  • Ograniczenia zakodowane na stałe: jeśli obszar danych jest statyczny, użyj opcji restriction w MapOptions, aby zablokować widok w określonych granicach.
  • Dynamiczne powiększanie: aby dynamicznie ustawić obszar widoku, możesz użyć map.fitBounds() z ramką ograniczającą zbioru danych.

3. Stylizacja na podstawie atrybutów funkcji

Pliki KML często zawierają informacje o stylu (np. kolory), których DDS nie stosuje automatycznie. Musisz utworzyć funkcję stylu po stronie klienta, która odczytuje atrybuty z elementów zbioru danych, aby zastosować kolory i krycie. Szczegółowe informacje znajdziesz w dokumentacji dla programistów na temat stylizowania danych.

Przykład: funkcja stylizacji z użyciem atrybutów

Ten przykład pokazuje, jak utworzyć funkcję stylu, która odczytuje atrybuty background_color i opacity bezpośrednio z przesłanego zbioru danych:

/**
 * 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,
    };
  };
}

Więcej informacji o wdrażaniu interakcji i stylizacji znajdziesz w artykule o stylu opartym na danych dla zbiorów danych – przegląd i w dokumentacji interfejsu Datasets API dotyczącej danych dynamicznych.

Zalecana migracja: renderowanie po stronie klienta z użyciem GeoJSON

Deweloperom, którzy przechodzą z KmlLayer na renderowanie po stronie klienta za pomocą GeoJSON, Google Maps Platform zaleca ścieżkę migracji, która obejmuje konwersję formatu danych i użycie warstwy danych do renderowania i stylizowania obiektów bezpośrednio w przeglądarce.

Renderowanie po stronie klienta za pomocą warstwy danych zapewnia bardzo elastyczny sposób wyświetlania danych geograficznych. W przeciwieństwie do KmlLayer, które jest renderowane na serwerach Google, warstwa danych umożliwia interakcję z funkcjami jako standardowymi obiektami JavaScriptu. Pamiętaj jednak, że w przypadku dużych zbiorów danych możesz preferować przetwarzanie i renderowanie danych po stronie serwera, np. za pomocą stylów opartych na danych w przypadku zbiorów danych.

1. Konwertowanie pliku KML na GeoJSON

Pierwszym krokiem jest przekonwertowanie plików KML na format GeoJSON. Możesz to zrobić za pomocą kilku popularnych narzędzi open source:

  • ogr2ogr to część pakietu GDAL. To zaawansowane narzędzie wiersza poleceń może konwertować wiele formatów wektorowych.
ogr2ogr -f GeoJSON output.json input.kml
  • togeojson: małe, dobrze przetestowane narzędzie zaprojektowane specjalnie do konwertowania plików KML i GPX na GeoJSON.
togeojson input.kml > output.json

2. Ustawianie widocznego obszaru na dane

Podczas gdy KmlLayer automatycznie przesuwa się i powiększa do lokalizacji danych, warstwa danych tego nie robi. Aby ustawić widoczny obszar tak, aby pasował do danych GeoJSON, musisz ręcznie obliczyć ramkę ograniczającą i wywołać funkcję map.fitBounds().

3. Stylizacja na podstawie atrybutów funkcji

W warstwie danych możesz zdefiniować stylefunkcję, która odczytuje atrybuty (właściwości) bezpośrednio z każdej funkcji GeoJSON, aby określić jej wygląd.

Przykład: funkcja stylizacji i dostosowanie obszaru wyświetlania

Ten przykład pokazuje, jak wczytać dane GeoJSON, obliczyć ich granice, aby ustawić widok, i określić styl elementów na podstawie ich atrybutów:

/**
 * 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
    };
  });
}

Więcej informacji o korzystaniu z warstwy danych znajdziesz w dokumentacji importowania GeoJSON do Map.

Ścieżka migracji: renderowanie po stronie klienta z bibliotekami innych firm

Deweloperzy, którzy szukają innych alternatyw dla KmlLayer, mogą skorzystać z kilku bibliotek utrzymywanych przez społeczność, które renderują dane KML w interfejsie JavaScript API Platformy Map Google.

1. deck.gl

deck.gl to wydajny framework wizualizacyjny oparty na WebGL. Może być używany jako niemal bezpośredni zamiennik renderowania KML za pomocą funkcji GoogleMapsOverlay i GeoJsonLayer.

  • Wymagania dotyczące obszaru roboczego: aby skutecznie korzystać z deck.gl, musisz przekonwertować mapę, aby używać typu mapy wektorowej (która jest renderowana w elemencie obszaru roboczego) z funkcjami renderowania WebGL.
  • Obsługa KML: analizowanie geometrii jest obsługiwane przez @loaders.gl/kml, który konwertuje KML na GeoJSON. Pamiętaj, że niektóre funkcje KML, takie jak złożone style, ikony i NetworkLink, mogą wymagać dodatkowej implementacji ręcznej.
  • Dokumentacja: Dokumentacja deck.gl | loaders.gl KML Loader.
  • Przykłady:
    • Przykładowy kod deckgl-kml-updated w repozytorium GitHub Google Maps pokazuje, jak używać biblioteki deck.gl do renderowania danych KML aktualizowanych w czasie rzeczywistym.
    • Przykład deckgl-kml pokazuje, jak używać deck.gl do renderowania danych KML.

2. geoxml3

geoxml3 to procesor KML zaprojektowany specjalnie dla interfejsu API JavaScript Map Google w wersji 3. Analizuje on pliki KML lokalnie w przeglądarce i renderuje dane jako standardowe obiekty interfejsu API Map Google, takie jak znaczniki, linie łamane i wielokąty.

  • Obsługa standardowych map: w przeciwieństwie do rozwiązań opartych na WebGL geoxml3 działa na standardowych mapach interfejsu Google Maps JS API w wersji 3 bez konieczności stosowania określonego trybu renderowania.
  • Zastrzeżenia:
    • Ograniczona obsługa KMZ: biblioteka nie obsługuje w pełni plików KMZ. Rozpakowywanie archiwów KMZ zwykle wymaga integracji z dodatkowymi skryptami innych firm, takimi jak ZipFile.complete.js.
    • Nieobsługiwane elementy: funkcje takie jak geometrie 3D, złożone etykiety i niektóre nowsze elementy KML nie są obsługiwane.
  • Dokumentacja: repozytorium geoxml3 w GitHub.

Plik KML z elementami interaktywnymi

Rekomendacja dotycząca migracji: styl oparty na danych w przypadku zbiorów danych

Deweloperom, którzy przechodzą z KmlLayer na stylizację opartą na danych (DDS) w przypadku zbiorów danych, ten przewodnik wyjaśnia, jak przejść od automatycznych interakcji KML do niestandardowych interakcji o wysokiej wydajności, takich jak kliknięcia myszą i najechanie kursorem.

Konfiguracja początkowa

Zanim zaimplementujesz interakcje, wykonaj czynności konfiguracyjne opisane w przewodniku Migracja KML: dane wektorowe:

  • Identyfikator mapy: skonfiguruj identyfikator mapy dla typu Mapa wektorowa.
  • Prześlij: prześlij dane KML do konsoli Google Cloud, aby uzyskać identyfikator zbioru danych.
  • Dostęp do warstwy: użyj przycisku map.getDatasetFeatureLayer(datasetId), aby uzyskać dostęp do warstwy interaktywnej.

1. Obsługa zdarzeń interakcji

W KmlLayer kliknięcia funkcji są obsługiwane automatycznie przez interfejs API, który wyświetla okno informacyjne. W przypadku DDS dla zbiorów danych musisz ręcznie zarejestrować detektory zdarzeń myszy w warstwie zbioru danych.

  • click: wywoływane, gdy użytkownik kliknie funkcję.
  • mousemove: uruchamiane, gdy kursor przesuwa się nad elementem, przydatne w przypadku efektów najechania.

2. Dynamiczne style (efekt najechania kursorem)

Style DDS są stosowane globalnie do warstwy, dlatego należy zachować zmienną stanu, aby śledzić, z którym elementem użytkownik wchodzi w interakcję, i ponownie zastosować styl.

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. Wyświetlanie kodu HTML z atrybutu description

W KML tag <description> często zawiera kod HTML domyślnego okna informacyjnego. Gdy te dane zostaną zaimportowane jako zbiór danych, description stanie się atrybutem obiektu. Aby go wyrenderować, przekaż ciąg znaków bezpośrednio do standardowego elementu 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. Niestandardowe okno informacji z ExtendedData

Jeśli plik KML zawiera element <ExtendedData> do przechowywania niestandardowych par nazwa/wartość, są one mapowane na element datasetAttributes. Możesz iterować te atrybuty, aby utworzyć niestandardową reklamę displayową HTML.

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

Bardziej zaawansowane techniki wizualizacji znajdziesz w dokumentacji dla deweloperów na temat stylizowania funkcji danych.

Zalecana migracja: renderowanie po stronie klienta z użyciem GeoJSON

Ten przewodnik jest przeznaczony dla deweloperów, którzy przechodzą z KmlLayer na renderowanie po stronie klienta za pomocą GeoJSON i warstwy danych. Wyjaśniamy w nim, jak przejść od automatycznych interakcji KML do niestandardowych interakcji opartych na zdarzeniach i dynamicznego stylu.

Konfiguracja początkowa

Przed wdrożeniem interakcji musisz przekonwertować dane KML na format GeoJSON i załadować je do warstwy danych. Szczegółowe informacje o korzystaniu z narzędzi takich jak ogr2ogr lub togeojson oraz o inicjowaniu mapy za pomocą map.data.loadGeoJson() znajdziesz w przewodniku Rekomendacja dotycząca migracji: renderowanie po stronie klienta za pomocą GeoJSON.

1. Interakcje automatyczne i ręczne

Główna różnica między tymi warstwami polega na sposobie obsługi danych wejściowych użytkownika:

  • KmlLayer: automatycznie obsługuje kliknięcia funkcji i wyświetla InfoWindow zawierający dane i  w formacie KML.
  • Warstwa danych: nie wyświetla automatycznie obiektów InfoWindow. Aby rejestrować interakcje użytkowników, musisz ręcznie dodać moduły nasłuchiwania zdarzeń i napisać kod do wyświetlania danych.

2. Obsługa zdarzeń interakcji

Aby umożliwić interakcję z obiektami GeoJSON, użyj metody addListener() na obiekcie map.data. Typowe zdarzenia to:

  • click: służy do wywoływania okien informacyjnych lub logiki wyboru.
  • mouseover / mouseout: służy do efektów najechania kursorem i wyróżniania.

3. Wyświetlanie opisów HTML w dymku informacyjnym

Gdy plik KML jest konwertowany na GeoJSON, tag <description> (który często zawiera kod HTML) jest zwykle mapowany na właściwość o nazwie description. Możesz użyć feature.getProperty('description'), aby pobrać ten ciąg tekstowy i wyświetlić go w standardowym tagu google.maps.InfoWindow.

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. Niestandardowe okna informacyjne i ExtendedData

Jeśli oryginalny plik KML zawierał element <ExtendedData>, te pary nazwa-wartość są konwertowane na właściwości GeoJSON. Warstwa danych nie ma domyślnego interfejsu do wyświetlania tych informacji, więc musisz zaimplementować niestandardowe okno informacyjne, aby je iterować i wyświetlać.

Dostęp do tych atrybutów możesz uzyskać za pomocą event.feature.getProperty('attribute_name') i utworzyć niestandardowy ciąg HTML lub element DOM, który zostanie przekazany do metody infoWindow.setContent().

5. Dynamiczne style (efekty najechania kursorem)

Warstwa danych umożliwia programistyczne aktualizowanie stylów funkcji w odpowiedzi na zdarzenia. Użyj overrideStyle(), aby tymczasowo zmienić wygląd elementu (np. po najechaniu kursorem), i revertStyle(), aby wrócić do stylu globalnego.

// 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();
});

Szczegółowe informacje o wdrażaniu znajdziesz w dokumentacji dotyczącej warstwy danych: obsługi zdarzeń i warstwy danych: dynamicznej stylizacji.

Ścieżka migracji: renderowanie po stronie klienta z bibliotekami innych firm

Ten przewodnik jest przeznaczony dla deweloperów, którzy przechodzą z KmlLayer na rozwiązania innych firm. Skupia się on na obsłudze danych interaktywnych, takich jak kliknięcia myszą i zdarzenia dynamiczne, za pomocą bibliotek deck.gl i geoxml3.

Konfiguracja początkowa

Przed wdrożeniem interakcji upewnij się, że wykonano czynności konfiguracyjne opisane w przewodniku Ścieżka migracji: renderowanie po stronie klienta z bibliotekami innych firm. Obejmuje to m.in.:

  • deck.gl: przekształcanie mapy w celu używania typu mapy wektorowej (wymagane jest użycie elementu canvas).
  • geoxml3 udostępnianie skryptów biblioteki z własnego hosta i zarządzanie mechanizmem CORS (współdzielenie zasobów pomiędzy serwerami z różnych domen).

1. Interaktywne dane z deck.gl

deck.gl obsługuje format KML jako bezpośredni format wejściowy i automatycznie obsługuje interakcje z funkcjami, takie jak kliknięcia, na podstawie danych podanych w pliku KML.

  • Obsługa KMLLoader: za pomocą modułu @loaders.gl/kml geometria i właściwości są analizowane i przekształcane do formatu, który deck.gl wykorzystuje do natywnego wywoływania zdarzeń interakcji.
  • Kliknięcia funkcji: gdy klikniesz funkcję, deck.gl może zarejestrować zdarzenie i wyświetlić powiązane metadane (np. <name> lub <description>).
  • Przykład: przykład deckgl-kml-updated pokazuje renderowanie plików KML w czasie rzeczywistym. Po najechaniu kursorem na znaczniki trzęsień ziemi wyświetlają się szczegółowe informacje o zdarzeniu.

2. Dane interaktywne z geoxml3

geoxml3 analizuje plik KML lokalnie w przeglądarce, wyodrębnia informacje o stylu i generuje standardowe obiekty interfejsu API Map Google, które zachowują interaktywność.

  • Wyodrębnianie stylu natywnego: biblioteka pobiera elementy <Style> i <StyleMap> z pliku KML, aby zastosować je do wygenerowanych znaczników, polilinii i wielokątów.
  • Moduły obsługi kliknięć: domyślnie geoxml3 udostępnia moduły obsługi kliknięć tych obiektów. Podczas tworzenia instancji analizatora możesz też zdefiniować niestandardowe funkcje wywołania zwrotnego (createMarker,createOverlay), aby zaimplementować własną logikę wyboru lub aktualizacje paska bocznego.
  • Przykład: ten przykład pokazuje, jak używać geoxml3 do renderowania KML z dostosowaniami, takimi jak znaczniki w kształcie okręgów z interakcjami, np. klikanie znaczników w celu wyświetlania informacji o trzęsieniach ziemi.
  • Wzorzec wykorzystania:
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');

Plik KML z obrazami

Dla deweloperów, którzy używają KmlLayer do wyświetlania obrazów, takich jak mapy z danymi pochodzącymi z satelitów, wzorce pogodowe czy historyczne plany, ten przewodnik zawiera informacje o ścieżkach migracji do GroundOverlays lub parserów innych firm.

Rekomendacja dotycząca migracji: nakładka GroundOverlay w Maps JavaScript API

Zalecana ścieżka migracji zdjęć to użycie klasy google.maps.GroundOverlay. Dzięki temu możesz umieścić obraz na mapie w określonych współrzędnych geograficznych bezpośrednio w kodzie.

1. Implementacja

Zamiast polegać na pliku KML w celu określenia granic, podajesz adres URL obrazu i obiekt LatLngBounds reprezentujący prostokąt na mapie.

  • Dokumentacja: Przewodnik po nakładkach na ziemię.
  • Przygotowanie obrazu: jeśli obraz jest georeferencyjny, ale nie ma prawidłowej projekcji (EPSG:4326), możesz użyć narzędzia open source gdalwarp, aby przekształcić obraz do użytku z interfejsem Maps JS API.
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

Ścieżka migracji: używanie bibliotek innych firm

Jeśli Twój proces wymaga przechowywania danych w formacie KML, możesz użyć bibliotek innych firm, takich jak geoxml3 lub deck.gl, do renderowania nakładek obrazów.

Wyłączenie odpowiedzialności: te rozwiązania innych firm nie są obsługiwane przez Google. Zostały one jednak przetestowane i powinny działać w większości przypadków.

1. geoxml3

geoxml3 to dobra opcja do lokalnego analizowania prostych elementów GroundOverlay w przeglądarce i przekształcania ich w obiekty interfejsu API Map Google.

Przykład użycia:

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

Standardowy GeoJsonLayer deck.gl obsługuje dane wektorowe, ale może też obsługiwać GroundOverlays w ramach ręcznej implementacji z użyciem BitmapLayer.

W tym podejściu wykorzystuje się KMLLoader do przeanalizowania pliku, a następnie jawnie definiuje się BitmapLayer z adresem URL obrazu i współrzędnymi wyodrębnionymi z danych KML.

Zaawansowany przypadek: piramidy kafelków z użyciem gdal2tiles

W przypadku złożonych plików KML zawierających piramidy kafelków obrazów migracja jest trudniejsza i wymaga wyodrębnienia danych obrazów.

  • Narzędzie: gdal2tiles może wyodrębniać dane z piramidy KMZ i generować standardowy kod Maps JavaScript API do wyświetlania kafelków. Pamiętaj, że wynik końcowy może wymagać ręcznej modyfikacji, aby można go było uwzględnić na istniejącej mapie.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

Obsługa plików KML z linkami do sieci wymaga przejścia z automatycznego pobierania po stronie chmury KmlLayer na bardziej jednoznaczne strategie zarządzania danymi.

Obsługiwane rozwiązanie: styl oparty na danych (DDS) w przypadku zbiorów danych

Zestawy danych w Google Maps Platform nie analizują natywnie elementów <NetworkLink>, dlatego musisz wybrać strategię migracji na podstawie struktury danych:

  • Strategia A: oddzielne zbiory danych (najlepsza w przypadku warstw kontrolowanych przez użytkownika): prześlij każdy plik KML, który wcześniej był linkiem sieciowym, jako osobny zbiór danych w konsoli Google Cloud. Następnie możesz użyć JavaScriptu, aby w razie potrzeby dynamicznie wczytywać i wyświetlać te warstwy, wywołując funkcję map.getDatasetFeatureLayer(datasetId) i dostosowując jej widoczność lub styl.
  • Strategia B. Spłaszczony plik KML (najlepsza w przypadku wyświetlania o wysokiej wydajności) Połącz wszystkie funkcje z różnych plików połączonych z siecią w jeden, kompleksowy plik KML, a następnie prześlij go jako zbiór danych. Następnie możesz użyć dynamicznego stylu opartego na atrybutach elementów, aby filtrować i wyświetlać w czasie rzeczywistym określone podzbiory danych.

Aktualizowanie danych dynamicznych: aby naśladować zachowanie „automatycznego odświeżania” linków sieciowych, użyj interfejsu Datasets API do programowego przesyłania nowej wersji zbioru danych za każdym razem, gdy zmienią się dane źródłowe.

Rozwiązania open source: deck.gl i geoxml3

Ani deck.gl, ani geoxml3 nie zapewniają solidnego wsparcia w zakresie analizowania i automatycznego pobierania elementów KML <NetworkLink>.

deck.gl

deck.gl korzysta z KMLLoader (opartego na togeojson), który nie obsługuje linków do sieci.

  • Dlaczego to nie jest dobre rozwiązanie: analizator składni został zaprojektowany jako synchroniczny, „bezproblemowy” konwerter, który nie wysyła własnych żądań sieciowych, aby zapewnić niezawodność i prostotę. Jeśli Twoja aplikacja korzysta z plików KML, które wskazują wiele innych adresów URL, deck.gl nie będzie ich automatycznie rozpoznawać.

geoxml3

Biblioteka geoxml3 została opracowana do analizowania plików KML na potrzeby interfejsu Maps JS API, ale jej obsługa linków sieciowych jest eksperymentalna i nie jest utrzymywana.

  • Dlaczego to nie jest dobre rozwiązanie: ta funkcja występuje tylko w określonej gałęzi „network_link”, która jest stara i nie została dobrze przetestowana. Używanie tego narzędzia do migracji danych produkcyjnych jest odradzane, ponieważ może ono nie obsługiwać złożonych struktur linków ani nowoczesnych wymagań dotyczących bezpieczeństwa, takich jak CORS.

Podsumowanie rekomendacji

Aby zapewnić niezawodną migrację, deweloperzy powinni unikać zewnętrznych analizatorów plików z linkami do sieci i zamiast tego odtworzyć logikę pobierania danych za pomocą interfejsu Datasets API. Dzięki temu Twoje dane są bezpiecznie zarządzane w infrastrukturze Platformy Google Maps, a nie za pomocą nieaktualizowanych parserów po stronie klienta.

Wyświetlanie nakładek ekranowych za pomocą KML

W przypadku deweloperów, którzy przechodzą z KmlLayer na nowoczesne alternatywy, takie jak stylizacja oparta na danych (DDS), ważne jest, aby pamiętać, że nakładki ekranowe nie są obsługiwane w zbiorach danych. Aby uzyskać ten sam efekt wyświetlania stałych obrazów, logo lub legend na mapie, musisz utworzyć niestandardowe elementy sterujące za pomocą interfejsu Maps JavaScript API.

1. Czego szukać w pliku KML

Aby utworzyć odpowiednik elementu Custom Control, sprawdź w pliku KML element <ScreenOverlay> pod kątem tych kluczowych atrybutów:

  • <Icon>&lt;href> – adres URL obrazu, który chcesz wyświetlać.
  • <screenXY>: określa, w którym miejscu ekranu znajduje się nakładka.
    • x=0, y=1 (ułamki) odpowiada górnemu lewemu.
    • x=1, y=1 odpowiada prawemu górnemu rogowi.
    • x=0, y=0 odpowiada lewemu dolnemu.
    • x=1, y=0 odpowiada prawemu dolnemu.
  • <size>: określa szerokość i wysokość nakładki.
  • <rotation>: wskazuje, czy obraz ma zostać obrócony.

2. Wdrażanie: tworzenie niestandardowego ustawienia

Kontrolka niestandardowa to w zasadzie standardowy element HTML (np. <div> lub <img>), który „wstawiasz” w jednym z wstępnie zdefiniowanych miejsc na mapie.

Mapowanie pozycji KML na ControlPosition

Interfejs Maps JavaScript API używa wyliczenia ControlPosition do zakotwiczania elementów sterujących. Skorzystaj z tabeli poniżej, aby przypisać do pliku KML <screenXY> odpowiednią stałą interfejsu JS API:

Pozycja KML (screenXY) JS API ControlPosition
Lewy górny róg (x:0, y:1) TOP_LEFT (starszy) lub BLOCK_START_INLINE_START (logiczny)
Prawy górny róg (x:1, y:1) TOP_RIGHT lub BLOCK_START_INLINE_END
Lewy dolny róg (x:0, y:0) BOTTOM_LEFT lub BLOCK_END_INLINE_START
Prawy dolny róg (x:1, y:0) BOTTOM_RIGHT lub BLOCK_END_INLINE_END

3. Przykład migracji: stała nakładka z logo

Poniższy przykład imituje logo KML ScreenOverlay umieszczone w prawym górnym rogu mapy.

Stylizacja CSS

Użyj CSS, aby określić rozmiar i wygląd „nakładki”.

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

Implementacja JavaScript

Dodaj element do tablicy map.controls.

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

Więcej informacji