Warstwy KML i GeoRSS

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

Opis

Interfejs Maps JavaScript API obsługuje formaty danych KML i GeoRSS w celu wyświetlania informacji geograficznych. Te formaty danych są wyświetlane na mapie przy użyciu obiektu KmlLayer, którego konstruktor pobiera 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. W związku z tym można wyświetlać pliki KML tylko wtedy, gdy są przechowywane pod publicznie dostępnym adresem URL, do którego dostęp 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życie warstw danych zamiast KmlLayer. Spowoduje to przekierowanie przeglądarek użytkowników do bezpośredniego żądania zasobów z 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 z kafelkami interfejsu Maps JavaScript API. Ten plik KML wygląda (i trochę się zachowuje) jak elementy nakładki interfejsu Maps JavaScript API. Elementy KML <Placemark> i GeoRSS point są renderowane jako znaczniki. Na przykład elementy <LineString> – jako linie łamane, a elementy <Polygon> – jako wielokąty. Podobnie elementy <GroundOverlay> są renderowane na mapie jako prostokątne obrazy. Co ważne, te obiekty nie są interfejsem Maps JavaScript API Markers, Polylines, Polygons ani GroundOverlays – są renderowane jako pojedynczy obiekt na mapie.

Gdy ustawisz właściwość map, obiekty KmlLayer pojawią się na mapie. Możesz je usunąć z mapy, wywołując metodę setMap() przekazującą null. Obiekt KmlLayer zarządza renderowaniem tych elementów podrzędnych przez automatyczne pobieranie odpowiednich cech na potrzeby podanych granic mapy. Gdy granice się zmieniają, obiekty w bieżącym widocznym obszarze są renderowane automatycznie.

Komponenty w obiekcie KmlLayer są renderowane na żądanie, dlatego 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, ale każdy z nich zawiera zdarzenia kliknięcia, które zwracają dane tych obiektów.

Opcje warstwy KML

Konstruktor KmlLayer() opcjonalnie przekazuje liczbę KmlLayerOptions:

• map określa element Map, w którym ma być renderowany 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 elementu KmlLayer. Podczas wyświetlania obiektu KmlLayer mapa jest domyślnie powiększona i ustawiona tak, aby pokazać całą zawartość warstwy.
• suppressInfoWindows wskazuje, że klikalne obiekty w KmlLayer nie powinny uruchamiać wyświetlania obiektów InfoWindow.

Dodatkowo po wyrenderowaniu KmlLayer zawiera niezmienną właściwość metadata zawierającą nazwę warstwy, opis, fragment kodu i autora w literale obiektu KmlLayerMetadata. Te informacje możesz sprawdzić za pomocą metody getMetadata(). Renderowanie obiektów KmlLayer wymaga asynchronicznej komunikacji z serwerem zewnętrznym, dlatego warto nasłuchiwać zdarzenia metadata_changed, które wskazuje, że właściwość została wypełniona.

Ten przykład umożliwia utworzenie elementu KmlLayer z danego 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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

Poniższy przykład umożliwia utworzenie elementu KmlLayer z danego kanału 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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

Plik KML może obejmować dużą liczbę obiektów, dlatego nie możesz uzyskać dostępu do danych cech bezpośrednio z obiektu KmlLayer. Podczas wyświetlania obiektów wyglądają one jak klikalne nakładki interfejsu Maps JavaScript API. Domyślnie kliknięcie danego obiektu powoduje wyświetlenie InfoWindow z informacjami w formacie KML <title> i <description> dotyczącymi danej cechy. Poza tym kliknięcie funkcji KML generuje element KmlMouseEvent, który przekazuje następujące informacje:

• position wskazuje współrzędne szerokości i długości geograficznej, w których ma być zakotwiczony element InfoWindow dla danego obiektu KML. Ta pozycja jest zwykle klikniętą lokalizacją wielokątów, linii łamanych i nakładek naziemnych, ale jest to rzeczywiste źródło znaczników.
• pixelOffset wskazuje przesunięcie od wskazanego powyżej position miejsca zakotwiczenia elementu 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.

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"
}

Na przykładzie poniżej widać tekst elementu KML <Description> w boku elementu <div> po kliknięciu obiektu:

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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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 rozmiaru i złożoności renderowania KML

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

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

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. Jeśli przekroczysz ten limit, na mapie nie pojawi się żadna z warstw, a w konsoli JavaScript Twojej przeglądarki pojawi się komunikat o błędzie. Limit jest obliczany na podstawie liczby utworzonych klas KmlLayer i łącznej długości wszystkich adresów URL użytych do utworzenia tych warstw. Każdy nowo utworzony element KmlLayer będzie zajmować część limitu warstwy i dalszą część limitu w zależności od długości adresu URL, z którego został wczytany plik KML. W związku z tym liczba warstw, które możesz dodać, będzie różna w zależności od aplikacji. Przeciętnie powinno być możliwe wczytanie od 10 do 20 warstw bez przekroczenia limitu. Jeśli nadal osiągniesz limit, użyj narzędzia do skracania adresów URL, aby skrócić adresy URL. Możesz też utworzyć pojedynczy plik KML zawierający elementy NetworkLinks do poszczególnych adresów URL w formacie KML.

Uwagi na temat wydajności i pamięci podręcznej

Serwery Google tymczasowo zapisują pliki KML w pamięci podręcznej, aby zmniejszyć obciążenie Twoich serwerów. Zwiększa to też wydajność użytkowników, ponieważ gdy użytkownicy klikają, przesuwają i powiększają mapę, reprezentacja odpowiednich segmentów w pliku KML nie zajmuje dużo miejsca.

Aby uzyskać najlepszą skuteczność, zalecamy:

• Użyj odpowiedniego tagu <expires> w pliku KML.
  
  KmlLayer nie będzie używać nagłówków HTTP podczas podejmowania decyzji o pamięci podręcznej 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 przez serwer trwa zbyt długo, parametr 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.
  
  Ciągłe ominięcie pamięci podręcznej (np. przez dołączanie losowej liczby lub godziny zegara użytkownika jako parametru zapytania) może łatwo spowodować przeciążenie Twoich serwerów w przypadku nagłego zwiększenia popularności witryny i udostępniania dużych plików KML.
  
  Może to też spowodować, że pamięć podręczna będzie wyświetlać użytkownikom nieaktualne dane, jeśli zegar jakiegoś użytkownika jest nieprawidłowy, a tag <expires> nie został prawidłowo ustawiony.
  
  Zamiast tego opublikuj zaktualizowane pliki statyczne z nowym, dyskretnym numerem wersji i używaj kodu po stronie serwera, aby dynamicznie aktualizować adres URL przekazany do KmlLayer za pomocą bieżącej wersji.
• Ogranicz wprowadzanie zmian w plikach KML do raz na minutę.
  
  Jeśli łączny rozmiar wszystkich plików (po zdekompresowaniu przekracza 1 MB), ogranicz liczbę zmian do 1 na 5 minut.
• Jeśli korzystasz z serwera danych geoprzestrzennych, unikaj używania parametrów zapytania, aby ograniczyć widoczny obszar warstw.
  
  Możesz jednak ograniczyć widoczny obszar mapy za pomocą zdarzenia bounds_changed. Użytkownicy otrzymają tylko te funkcje, które mogą zostać wyświetlone 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 obiektu KmlLayer z różnymi parametrami zapytania użyj wielu elementów KmlLayer dla każdej grupy funkcji, na które chcesz zezwolić użytkownikom.
• Aby zmniejszyć rozmiar pliku, użyj skompresowanych plików KMZ.
• 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 czy tokeny tymczasowe do wymuszania kontroli dostępu. Mogą one w sposób niezamierzony zapobiec zapisywaniu danych w pamięci podręcznej.
• Zmniejsz dokładność wszystkich punktów do odpowiedniej precyzji.
• Scalanie i upraszczanie geometrii podobnych obiektów, takich jak wielokąty i linie łamane.
• Usuń nieużywane elementy lub zasoby graficzne.
• Usuń wszystkie nieobsługiwane elementy.

Jeśli chcesz uzyskać dostęp do danych prywatnych, zapobiec zapisywaniu danych w pamięci podręcznej lub wysłać widoczny obszar przeglądarki do serwera danych geoprzestrzennych w ramach parametru zapytania, zalecamy używanie warstw danych zamiast KmlLayer. Spowoduje to przekierowanie przeglądarek użytkowników bezpośrednio do Twojego serwera WWW.

Obsługiwane elementy KML

Interfejs Maps JavaScript API obsługuje poniższe 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 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

Poniższa tabela zawiera pełne informacje na temat obsługiwanych elementów KML.