Layer KML dan GeoRSS

KmlLayer merender elemen KML dan GeoRSS menjadi overlay ubin Maps JavaScript API.

Ringkasan

Maps JavaScript API mendukung format data KML dan GeoRSS untuk menampilkan informasi geografis. Format data ini ditampilkan pada peta menggunakan objek KmlLayer, yang konstruktornya mengambil URL file KML atau GeoRSS yang dapat diakses oleh publik.

Catatan: Class KmlLayer yang membuat overlay KML di Maps JavaScript API menggunakan layanan yang dihosting Google untuk mengambil dan mengurai file KML untuk rendering. Akibatnya, file KML hanya dapat ditampilkan jika dihosting di URL yang dapat diakses secara publik yang tidak memerlukan autentikasi untuk mengaksesnya.

Jika Anda memerlukan akses ke file pribadi, kontrol terperinci atas cache, atau ingin mengirim area tampilan browser ke server data geospasial sebagai parameter kueri, sebaiknya gunakan lapisan data, bukan KmlLayer. Tindakan ini akan mengarahkan browser pengguna untuk langsung meminta resource dari server web Anda.

Maps JavaScript API mengonversi data XML geografis yang diberikan menjadi representasi KML yang ditampilkan di peta menggunakan overlay ubin Maps JavaScript API. KML ini terlihat (dan berperilaku) seperti elemen overlay Maps JavaScript API yang sudah dikenal. Elemen KML <Placemark> dan GeoRSS point dirender sebagai penanda, misalnya, elemen <LineString> dirender sebagai polyline dan elemen <Polygon> dirender sebagai poligon. Demikian pula, elemen <GroundOverlay> dirender sebagai gambar persegi panjang pada peta. Namun, yang penting, objek ini bukan Markers, Polylines, Polygons, atau GroundOverlays Maps JavaScript API; melainkan, objek tersebut dirender menjadi satu objek pada peta.

Objek KmlLayer muncul pada peta setelah properti map ditetapkan. Anda dapat menghapusnya dari peta dengan memanggil setMap() yang meneruskan null. Objek KmlLayer mengelola rendering elemen turunan ini dengan mengambil fitur yang sesuai untuk batas tertentu pada peta secara otomatis. Saat batasnya berubah, fitur di area tampilan saat ini akan otomatis dirender.

Karena komponen dalam KmlLayer dirender sesuai permintaan, lapisan ini memudahkan Anda mengelola rendering ribuan penanda, polyline, dan poligon. Perhatikan, Anda tidak dapat mengakses objek konstituen ini secara langsung, meskipun jika setiap objek ini memberikan peristiwa klik yang menampilkan data tentang masing-masing objek tersebut.

Opsi lapisan KML

Konstruktor KmlLayer() secara opsional meneruskan sejumlah KmlLayerOptions:

• map menentukan Map yang akan digunakan untuk merender KmlLayer. Anda dapat menyembunyikan KmlLayer dengan menetapkan nilai ini ke null dalam metode setMap().
• preserveViewport menentukan bahwa peta tidak boleh disesuaikan dengan batas konten KmlLayer saat menampilkan lapisan tersebut. Secara default, saat menampilkan KmlLayer, peta akan di-zoom dan diposisikan untuk menampilkan keseluruhan konten lapisan.
• suppressInfoWindows menunjukkan bahwa fitur yang dapat diklik dalam KmlLayer tidak boleh memicu tampilan objek InfoWindow.

Selain itu, setelah dirender, KmlLayer berisi properti metadata yang tidak dapat diubah yang berisi nama lapisan, deskripsi, cuplikan, dan penulis dalam literal objek KmlLayerMetadata. Anda dapat memeriksa informasi ini menggunakan metode getMetadata(). Karena rendering objek KmlLayer memerlukan komunikasi asinkron ke server eksternal, Anda dapat memproses peristiwa metadata_changed, yang akan menunjukkan bahwa properti telah diisi.

Contoh berikut membuat KmlLayer dari feed GeoRSS tertentu:

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

Contoh berikut membuat KmlLayer dari feed KML tertentu:

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

Detail fitur KML

Karena KML mungkin menyertakan fitur dalam jumlah besar, Anda tidak boleh mengakses data fitur dari objek KmlLayer secara langsung. Sebagai gantinya, saat ditampilkan, fitur tersebut akan dirender agar terlihat seperti overlay Maps JavaScript API yang dapat diklik. Mengklik masing-masing fitur akan secara default menampilkan InfoWindow yang berisi informasi <title> dan <description> KML terkait fitur yang ditentukan. Selain itu, klik pada fitur KML menghasilkan KmlMouseEvent, yang meneruskan informasi berikut:

• position menunjukkan koordinat garis lintang/bujur tempat InfoWindow untuk fitur KML ini ditambatkan. Posisi ini biasanya adalah lokasi klik untuk poligon, polyline, dan GroundOverlays, tetapi merupakan asal sesungguhnya untuk penanda.
• pixelOffset menunjukkan offset dari position di atas untuk menambatkan “tail” InfoWindow. Untuk objek poligon, offset ini biasanya 0,0, tetapi untuk penanda, offset ini mencakup tinggi penanda.
• featureData berisi struktur JSON dari KmlFeatureData.

Contoh objek KmlFeatureData ditampilkan di bawah ini:

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

Contoh berikut menampilkan teks <Description> fitur KML dalam <div> samping saat fitur tersebut diklik:

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

Batasan ukuran dan kompleksitas untuk rendering KML

Maps JavaScript API memiliki batasan terhadap ukuran dan kompleksitas file KML yang dimuat. Di bawah ini adalah rangkuman batas yang saat ini berlaku.

Catatan: Batas ini dapat berubah sewaktu-waktu.

Ukuran file maksimum yang dapat diambil (KML mentah, GeoRSS mentah, atau KMZ yang dikompresi)

3 MB

Ukuran maksimum file KML yang tidak dikompresi

10 MB

Ukuran maksimum file gambar yang tidak dikompresi dalam file KMZ

500 KB per file

Jumlah maksimum network link

10

Jumlah maksimum total fitur seluruh dokumen

1.000

Jumlah lapisan KML

Terdapat batas jumlah Lapisan KML yang dapat ditampilkan pada satu Peta Google. Jika Anda melebihi batas ini, tidak satu pun lapisan Anda yang akan muncul pada peta dan sebuah error akan dilaporkan di Konsol JavaScript browser web Anda. Batas didasarkan pada kombinasi jumlah class KmlLayer yang dibuat dan total panjang semua URL yang digunakan untuk membuat lapisan tersebut. Setiap KmlLayer baru yang Anda buat akan memakan bagian batas untuk lapisan dan bagian lain dari batas tergantung pada panjang URL asal file KML dimuat. Dengan demikian, jumlah lapisan yang dapat Anda tambahkan berbeda dari satu aplikasi dengan yang lain; rata-rata, Anda seharusnya dapat memuat antara 10 hingga 20 lapisan tanpa mencapai batas. Jika Anda masih mencapai batas, gunakan penyingkat URL untuk mempersingkat URL KML. Atau, buat satu file KML yang terdiri dari NetworkLinks untuk setiap URL KML.

Pertimbangan performa dan penyimpanan dalam cache

Server Google akan menyimpan file KML dalam cache sementara waktu untuk mengurangi beban pada server Anda. Hal ini juga akan meningkatkan performa bagi pengguna dengan menampilkan representasi hemat ruang dari segmen yang sesuai pada file KML Anda, saat pengguna mengklik, menggeser, dan melakukan zoom pada peta.

Untuk performa terbaik, sebaiknya:

• Gunakan tag <expires> yang sesuai di KML.
  
  KmlLayer tidak akan menggunakan header HTTP saat menentukan cara menyimpan file KML dalam cache.
• Jangan membuat file secara dinamis pada waktu permintaan.
  
  Buat file sebelum diperlukan, dan tayangkan secara statis. Jika server Anda memerlukan waktu lama untuk mengirimkan file KML, KmlLayer mungkin tidak ditampilkan.
• Jangan mencoba mengabaikan cache kecuali jika Anda mengetahui dengan pasti bahwa file Anda telah diperbarui.
  
  Selalu mengabaikan cache (misalnya, dengan menambahkan angka acak atau waktu jam pengguna sebagai parameter kueri) dapat menyebabkan server Anda mengalami kelebihan beban jika situs Anda tiba-tiba menjadi populer, dan Anda menyajikan file KML yang besar.
  
  Hal ini juga dapat menyebabkan cache menayangkan data yang tidak berlaku kepada pengguna, jika jam pengguna salah, dan tag <expires> belum ditetapkan dengan benar.
  
  Sebaliknya, publikasikan file statis terbaru dengan nomor revisi yang baru dan terpisah, serta gunakan kode sisi server untuk memperbarui URL yang diteruskan secara dinamis ke KmlLayer dengan versi saat ini.
• Batasi perubahan pada file KML Anda sekali per menit.
  
  Jika semua file berukuran lebih dari 1 MB (tidak dikompresi), batasi perubahan menjadi sekali per 5 menit.
• Saat menggunakan server data geospasial, hindari penggunaan parameter kueri untuk membatasi area tampilan lapisan.
  
  Namun, Anda dapat membatasi area tampilan peta dengan peristiwa bounds_changed. Pengguna hanya akan dikirimi fitur yang dapat ditampilkan secara otomatis.
  
  Jika ada banyak data di server data geospasial Anda, sebaiknya gunakan lapisan data.
• Saat menggunakan server data geospasial, gunakan beberapa KmlLayer untuk setiap grup fitur yang boleh diganti oleh pengguna, bukan satu KmlLayer dengan parameter kueri yang berbeda-beda.
• Gunakan file KMZ yang dikompresi untuk mengurangi ukuran file.
• Jika Anda menggunakan Google Cloud Storage atau solusi penyimpanan cloud lainnya, hindari menggunakan fitur seperti URL bertanda tangan atau token sementara untuk menerapkan kontrol akses. Hal ini dapat mencegah penyimpanan cache secara tidak sengaja.
• Kurangi presisi semua titik menjadi presisi yang sesuai.
• Gabungkan dan sederhanakan geometri berbagai fitur yang serupa, seperti poligon dan polyline.
• Hapus elemen atau resource gambar yang tidak digunakan.
• Hapus semua elemen yang tidak didukung.

Jika Anda perlu mengakses data pribadi, mencegah penyimpanan dalam cache, atau mengirim area tampilan browser ke server data geospasial sebagai parameter kueri, sebaiknya gunakan lapisan data, bukan KmlLayer. Tindakan ini akan mengarahkan browser pengguna untuk langsung meminta resource dari server web Anda.

Elemen KML yang didukung

Maps JavaScript API mendukung elemen KML berikut. Parser KML umumnya akan secara diam-diam mengabaikan tag XML yang tidak dipahaminya.

• Penanda letak
• Ikon
• Folder
• HTML deskriptif—Penggantian entitas melalui <BalloonStyle> dan <text>
• KMZ (KML yang dikompresi, termasuk gambar yang dilampirkan)
• Polyline dan poligon
• Gaya untuk polyline dan poligon, termasuk warna, isian, dan opasitas
• Network link untuk mengimpor data secara dinamis
• Overlay bumi dan overlay layar

Tabel berikut berisi detail penuh elemen KML yang didukung.