KML ve GeoRSS Katmanları

KmlLayer, KML ve GeoRSS öğelerini bir Haritalar JavaScript API'si karo yer paylaşımında 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, oluşturucusu herkes tarafından erişilebilen bir KML veya GeoRSS dosyasının URL'sini alan bir KmlLayer nesnesi kullanılarak harita üzerinde görüntülenir.

Not: Maps JavaScript API'de KML yer paylaşımları oluşturan KmlLayer sınıfı, KML dosyalarını oluşturmak ve ayrıştırmak için Google tarafından barındırılan bir hizmetten yararlanır. Sonuç olarak, KML dosyaları yalnızca erişim için kimlik doğrulaması gerektirmeyen, herkesin erişebileceği bir URL'de barındırılırsa görüntülenebilir.

Gizli 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 bir KML gösterimine dönüştürür. Bu gösterim, haritada Maps JavaScript API parça yerleşimi kullanılarak gösterilir. Bu KML, bilinen Maps JavaScript API yer paylaşımı öğelerine benzer (ve bir şekilde davranır). KML <Placemark> ve GeoRSS point öğeleri, işaretçi olarak oluşturulur. Örneğin, <LineString> öğeleri çoklu çizgiler olarak, <Polygon> öğeleri ise poligonlar olarak oluşturulur. Benzer şekilde, <GroundOverlay> öğeleri haritada dikdörtgen resimler olarak oluşturulur. Ancak daha da önemlisi, bu nesneler Maps JavaScript API Markers, Polylines, Polygons veya GroundOverlays değildir. Bunun yerine, haritada tek bir nesne halinde oluşturulurlar.

map özelliği ayarlandıktan sonra KmlLayer nesne haritada görünür. null numaralı telefonu geçen setMap() numarasını çağırarak bunları haritadan kaldırabilirsiniz. KmlLayer nesnesi, haritanın belirtilen 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üntü alanındaki özellikler otomatik olarak oluşturulur.

KmlLayer içindeki bileşenler isteğe bağlı olarak oluşturulduğundan, bu katman binlerce işaretçi, çoklu çizgi ve poligonun oluşturulmasını kolayca yönetmenizi sağlar. Bu bileşenlerin her biri, söz konusu nesneler hakkında veri döndüren tıklama etkinlikleri sağlar, ancak bu nesnelere doğrudan erişemeyeceğinizi unutmayın.

KML katmanı seçenekleri

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

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

Buna ek olarak, KmlLayer oluşturulduktan sonra, KmlLayerMetadata nesne değişmez değeri içinde katmanın adını, açıklamasını, snippet'ini ve yazarını içeren sabit bir metadata özelliği içerir. Bu bilgileri getMetadata() yöntemini kullanarak inceleyebilirsiniz. KmlLayer nesnelerinin oluşturulması harici bir sunucuyla eşzamansız iletişim kurulmasını gerektirdiğinden, özelliğin doldurulduğunu belirten metadata_changed etkinliğini dinlemek isteyebilirsiniz.

Aşağıdaki örnek, belirtilen GeoRSS feed'inden bir KmlLayer oluşturur:

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 örnek, belirtilen KML feed'inden bir KmlLayer oluşturur:

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şemezsiniz. Bunun yerine, özellikler görüntülendikçe tıklanabilir Maps JavaScript API yer paylaşımları gibi görünür. Özellikler tıklandığında varsayılan olarak, ilgili özellikle ilgili KML <title> ve <description> bilgilerini içeren bir InfoWindow gösterilir. Ayrıca, bir KML özelliği tıklandığında, aşağıdaki bilgileri ileten bir KmlMouseEvent oluşturulur:

• position, bu KML özelliğine ait InfoWindow öğesinin sabitleneceği enlem/boylam koordinatlarını gösterir. Bu konum genellikle poligonlar, çoklu çizgiler ve GroundOverlay'ler (GroundOverlays) için tıklanan konumdur, ancak işaretçiler için doğru başlangıç noktasıdır.
• pixelOffset, InfoWindow "kuyruğunu" sabitlemek için yukarıdaki position ile arasındaki uzaklığı gösterir. Poligonal nesneler için bu ofset genellikle 0,0 şeklindedir ancak işaretçiler için işaretçinin yüksekliğini içerir.
• featureData, KmlFeatureData JSON yapısını içeriyor.

Aşağıda örnek bir KmlFeatureData nesnesi 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 kenarda <div> içinde <Description> KML özelliği 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, yüklenen KML dosyalarının boyutu ve karmaşıklığıyla ilgili sınırlamalara sahiptir. Aşağıda mevcut sınırların özeti verilmiştir.

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

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 Katmanlarının sayısı sınırlıdır. Bu sınırı aşarsanız katmanlarınızın hiçbiri harita üzerinde görünmez ve web tarayıcınızın JavaScript konsolunda bir hata bildirilir. Sınır, oluşturulan KmlLayer sınıfının sayısı ile bu katmanları oluşturmak için kullanılan tüm URL'lerin toplam uzunluğunun birleşimine dayanır. Oluşturduğunuz her yeni KmlLayer, KML dosyasının yüklendiği URL'nin uzunluğuna bağlı olarak katman sınırının bir kısmını ve sınırın ek bir kısmını kullanır. Sonuç olarak, ekleyebileceğiniz katman sayısı uygulamaya göre değişir. Ortalama olarak, sınıra ulaşmadan 10 ila 20 katman yükleyebilmeniz gerekir. Yine de sınıra ulaşırsanız KML URL'lerini kısaltmak için bir URL kısaltıcı kullanın. Alternatif olarak, her bir KML URL'sinin NetworkLinks oluşan tek bir KML dosyası oluşturabilirsiniz.

Performans ve önbelleğe alma konusunda 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ın haritayı tıkladığında, kaydırırken ve yakınlaştırırken, KML dosyanızdaki uygun segmentlerin alan açısından verimli bir temsilini sunarak kullanıcılarınızın performansını da artıracaktı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 sunun. Sunucunuzun KML dosyasını iletmesi uzun zaman alırsa KmlLayer görüntülenmeyebilir.
• Dosyanızın güncellenip güncellenmediğini kesin olarak bilmiyorsanız önbellekleri atlamaya çalışmayın.
  
  Siteniz aniden popüler hale gelirse ve büyük KML dosyaları sunuyorsanız önbellekleri her zaman atlamak (örneğin, sorgu parametresi olarak rastgele bir sayı veya kullanıcının saatini ekleyerek), sunucularınızın aşırı meşgul olmasına neden olabilir.
  
  Ayrıca herhangi bir kullanıcının saati yanlışsa ve <expires> etiketi doğru şekilde ayarlanmadıysa önbelleğin kullanıcılara eski verileri sunmasına da neden olabilir.
  
  Bunun yerine, güncellenmiş statik dosyaları yeni ve ayrı bir düzeltme numarasıyla yayınlayın ve KmlLayer hizmetine iletilen URL'yi geçerli sürümle dinamik olarak güncellemek için sunucu tarafı kod kullanın.
• KML dosyalarınızda yapılacak değişiklikleri dakikada bir defa ile sınırlandırın.
  
  Tüm dosyaların toplam boyutu 1 MB'tan büyükse (sıkıştırılmamış olarak) değişiklikleri 5 dakikada bir olarak sınırlayın.
• Coğrafi veri sunucusu kullanırken katmanların görüntü alanını sınırlamak için sorgu parametreleri kullanmaktan kaçının.
  
  Bunun yerine, harita görüntü alanını bounds_changed etkinliğiyle sınırlandırabilirsiniz. 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ı kullanmayı düşünün.
• Coğrafi veri sunucusu kullanırken farklı sorgu parametrelerine sahip tek bir KmlLayer yerine, kullanıcıların geçiş yapmasına izin vermek istediğiniz her bir özellik grubu için birden fazla KmlLayer kullanın.
• Dosya boyutunu küçültmek için sıkıştırılmış KMZ dosyaları kullanın.
• Google Cloud Storage veya başka bir bulut depolama alanı çözümü kullanıyorsanız erişim denetimlerini zorunlu kılmak için İmzalı URL'ler veya geçici jetonlar gibi özellikleri kullanmayın. Bunlar yanlışlıkla önbelleğe almayı engelleyebilir.
• Tüm noktaların hassasiyetini uygun bir hassasiyete düşürün.
• Poligonlar ve çoklu çizgiler gibi benzer özelliklerin geometrisini birleştirip basitleştirin.
• Kullanılmayan öğeleri veya resim kaynaklarını kaldırın.
• Desteklenmeyen öğeleri kaldırın.

Gizli verilere erişmeniz, önbelleğe almayı önlemeniz veya tarayıcı görüntü alanını sorgu parametresi olarak bir coğrafi veri sunucusuna göndermeniz gerekiyorsa KmlLayer yerine veri katmanları 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 varlık değişimi
• 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 öğelerinin tüm ayrıntıları verilmiştir.