Warstwy KML i GeoRSS

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

Omówienie

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

Uwaga: klasa KmlLayer, która generuje nakłady KML w interfejsie Maps JavaScript API, korzysta z usługi hostowanej przez Google do pobierania i analizowania plików KML na potrzeby renderowania. W związku z tym pliki KML można wyświetlać tylko wtedy, gdy są one hostowane pod adresem URL dostępnym publicznie, do którego nie trzeba się uwierzytelniać.

Jeśli potrzebujesz dostępu do plików prywatnych, dokładnej kontroli nad pamięcią podręczną lub wysyłania widoku przeglądarki do serwera danych geoprzestrzennych jako parametru zapytania, zalecamy użycie warstw danych zamiast KmlLayer. Spowoduje to, że przeglądarki użytkowników będą bezpośrednio wysyłać żądania zasobów do Twojego serwera WWW.

Interfejs Maps JavaScript API konwertuje podane dane geograficzne XML na reprezentację KML, która jest wyświetlana na mapie za pomocą nakładki mapy interfejsu Maps JavaScript API. Plik KML wygląda (i działa) podobnie jak znane elementy nakładki interfejsu Maps JavaScript API. Elementy KML <Placemark> i GeoRSS point są renderowane jako znaczniki. Na przykład elementy <LineString> są renderowane jako polilinie, a elementy <Polygon> jako wielokąty. Podobnie elementy <GroundOverlay> są renderowane na mapie jako prostokątne obrazy. Należy jednak pamiętać, że te obiekty nie są obiektami interfejsu Maps JavaScript API Markers, Polylines, Polygons ani GroundOverlays, lecz są renderowane jako pojedynczy obiekt na mapie.

Obiekty KmlLayer pojawiają się na mapie po ustawieniu właściwości map. Możesz je usunąć z mapy, wywołując funkcję setMap() z parametrami null. Obiekt KmlLayer zarządza renderowaniem tych elementów podrzędnych, automatycznie pobierając odpowiednie funkcje dla podanych granic mapy. Gdy zmieniają się granice, funkcje w bieżącym widoku są automatycznie renderowane.

Komponenty w KmlLayer są renderowane na żądanie, dzięki czemu ta warstwa pozwala łatwo zarządzać renderowaniem tysięcy znaczników, polilinii i poligonów. Pamiętaj, że nie możesz uzyskać bezpośredniego dostępu do tych obiektów składowych, ale każdy z nich udostępnia zdarzenia kliknięcia, które zwracają dane o tych poszczególnych obiektach.

Opcje warstwy KML

Konstruktor KmlLayer() opcjonalnie przekazuje kilka wartości: KmlLayerOptions:

• map określa Map, na którym ma zostać wyrenderowany element KmlLayer. Możesz ukryć KmlLayer, ustawiając tę wartość na null w ramach metody setMap().
• preserveViewport określa, że podczas wyświetlania warstwy mapa nie powinna być dostosowywana do granic zawartości elementu KmlLayer. Domyślnie podczas wyświetlania KmlLayer mapa jest powiększana i ustawiana tak, aby pokazać całą zawartość warstwy.
• suppressInfoWindows oznacza, że klikalne funkcje w KmlLayer nie powinny powodować wyświetlania obiektów InfoWindow.

Dodatkowo po renderowaniu KmlLayer zawiera ona niezmienną właściwość metadata z nazwą warstwy, opisem, fragmentem i autorem w ramach obiektu KmlLayerMetadata. Te informacje możesz sprawdzić, używając metody getMetadata(). Renderowanie obiektów KmlLayer wymaga komunikacji asynchronicznej z serwerem zewnętrznym, dlatego warto nasłuchiwać zdarzenia metadata_changed, które wskazuje, że właściwość została wypełniona.

W tym przykładzie z danego kanału GeoRSS tworzymy obiekt KmlLayer:

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

W tym przykładzie z podanego pliku danych KML tworzony jest element KmlLayer:

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 zawierać dużą liczbę funkcji, możesz nie mieć dostępu do danych funkcji bezpośrednio z obiektu KmlLayer. Zamiast tego wyświetlane są one jako klikalne nakładki interfejsu Maps JavaScript API. Kliknięcie poszczególnych funkcji powoduje wyświetlenie InfoWindow zawierającego informacje dotyczące danej funkcji w formacie KML <title> i <description>. Kliknięcie funkcji KML powoduje wygenerowanie KmlMouseEvent, który przekazuje te informacje:

• position wskazuje współrzędne geograficzne (długość i szerokości), w których ma być zamocowany element InfoWindow tej funkcji KML. Ta pozycja jest zazwyczaj klikniętą lokalizacją w przypadku wielokątów, polilinii i GroundOverlay, ale prawdziwym źródłem w przypadku znaczników.
• pixelOffset wskazuje przesunięcie od position, aby zamocować „ogon” 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 o postaci KmlFeatureData.

Poniżej znajduje się przykładowy obiekt KmlFeatureData:

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

Poniższy przykład pokazuje funkcję KML <Description> tekst w ramce <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 podczas renderowania KML

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

Uwaga: te limity mogą ulec zmianie w dowolnym momencie.

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

3 MB

Maksymalny rozmiar nieskompresowanego pliku KML

10 MB

Maksymalny nieskompresowany rozmiar pliku obrazu w plikach KMZ

500 KB na plik

Maksymalna liczba połączeń sieciowych

10

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

1000

Liczba warstw KML

Liczba warstw KML, które można wyświetlić w pojedynczej Mapie Google, jest ograniczona. Jeśli przekroczysz ten limit, żadne warstwy nie będą widoczne na mapie, a w konsoli JavaScript przeglądarki pojawi się komunikat o błędzie. Limit jest określany 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 element KmlLayer, który utworzysz, zajmie część limitu dla warstwy oraz dodatkową część limitu w zależności od długości adresu URL, z którego został załadowany plik KML. W związku z tym liczba warstw, które możesz dodać, będzie się różnić w zależności od aplikacji. Przeciętnie możesz załadować od 10 do 20 warstw bez przekroczenia limitu. Jeśli nadal przekraczasz limit, spróbuj skrócić adresy URL plików KML za pomocą skróconego adresu URL. Możesz też utworzyć jeden plik KML, który będzie zawierać elementy NetworkLinks

do poszczególnych adresów URL plików KML.

Informacje o wydajności i buforowaniu

Serwery Google będą tymczasowo przechowywać w pamięci podręcznej pliki KML, aby zmniejszyć obciążenie serwerów. Dzięki temu poprawi się też wydajność dla użytkowników, ponieważ będą oni otrzymywać oszczędzającą miejsce reprezentację odpowiednich segmentów pliku KML, gdy będą klikać mapę, przesuwać ją i powiększać.

Aby uzyskać najlepszą wydajność, zalecamy:

• Użyj odpowiedniego tagu <expires> w pliku KML.
  
  KmlLayer nie będzie używać nagłówków HTTP do podejmowania decyzji o tym, jak przechowywać w pamięci podręcznej pliki KML.
• Nie generuj plików dynamicznie w momencie wysyłania żądania.
  
  Zamiast tego wygeneruj pliki przed ich użyciem i prześlij je statycznie. Jeśli przesłanie pliku KML zajmuje serwerowi dużo czasu, ikona KmlLayer może się nie wyświetlić.
• Nie próbuj pomijać pamięci podręcznej, chyba że wiesz na pewno, że plik został zaktualizowany.
  
  Zawsze pomijanie pamięci podręcznej (np. przez dodanie losowego numeru lub czasu zegara użytkownika jako parametru zapytania) może łatwo spowodować przeciążenie Twoich serwerów, jeśli Twoja witryna nagle zyska popularność, a Ty będziesz serwować duże pliki KML.
  
  Może to też spowodować, że pamięć podręczna będzie przekazywać użytkownikom nieaktualne dane, jeśli zegar któregoś z użytkowników jest nieprawidłowy, a tag <expires> nie został prawidłowo ustawiony.
  
  Zamiast tego opublikuj zaktualizowane pliki statyczne z nowym, oddzielnym numerem wersji i użyj kodu po stronie serwera, aby dynamicznie aktualizować adres URL przekazywany do funkcji KmlLayer z bieżącą wersją.
• Ogranicz zmiany w plikach KML do jednej na minutę.
  
  Jeśli łączny rozmiar wszystkich plików (w nieskompresowanej formie) przekracza 1 MB, limit zmienia się na jeden raz na 5 minut.
• Korzystając z serwera danych geoprzestrzennych, nie używaj parametrów zapytań do ograniczania widoku warstw.
  
  Zamiast tego możesz ograniczyć widoczny obszar mapy za pomocą zdarzenia bounds_changed. Użytkownikom będą wysyłane tylko funkcje, które można wyświetlić automatycznie.
  
  Jeśli na serwerze danych geoprzestrzennych jest dużo danych, rozważ użycie warstw danych.
• Jeśli korzystasz z serwera danych geoprzestrzennych, zamiast jednego KmlLayer z różnymi parametrami zapytania użyj wielu KmlLayer dla każdej grupy funkcji, które użytkownicy mogą włączać i wyłączać.
• Aby zmniejszyć rozmiar pliku, użyj skompresowanych plików KMZ.
• Jeśli używasz Google Cloud Storage lub innego rozwiązania do przechowywania danych w chmurze, nie używaj funkcji takich jak podpisane adresy URL ani tokenów tymczasowych, aby wymusić kontrolę dostępu. Mogą one niezamierzenie uniemożliwić buforowanie.
• Zmniejsz dokładność wszystkich punktów do odpowiedniej dokładności.
• Łączenie i upraszczanie geometrii podobnych obiektów, takich jak wielokąty i linie łamane.
• Usuń wszystkie nieużywane elementy i zasoby graficzne.
• Usuń nieobsługiwane elementy.

Jeśli potrzebujesz dostępu do danych prywatnych, chcesz zapobiec przechowywaniu w pamięci podręcznej lub wysłać widok w przeglądarce do serwera danych geoprzestrzennych jako parametr zapytania, zalecamy użycie warstw danych zamiast KmlLayer. Spowoduje to, że przeglądarki użytkowników będą bezpośrednio przesyłać żądania zasobów do Twojego serwera WWW.

Obsługiwane elementy KML

Interfejs Maps JavaScript API obsługuje te elementy KML: Parser plików KML ignoruje bez powiadamiania tagi XML, których nie rozpoznaje.

• Oznaczenia miejsc
• Ikony
• Foldery
• HTML opisowy – zastępowanie elementów za pomocą tagó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 pełne informacje o obsługiwanych elementach KML.