Warstwy KML i GeoRSS

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

Przegląd

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ładki KML w interfejsie Maps JavaScript API, korzysta z usługi hostowanej przez Google do pobierania i parsowania plików KML na potrzeby renderowania. W związku z tym pliki KML można wyświetlać tylko wtedy, gdy są hostowane pod publicznie dostępnym adresem URL, który nie wymaga uwierzytelniania.

Jeśli potrzebujesz dostępu do prywatnych plików, precyzyjnej kontroli nad pamięcią podręczną lub wysyłania widocznego obszaru przeglądarki do serwera danych geoprzestrzennych jako parametru zapytania, zalecamy używanie 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 geograficzne dane XML na reprezentację KML, która jest wyświetlana na mapie za pomocą nakładki z kafelkami interfejsu Maps JavaScript API. Ten plik KML wygląda (i zachowuje się) podobnie do znanych elementów nakładki interfejsu Maps JavaScript API. Elementy KML <Placemark> i GeoRSS point są renderowane jako markery, np. elementy <LineString> są renderowane jako polilinie, a elementy <Polygon> jako wielokąty. Podobnie elementy <GroundOverlay> są renderowane na mapie jako prostokątne obrazy. Ważne jest jednak to, że te obiekty nie są elementami Markers, Polylines, Polygons ani GroundOverlays interfejsu Maps JavaScript API. Zamiast tego są renderowane jako jeden 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() i przekazując wartość null. Obiekt KmlLayer zarządza renderowaniem tych elementów podrzędnych, automatycznie pobierając odpowiednie funkcje dla danego obszaru mapy. Gdy zmieniają się granice, funkcje w bieżącym widocznym obszarze są automatycznie renderowane.

Komponenty w KmlLayer są renderowane na żądanie, dzięki czemu warstwa umożliwia łatwe zarządzanie renderowaniem tysięcy znaczników, polilinii i wielokątów. Pamiętaj, że nie możesz uzyskać bezpośredniego dostępu do tych obiektów składowych, ale każdy z nich generuje zdarzenia kliknięcia, które zwracają dane dotyczące poszczególnych obiektów.

Opcje warstwy KML

Konstruktor KmlLayer() opcjonalnie przekazuje liczbę KmlLayerOptions:

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

Po wyrenderowaniu elementu KmlLayer zawiera on niezmienną właściwość metadata, która zawiera nazwę, opis, fragment i autora warstwy w obiekcie 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, które wskazuje, że właściwość została wypełniona.

W przykładzie poniżej tworzymy obiekt 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

W tym przykładzie tworzymy 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

Plik KML może zawierać dużą liczbę elementów, więc możesz nie mieć bezpośredniego dostępu do danych elementów z obiektu KmlLayer. Zamiast tego wyświetlane funkcje są renderowane tak, aby wyglądały jak nakładki interfejsu Maps JavaScript API, w które można kliknąć. Kliknięcie poszczególnych obiektów domyślnie powoduje wyświetlenie InfoWindow zawierającego informacje o pliku KML <title> i <description> dotyczące danego obiektu. Kliknięcie elementu KML generuje KmlMouseEvent, które przekazuje te informacje:

• position wskazuje współrzędne szerokości i długości geograficznej, w których ma być zakotwiczony InfoWindow dla tej funkcji KML. Ta pozycja jest zwykle klikniętą lokalizacją w przypadku wielokątów, polilinii i nakładek na ziemię, ale w przypadku znaczników jest to prawdziwy punkt początkowy.
• pixelOffset oznacza przesunięcie od powyższego position, które służy do zakotwiczenia „ogona” 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:

{
  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 tekst elementu KML <Description> w bocznym <div> po kliknięciu elementu:

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 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 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 rozmiar nieskompresowanego pliku obrazu 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

Istnieje limit liczby warstw KML, które można wyświetlić na jednej mapie Google. Jeśli przekroczysz ten limit, żadna z Twoich warstw nie pojawi się na mapie, a w konsoli JavaScript przeglądarki internetowej zostanie zgłoszony błąd. Limit zależy od liczby utworzonych KmlLayerzajęć i łącznej długości wszystkich adresów URL użytych do utworzenia tych warstw. Każda nowa KmlLayer zajmuje część limitu warstwy i dodatkową część limitu w zależności od długości adresu URL, z którego załadowano 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. Średnio możesz wczytać od 10 do 20 warstw, zanim osiągniesz limit. Jeśli nadal przekraczasz limit, użyj skracacza adresów URL, aby skrócić adresy URL KML. Możesz też utworzyć jeden plik KML zawierający NetworkLinks do poszczególnych adresów URL KML.

Wskazówki dotyczące wydajności i buforowania

Serwery Google będą tymczasowo przechowywać pliki KML w pamięci podręcznej, aby zmniejszyć obciążenie Twoich serwerów. Poprawi to też wydajność dla użytkowników, ponieważ w miarę klikania, przesuwania i powiększania mapy będą oni widzieć odpowiednie segmenty z pliku KML w formie zajmującej mało miejsca.

Aby uzyskać najlepsze wyniki, zalecamy:

• Użyj odpowiedniego tagu <expires> w KML.
  
  KmlLayer nie będzie używać nagłówków HTTP podczas podejmowania decyzji o tym, jak buforować pliki KML.
• Nie generuj plików dynamicznie w momencie wysłania prośby.
  
  Zamiast tego generuj pliki, zanim będą potrzebne, i wyświetlaj je statycznie. Jeśli serwer długo przesyła plik KML, ikona KmlLayer może się nie wyświetlać.
• Nie próbuj pomijać pamięci podręcznej, chyba że masz pewność, że plik został zaktualizowany.
  
  Zawsze pomijanie pamięci podręcznej (np. przez dodawanie losowej liczby lub czasu zegarowego 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 udostępniać duże pliki KML.
  
  Może to również spowodować, że pamięć podręczna będzie wyświetlać użytkownikom nieaktualne dane, jeśli zegar któregokolwiek użytkownika jest nieprawidłowy, a tag <expires> nie został prawidłowo skonfigurowany.
  
  Zamiast tego opublikuj zaktualizowane pliki statyczne z nowym, odrębnym numerem wersji i użyj kodu po stronie serwera, aby dynamicznie aktualizować adres URL przekazywany do KmlLayer z bieżącą wersją.
• Wprowadzaj zmiany w plikach KML nie częściej niż raz na minutę.
  
  Jeśli łączny rozmiar wszystkich plików (po rozpakowaniu) przekracza 1 MB, limit zmian wynosi 1 raz na 5 minut.
• Jeśli używasz serwera danych geoprzestrzennych, unikaj używania parametrów zapytania do ograniczania obszaru widoku warstw.
  
  Zamiast tego możesz ograniczyć widoczny obszar mapy za pomocą zdarzenia bounds_changed. Użytkownicy będą otrzymywać tylko funkcje, które mogą być wyświetlane automatycznie.
  
  Jeśli na serwerze danych geoprzestrzennych znajduje się duża ilość danych, rozważ użycie warstw danych.
• Jeśli używasz serwera danych geoprzestrzennych, używaj wielu elementów KmlLayer dla każdej grupy obiektów, które użytkownicy mają móc włączać i wyłączać, zamiast jednego elementu KmlLayer z różnymi parametrami zapytania.
• Aby zmniejszyć rozmiar pliku, używaj skompresowanych plików KMZ.
• Jeśli korzystasz z Google Cloud Storage lub innego rozwiązania do przechowywania w chmurze, unikaj używania funkcji takich jak podpisane adresy URL lub tymczasowe tokeny do egzekwowania kontroli dostępu. Mogą one nieumyślnie uniemożliwiać zapisywanie w pamięci podręcznej.
• Zmniejsz precyzję wszystkich punktów do odpowiedniej precyzji.
• Scalanie i upraszczanie geometrii podobnych obiektów, takich jak wielokąty i linie łamane.
• Usuń wszystkie nieużywane elementy lub zasoby obrazów.
• Usuń wszystkie nieobsługiwane elementy.

Jeśli musisz uzyskać dostęp do danych prywatnych, zapobiec buforowaniu lub wysłać do serwera danych geoprzestrzennych widoczny obszar przeglądarki jako parametr zapytania, zalecamy użycie warstw danych zamiast KmlLayer. Spowoduje to przekierowanie przeglądarek użytkowników do bezpośredniego wysyłania żądań zasobów z 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
• Opisowy HTML – zastępowanie jednostek za pomocą 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

W tabeli poniżej znajdziesz szczegółowe informacje o obsługiwanych elementach KML.