KML ve GeoRSS Katmanları

KmlLayer, KML ve GeoRSS öğelerini bir Maps JavaScript API döşeme yer paylaşımı olarak oluşturur.

Genel Bakış

Maps JavaScript API, coğrafi bilgileri görüntülemek için KML ve GeoRSS veri biçimlerini destekler. Bu veri biçimleri, herkese açık bir KML veya GeoRSS dosyasının URL'sini alan bir oluşturucuya sahip KmlLayer nesnesi kullanılarak haritada gösterilir.

Not: Maps JavaScript API'de KML yer paylaşımları oluşturan KmlLayer sınıfı, KML dosyalarını alıp ayrıştırarak oluşturmak için Google tarafından barındırılan bir hizmet kullanır. Bu nedenle, KML dosyalarının gösterilebilmesi için herkese açık olarak erişilebilen ve erişmek için kimlik doğrulama gerektirmeyen bir URL'de barındırılması gerekir.

Özel dosyalara erişmeniz, önbellekler üzerinde ayrıntılı kontrol sahibi olmanız veya tarayıcı görüntü alanını sorgu parametresi olarak bir coğrafi veri sunucusuna göndermeniz gerekiyorsa KmlLayer yerine veri katmanlarını kullanmanızı öneririz. Bu işlem, kullanıcılarınızın tarayıcılarını doğrudan web sunucunuzdan kaynak istemeye yönlendirir.

Maps JavaScript API, sağlanan coğrafi XML verilerini, Maps JavaScript API döşeme yer paylaşımı kullanılarak haritada gösterilen bir KML gösterimine dönüştürür. Bu KML, Maps JavaScript API'nin bilinen yer paylaşımı öğelerine benzer (ve biraz da öyle davranır). KML <Placemark> ve GeoRSS point öğeleri işaretçi olarak işlenir. Örneğin, <LineString> öğeleri çoklu çizgi olarak, <Polygon> öğeleri ise poligon olarak işlenir. Benzer şekilde, <GroundOverlay> öğeleri haritada dikdörtgen resimler olarak oluşturulur. Ancak bu nesnelerin Maps JavaScript API Markers, Polylines, Polygons veya GroundOverlays olmadığını belirtmek önemlidir. Bunun yerine, haritada tek bir nesne olarak oluşturulurlar.

KmlLayer nesneleri, map özelliği ayarlandıktan sonra haritada görünür. setMap() geçerek null numaralı telefonu arayarak bunları haritadan kaldırabilirsiniz. KmlLayer nesnesi, haritanın belirli sınırları için uygun özellikleri otomatik olarak alarak bu alt öğelerin oluşturulmasını yönetir. Sınırlar değiştikçe mevcut görünüm penceresindeki özellikler otomatik olarak oluşturulur.

KmlLayer içindeki bileşenler isteğe bağlı olarak oluşturulduğundan katman, binlerce işaretçinin, çoklu çizginin ve poligonun oluşturulmasını kolayca yönetmenize olanak tanır. Bu bileşen nesnelerine doğrudan erişemezsiniz ancak her biri, söz konusu nesnelerle ilgili verileri döndüren tıklama etkinlikleri sağlar.

KML katmanı seçenekleri

KmlLayer() oluşturucu, isteğe bağlı olarak bir dizi KmlLayerOptions iletir:

• map, KmlLayer öğesinin oluşturulacağı Map öğesini belirtir. setMap() yönteminde bu değeri null olarak ayarlayarak KmlLayer gizleyebilirsiniz.
• preserveViewport, katman gösterilirken haritanın KmlLayer içeriğinin sınırlarına göre ayarlanmaması gerektiğini belirtir. Varsayılan olarak, KmlLayer gösterilirken harita, katmanın içeriklerinin tamamını gösterecek şekilde yakınlaştırılır ve konumlandırılır.
• suppressInfoWindows, KmlLayer içindeki tıklanabilir özelliklerin InfoWindow nesnelerinin gösterilmesini tetiklememesi gerektiğini belirtir.

Ayrıca, KmlLayer oluşturulduktan sonra katmanın adını, açıklamasını, snippet'ini ve yazarını içeren değişmez bir metadata özelliği içerir. Bu özellik, KmlLayerMetadata nesne değişmezinin içinde yer alır. Bu bilgileri getMetadata() yöntemini kullanarak inceleyebilirsiniz. KmlLayer nesnelerinin oluşturulması için harici bir sunucuyla eşzamansız iletişim gerektiğinden, özelliğin doldurulduğunu belirten metadata_changed etkinliğini dinlemeniz gerekir.

Aşağıdaki örnekte, verilen GeoRSS özet akışından KmlLayer oluşturulmaktadır:

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

Aşağıdaki örnekte, verilen KML feed'inden KmlLayer oluşturulmaktadır:

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

KML özelliği ayrıntıları

KML çok sayıda özellik içerebileceğinden, özellik verilerine doğrudan KmlLayer nesnesinden erişemeyebilirsiniz. Bunun yerine, özellikler görüntülendiğinde tıklanabilir Maps JavaScript API yer paylaşımları gibi oluşturulur. Tek tek özellikler tıklandığında varsayılan olarak, söz konusu özellikle ilgili KML <title> ve <description> bilgilerini içeren bir InfoWindow açılır. Ayrıca, bir KML özelliği tıklandığında aşağıdaki bilgileri ileten bir KmlMouseEvent oluşturulur:

• position, bu KML özelliği için InfoWindow öğesinin sabitleneceği enlem/boylam koordinatlarını gösterir. Bu konum genellikle poligonlar, çoklu çizgiler ve GroundOverlay'ler için tıklanan konumdur ancak işaretçiler için gerçek başlangıç noktasıdır.
• pixelOffset, InfoWindow "kuyruğunu" sabitlemek için yukarıdaki position öğesinden olan uzaklığı gösterir. Çokgen nesneler için bu uzaklık genellikle 0,0 olur ancak işaretçiler için işaretçinin yüksekliğini de içerir.
• featureData, KmlFeatureData JSON yapısını içerir.

Örnek bir KmlFeatureData nesnesi aşağıda gösterilmiştir:

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

Aşağıdaki örnekte, özellik tıklandığında bir yan <div> içinde KML özelliği <Description> metni gösterilmektedir:

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

KML oluşturma için boyut ve karmaşıklık kısıtlamaları

Maps JavaScript API'nin, yüklenen KML dosyalarının boyutu ve karmaşıklığıyla ilgili sınırlamaları vardır. Mevcut sınırların özeti aşağıda verilmiştir.

Not: Bu sınırlar herhangi bir zamanda değişebilir.

Maksimum getirilen dosya boyutu (ham KML, ham GeoRSS veya sıkıştırılmış KMZ)

3MB

Maksimum sıkıştırılmamış KML dosyası boyutu

10MB

KMZ dosyalarındaki maksimum sıkıştırılmamış resim dosyası boyutu

Dosya başına 500 KB

Maksimum ağ bağlantısı sayısı

10

Doküman genelindeki özelliklerin maksimum sayısı

1.000

KML katmanı sayısı

Tek bir Google Haritası'nda görüntülenebilecek KML katmanı sayısıyla ilgili bir sınır vardır. Bu sınırı aşarsanız katmanlarınızın hiçbiri haritada görünmez ve web tarayıcınızın JavaScript konsolunda bir hata bildirilir. Sınır, oluşturulan KmlLayer sınıf sayısı ve bu katmanları oluşturmak için kullanılan tüm URL'lerin toplam uzunluğunun bir kombinasyonuna dayanır. Oluşturduğunuz her yeni KmlLayer katmanın sınırının bir kısmını ve KML dosyasının yüklendiği URL'nin uzunluğuna bağlı olarak sınırın başka bir kısmını kullanır. Bu nedenle, ekleyebileceğiniz katman sayısı uygulamaya göre değişir. Ortalama olarak, sınıra ulaşmadan 10 ila 20 katman yükleyebilirsiniz. Hâlâ sınıra ulaşıyorsanız KML URL'lerini kısaltmak için URL kısaltıcı kullanın. Alternatif olarak, tek tek KML URL'lerine NetworkLinks'lerden oluşan tek bir KML dosyası oluşturun.

Performans ve önbelleğe alma ile ilgili dikkat edilmesi gereken noktalar

Google'ın sunucuları, sunucularınızdaki yükü azaltmak için KML dosyalarını geçici olarak önbelleğe alır. Bu, kullanıcılarınız haritayı tıkladıkça, kaydırdıkça ve yakınlaştırıp uzaklaştırdıkça KML dosyanızdaki uygun segmentlerin yerden tasarruf sağlayan bir gösterimini sunarak kullanıcılarınızın performansını da artırır.

En iyi performans için şunları yapmanızı öneririz:

• KML'de uygun bir <expires> etiketi kullanın.
  
  KmlLayer, KML dosyalarının nasıl önbelleğe alınacağına karar verirken HTTP üst bilgilerini kullanmaz.
• İstek sırasında dosyaları dinamik olarak oluşturmayın.
  
  Bunun yerine, dosyaları ihtiyaç duyulmadan önce oluşturun ve statik olarak yayınlayın. Sunucunuzun KML dosyasını iletmesi uzun sürerse KmlLayer simgesi gösterilmeyebilir.
• Dosyanızın güncellendiğinden kesin olarak emin değilseniz önbellekleri atlamaya çalışmayın.
  
  Önbellekleri her zaman atlamak (ör. sorgu parametresi olarak rastgele bir sayı veya kullanıcının saatini ekleyerek) siteniz aniden popüler hale gelirse ve büyük KML dosyaları sunuyorsanız sunucularınızın kolayca aşırı yüklenmesine neden olabilir.
  
  Ayrıca, herhangi bir kullanıcının saati yanlışsa ve <expires> etiketi doğru şekilde ayarlanmamışsa önbelleğin kullanıcılara eski veriler sunmasına da neden olabilir.
  
  Bunun yerine, güncellenen statik dosyaları yeni ve ayrı bir düzeltme numarasıyla yayınlayın ve KmlLayer'ye iletilen URL'yi sunucu tarafı kodu kullanarak dinamik olarak güncelleyin.
• KML dosyalarınızda dakikada en fazla bir değişiklik yapın.
  
  Tüm dosyaların toplam boyutu 1 MB'tan (sıkıştırılmamış) fazlaysa değişiklikleri 5 dakikada bir kez olacak şekilde sınırlayın.
• Coğrafi veri sunucusu kullanırken katmanların görünüm alanını sınırlamak için sorgu parametrelerini kullanmaktan kaçının.
  
  Bunun yerine, harita görüntü alanını bounds_changed etkinliğiyle sınırlayabilirsiniz. Kullanıcılara yalnızca otomatik olarak gösterilebilen özellikler gönderilir.
  
  Coğrafi veri sunucunuzda büyük miktarda veri varsa bunun yerine veri katmanlarını kullanabilirsiniz.
• Coğrafi veriler sunucusu kullanırken, kullanıcıların açıp kapatmasına izin vermek istediğiniz her özellik grubu için farklı sorgu parametrelerine sahip tek bir KmlLayer yerine birden fazla KmlLayer kullanın.
• Dosya boyutunu küçültmek için sıkıştırılmış KMZ dosyalarını kullanın.
• Google Cloud Storage veya başka bir bulut depolama çözümü kullanıyorsanız erişim kontrollerini uygulamak için İmzalı URL'ler veya geçici jetonlar gibi özellikleri kullanmaktan kaçının. Bunlar, önbelleğe almayı istemeden engelleyebilir.
• Tüm noktaların hassasiyetini uygun bir hassasiyete düşürün.
• Poligonlar ve çoklu çizgiler gibi benzer unsurların geometrisini birleştirip basitleştirin.
• Kullanılmayan öğeleri veya resim kaynaklarını kaldırın.
• Desteklenmeyen öğeleri kaldırın.

Özel verilere erişmeniz, önbelleğe almayı engellemeniz veya tarayıcı görünüm alanını bir sorgu parametresi olarak coğrafi veriler sunucusuna göndermeniz gerekiyorsa KmlLayer yerine veri katmanlarını kullanmanızı öneririz. Bu işlem, kullanıcılarınızın tarayıcılarını doğrudan web sunucunuzdan kaynak istemeye yönlendirir.

Desteklenen KML öğeleri

Maps JavaScript API, aşağıdaki KML öğelerini destekler. KML ayrıştırıcısı, genellikle, anlamlandıramadığı XML etiketlerini sessiz bir şekilde göz ardı eder.

• Yer İşaretleri
• Simgeler
• Klasörler
• Açıklayıcı HTML: <BalloonStyle> ve <text> aracılığıyla öğe değiştirme
• KMZ (ekli resimler de dahil olmak üzere, sıkıştırılmış KML)
• Çoklu çizgiler ve poligonlar
• Renk, dolgu ve saydamlık da dahil olmak üzere, çoklu çizgiler ve poligonlar için stiller
• Dinamik olarak veri içe aktarmak için ağ bağlantıları
• Yer katmanları ve ekran katmanları

Aşağıdaki tabloda, desteklenen KML öğeleriyle ilgili tüm ayrıntılar verilmektedir.