Warstwy KML i GeoRSS

KmlLayer renderuje elementy KML i GeoRSS w nakładce kafelków interfejsu Maps JavaScript API.

Przegląd

Interfejs Maps JavaScript API obsługuje formaty danych KML i GeoRSS podczas wyświetlania informacji geograficznych. Te formaty danych są wyświetlane na mapie za pomocą obiektu KmlLayer, którego konstruktor wykorzystuje adres URL publicznie dostępnego pliku KML lub GeoRSS.

Uwaga: klasa KmlLayer, która generuje nakładki KML w interfejsie Maps JavaScript API, korzysta z usługi hostowanej przez Google do pobierania i analizowania plików KML na potrzeby renderowania. Dlatego można wyświetlać pliki KML tylko wtedy, gdy są przechowywane pod publicznie dostępnym adresem URL, który nie wymaga uwierzytelniania.

Jeśli potrzebujesz dostępu do plików prywatnych, szczegółowej kontroli nad pamięciami podręcznymi lub wysyłania widocznego obszaru przeglądarki do serwera danych geoprzestrzennych jako parametru zapytania, zalecamy używanie warstw danych zamiast KmlLayer. Spowoduje to przekierowanie przeglądarek użytkowników na bezpośrednie wysyłanie żądań zasobów do Twojego serwera WWW.

Interfejs Maps JavaScript API konwertuje podane dane geograficzne w formacie XML na format KML, który jest wyświetlany na mapie za pomocą nakładki kafelka interfejsu Maps JavaScript API. Ten plik KML wygląda (i pewnie działa) jak znajome elementy nakładek interfejsu Maps JavaScript API. Elementy KML <Placemark> i GeoRSS point są renderowane jako znaczniki, na przykład elementy <LineString> są renderowane w postaci linii łamanych, a <Polygon> – jako wielokąty. Podobnie elementy <GroundOverlay> są renderowane na mapie jako prostokątne obrazy. Co ważne, te obiekty nie są interfejsami Maps JavaScript API Markers, Polylines, Polygons ani GroundOverlays. Zamiast tego są renderowane w jednym obiekcie na mapie.

Obiekty KmlLayer pojawią się na mapie, gdy ustawisz ich właściwość map. Możesz je usunąć z mapy, wywołując setMap() przez null. Obiekt KmlLayer zarządza renderowaniem tych elementów podrzędnych, automatycznie pobierając odpowiednie cechy dla określonych granic mapy. Gdy granice się zmieniają, obiekty w bieżącym widocznym obszarze są automatycznie renderowane.

Komponenty w elemencie KmlLayer są renderowane na żądanie, więc warstwa pozwala łatwo zarządzać renderowaniem tysięcy znaczników, linii łamanych i wielokątów. Pamiętaj, że nie masz bezpośredniego dostępu do tych obiektów składowych, chociaż każdy z nich zapewnia zdarzenia kliknięcia, które zwracają dane o tych pojedynczych obiektach.

Opcje warstwy KML

Konstruktor KmlLayer() przekazuje opcjonalnie liczbę KmlLayerOptions:

• map określa pole Map, na którym ma zostać wyrenderowana KmlLayer. Możesz ukryć właściwość KmlLayer, ustawiając tę wartość na null w metodzie setMap().
• preserveViewport określa, że podczas wyświetlania warstwy mapa nie powinna być dostosowywana do granic zawartości KmlLayer. Domyślnie podczas wyświetlania elementu KmlLayer mapa jest powiększona i przesuwana tak, by pokazać całą zawartość warstwy.
• suppressInfoWindows wskazuje, że klikalne funkcje w obrębie KmlLayer nie powinny wywoływać wyświetlania obiektów InfoWindow.

Dodatkowo po wyrenderowaniu KmlLayer zawiera stałą właściwość metadata zawierającą nazwę, opis, fragment i autora warstwy w literalu obiektu KmlLayerMetadata. Możesz sprawdzić te informacje za pomocą metody getMetadata(). Renderowanie obiektów KmlLayer wymaga asynchronicznej komunikacji z serwerem zewnętrznym, dlatego warto nasłuchiwać zdarzenia metadata_changed, co będzie oznaczało, że właściwość została wypełniona.

W poniższym przykładzie konstruujemy pole KmlLayer na podstawie podanego kanału GeoRSS:

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

Ten przykład tworzy obiekt KmlLayer na podstawie podanego pliku danych KML:

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

Szczegóły funkcji KML

Ponieważ plik KML może obejmować dużą liczbę obiektów, możesz nie mieć dostępu do danych cech bezpośrednio z obiektu KmlLayer. Podczas wyświetlania obiektów są one renderowane jak klikalne nakładki Maps JavaScript API. Kliknięcie domyślnie konkretnego obiektu powoduje wyświetlenie pliku InfoWindow zawierającego informacje o nim w pliku KML <title> i <description>. Dodatkowo kliknięcie obiektu KML powoduje wygenerowanie obiektu KmlMouseEvent, który przekazuje następujące informacje:

• position wskazuje współrzędne długości i szerokości geograficznej, na których ma zostać zakotwiczony element InfoWindow dla tej funkcji KML. Ta lokalizacja jest zwykle klikniętą lokalizacją w przypadku wielokątów, linii łamanych i nakładek podłoża, ale jest to prawdziwe położenie znaczników.
• pixelOffset wskazuje przesunięcie względem powyższego elementu position, aby zakotwiczyć element InfoWindow. W przypadku obiektów wielokątnych to przesunięcie wynosi zwykle 0,0, ale w przypadku znaczników obejmuje wysokość znacznika.
• featureData zawiera strukturę JSON KmlFeatureData.

Przykładowy obiekt KmlFeatureData jest widoczny poniżej:

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

Ten przykład powoduje wyświetlenie tekstu funkcji KML <Description> w obrębie boku <div> po kliknięciu funkcji:

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

Ograniczenia dotyczące rozmiaru i złożoności renderowania KML

Interfejs Maps JavaScript API ma ograniczenia dotyczące rozmiaru i złożoności wczytywanych plików KML. Poniżej znajduje się podsumowanie obecnych limitów.

Uwaga: te limity mogą się zmienić w każdej chwili.

Maksymalny rozmiar pobieranego pliku (nieprzetworzone dane KML, nieprzetworzone dane GeoRSS lub skompresowane dane KMZ)

3MB

Maksymalny rozmiar nieskompresowanego pliku KML

10MB

Maksymalny rozmiar nieskompresowanego pliku graficznego w plikach KMZ

500 KB na plik

Maksymalna liczba linków sieciowych

10

Maksymalna łączna liczba funkcji obejmujących cały dokument

1000

Liczba warstw KML

Liczba warstw KML, które można wyświetlić na jednej Mapie Google, jest ograniczona. Po przekroczeniu tego limitu żadna z Twoich warstw nie pojawi się na mapie, a w konsoli JavaScript Twojej przeglądarki zostanie zgłoszony błąd. Limit jest obliczany na podstawie kombinacji liczby utworzonych klas (KmlLayer) i łącznej długości wszystkich adresów URL użytych do utworzenia tych warstw. Każdy nowy obiekt KmlLayer, który utworzysz, będzie zajmować część limitu warstwy i kolejną część limitu w zależności od długości adresu URL, z którego wczytano plik KML. Oznacza to, że liczba warstw, które możesz dodać, różni się w zależności od aplikacji. Średnio powinno udać się wczytać od 10 do 20 warstw bez przekraczania limitu. Jeśli nadal osiągniesz limit, użyj narzędzia do skracania adresów URL, aby skrócić adresy URL KML. Możesz też utworzyć pojedynczy plik KML zawierający obiekty NetworkLinks z poszczególnymi adresami URL KML.

Uwagi na temat wydajności i buforowania

Serwery Google tymczasowo przechowują pliki KML w pamięci podręcznej, aby zmniejszyć ich obciążenie. Zwiększy to także wydajność użytkowników, ponieważ odpowiednie segmenty z pliku KML będą wyświetlane w zaoszczędzonej przestrzeni, gdy użytkownicy będą klikać, przesuwać i powiększać mapę.

Aby uzyskać najlepszą skuteczność, zalecamy:

• Użyj odpowiedniego tagu <expires> w pliku KML.
  
  KmlLayer nie będzie używać nagłówków HTTP przy wyborze sposobu buforowania plików KML.
• Nie generuj plików dynamicznie w czasie żądania.
  
  Zamiast tego wygeneruj pliki, zanim będą potrzebne, i wyświetlaj je statycznie. Jeśli przesyłanie pliku KML trwa zbyt długo, KmlLayer może się nie wyświetlić.
• Nie próbuj omijać pamięci podręcznych, jeśli nie masz pewności, że plik został zaktualizowany.
  
  Pomijanie pamięci podręcznych (na przykład przez dodanie losowej liczby lub czasu zegara użytkownika jako parametru zapytania) może łatwo spowodować przeciążenie Twoich serwerów, jeśli witryna nagle stanie się popularna i będziesz obsługiwać duże pliki KML.
  
  Może też powodować wyświetlanie z pamięci podręcznej nieaktualnych danych użytkownikom, jeśli zegar któregoś z użytkowników jest ustawiony nieprawidłowo, a tag <expires> nie jest prawidłowo skonfigurowany.
  
  Zamiast tego opublikuj zaktualizowane pliki statyczne z nowym, osobnym numerem wersji i użyj kodu po stronie serwera, aby dynamicznie aktualizować adres URL przekazywany do KmlLayer za pomocą bieżącej wersji.
• Ogranicz zmiany w plikach KML do raz na minutę.
  
  Jeśli łącznie wszystkie pliki mają więcej niż 1 MB (po zdekompresowaniu), ogranicz zmiany do jednego miejsca na 5 minut.
• Gdy korzystasz z serwera danych geoprzestrzennych, unikaj używania parametrów zapytania do ograniczania widocznego obszaru warstw.
  
  Zamiast tego możesz ograniczyć widoczny na mapie za pomocą zdarzenia bounds_changed. Użytkownicy otrzymają tylko te funkcje, które mogą być wyświetlane automatycznie.
  
  Jeśli na serwerze danych geoprzestrzennych przechowywano dużo danych, rozważ użycie warstw danych.
• Gdy korzystasz z serwera danych geoprzestrzennych, zamiast pojedynczego obiektu KmlLayer z różnymi parametrami zapytania, używaj wielu elementów KmlLayer dla każdej grupy funkcji, które użytkownicy mogą przełączać.
• Użyj skompresowanych plików KMZ, aby zmniejszyć ich rozmiar.
• Jeśli korzystasz z Google Cloud Storage lub innego rozwiązania do przechowywania danych w chmurze, unikaj używania takich funkcji jak podpisane adresy URL lub tokeny tymczasowe, aby wymuszać kontrolę dostępu. Mogą one nieumyślnie zapobiegać buforowaniu.
• Zmniejsz precyzję wszystkich punktów do odpowiedniej precyzji.
• Scal i uprość geometrię podobnych obiektów, takich jak wielokąty i linie łamane.
• Usuń wszystkie nieużywane elementy lub zasoby obrazu.
• Usuń wszystkie nieobsługiwane elementy.

Jeśli chcesz uzyskać dostęp do prywatnych danych, zapobiec buforowaniu lub wysyłać jako parametr zapytania widoczny obszar przeglądarki do serwera danych geoprzestrzennych, zalecamy użycie warstw danych zamiast KmlLayer. Spowoduje to przekierowanie przeglądarek użytkowników na bezpośrednie wysyłanie żądań zasobów do Twojego serwera WWW.

Obsługiwane elementy KML

Interfejs Maps JavaScript API obsługuje następujące elementy KML. Parser plików KML ignoruje bez powiadamiania tagi XML, których nie rozpoznaje.

• Oznaczenia miejsc
• Ikony
• Foldery
• Opisowy kod HTML – zastępowanie encji przy użyciu elementów <BalloonStyle> i <text>
• pliki KMZ (skompresowane pliki KML, w tym również dołączone zdjęcia)
• linie łamane i wielokąty
• style linii łamanych i wielokątów, w tym kolor, wypełnienie i przezroczystość
• linki sieciowe do dynamicznego importowania danych
• warstwy nad powierzchnią oraz warstwy ekranu

Tabela poniżej zawiera szczegółowe informacje na temat obsługiwanych elementów KML.