KML ve GeoRSS Katmanları

KmlLayer, KML ve GeoRSS öğelerini bir Maps JavaScript API parça yer paylaşımına oluşturur.

Genel bakış

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

Not: Maps JavaScript API'de KML yer paylaşımları oluşturan KmlLayer sınıfı, oluşturma için KML dosyalarını almak ve ayrıştırmak amacıyla Google tarafından barındırılan bir hizmet kullanır. Sonuç olarak, KML dosyaları yalnızca erişmek için kimlik doğrulama gerektirmeyen ve herkesin erişebileceği bir URL'de barındırılıyorsa görüntülenebilir.

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

Maps JavaScript API, sağlanan coğrafi XML verilerini, bir Maps JavaScript API bloku yer paylaşımı kullanarak haritada görüntülenen bir KML gösterimine dönüştürür. Bu KML, bilinen Haritalar JavaScript API yer paylaşımlı öğeleri gibi görünür (ve bir şekilde davranır). KML <Placemark> ve GeoRSS point öğeleri işaretçi olarak oluşturulur. Örneğin, <LineString> öğeleri çoklu çizgi, <Polygon> öğeleri ise poligon olarak oluşturulur. Benzer şekilde, <GroundOverlay> öğeleri de harita üzerinde dikdörtgen resimler olarak oluşturulur. Ancak daha da önemlisi, bu nesneler Haritalar JavaScript API'si Markers, Polylines, Polygons veya GroundOverlays değildir. Bunun yerine, harita üzerinde tek bir nesneye dönüştürülürler.

KmlLayer nesneleri, map özellikleri ayarlandıktan sonra haritada görünür. null numaralı telefonu setMap() arayarak haritadan kaldırabilirsiniz. KmlLayer nesnesi, haritanın verdiği sınırlar için uygun özellikleri otomatik olarak alarak bu alt öğelerin görüntülenmesini yönetir. Sınırlar değiştikçe geçerli görüntü alanındaki ö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şturma işlemini kolayca yönetmenize olanak tanır. Bu bileşen nesnelere doğrudan erişemeyeceğinizi unutmayın. Bununla birlikte, her biri bu nesnelerle ilgili verileri döndüren tıklama etkinlikleri sağlar.

KML katmanı seçenekleri

KmlLayer() oluşturucu, isteğe bağlı olarak bir KmlLayerOptions sayısı geçirir:

• map, KmlLayer öğesinin oluşturulacağı Map öğesini belirtir. Bir KmlLayer öğesini gizlemek için bu değeri setMap() yönteminde null olarak ayarlayabilirsiniz.
• preserveViewport, katmanı gösterirken KmlLayer içeriğinin sınırlarına göre ayarlama yapılmaması 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österilmesini tetiklememesi gerektiğini belirtir.

Ayrıca, KmlLayer oluşturulduktan sonra bir KmlLayerMetadata nesne değişmez değeri içinde katman 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, mülkün doldurulduğunu gösteren metadata_changed etkinliğini dinlemek istersiniz.

Aşağıdaki örnek, belirtilen GeoRSS özet akışından 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>
    <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

Aşağıdaki örnekte, belirtilen KML feed'inden bir KmlLayer oluşturulur:

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

KML özelliği ayrıntıları

KML çok sayıda özellik içerebileceği için, özellik verilerine doğrudan KmlLayer nesnesinden erişemezsiniz. Özellikler görüntülenirken, tıklanabilir Maps JavaScript API yer paylaşımları gibi görünecek şekilde oluşturulurlar. Varsayılan olarak tekil özellikler tıklandığında, belirtilen özelliğe ilişkin <title> ve <description> KML bilgileri içeren InfoWindow gösterilir. Ayrıca, bir KML özelliği tıklandığında KmlMouseEvent aşağıdaki bilgiler aktarılır:

• position, bu KML özelliği için InfoWindow değerinin sabitleneceği enlem/boylam koordinatlarını gösterir. Bu konum genellikle çokgenler, çoklu çizgiler ve zemin bindirmeleri için tıklanan konum olup işaretçiler için doğru kaynaktır.
• pixelOffset, yukarıdaki "position" öğesinden belirli bir uzaklığı InfoWindow "kuyruğu" olarak belirtir. Çokgen nesneler için bu ofset genellikle 0,0 olur, ancak işaretçilerin yüksekliği işaretçinin yüksekliğini içerir.
• featureData, KmlFeatureData şeklinde bir JSON yapısı içerir.

Aşağıda örnek bir KmlFeatureData nesnesi gösterilmektedir:

{
  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 <Description> özelliği, <div> tarafının içindeki bir metin 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>
    <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

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ık düzeyi konusunda sınırlamalara sahiptir. Aşağıda, geçerli sınırların bir ö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ında 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 hiçbir katmanınız harita üzerinde görünmez ve web tarayıcınızın JavaScript konsolunda hata bildirilir. Sınır, oluşturulan KmlLayer sınıf sayısının ve bu katmanları oluşturmak için kullanılan tüm URL'lerin toplam uzunluğuna bağlıdır. Oluşturduğunuz her yeni KmlLayer, katman dosyasını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ı kaplar. Sonuç olarak, ekleyebileceğiniz katman sayısı uygulamaya göre değişir; ortalama olarak, 10 ila 20 katman arasında bir sınıra ulaşamayabilirsiniz. Sınıra ulaşırsanız KML URL'lerini kısaltmak için URL kısaltıcı kullanın. Alternatif olarak, tek tek KML URL'lerine NetworkLinks içeren tek bir KML dosyası oluşturabilirsiniz.

Performans ve önbelleğe alma konusunda dikkat edilmesi gereken noktalar

Google sunucuları, sunucularınız üzerindeki yükü azaltmak için KML dosyalarını geçici olarak önbelleğe alır. Bu sayede, kullanıcılarınız haritayı tıkladığında, kaydırdığında ve yakınlaştırdığında KML dosyanızın uygun segmentlerinin yer açısından verimli bir şekilde temsil edilmesini sağlayarak kullanıcılarınız daha iyi bir performans elde eder.

En iyi performans için aşağıdakileri yapmanızı öneririz:

• KML'de uygun bir <expires> etiketi kullanın.
  
  KmlLayer, KML dosyalarının nasıl önbelleğe alınacağına karar verilirken HTTP başlıklarını kullanmaz.
• İstek sırasında dosyaları dinamik olarak oluşturmayın.
  
  Bunun yerine, dosyaları ihtiyaç duyulmadan oluşturun ve statik olarak sunun. Sunucunuzun KML dosyasını iletmesi uzun sürüyorsa KmlLayer görüntülenmeyebilir.
• Dosyanızın güncel olduğunu kesin olarak bilmediğiniz sürece önbellekleri atlamaya çalışmayın.
  
  Önbelleklerin her zaman atlanması (örneğin, rastgele bir sayı veya sorgu parametresi olarak kullanıcının saati eklenmemesi), siteniz aniden popüler olursa 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üncellenmiş statik dosyaları yeni, ayrı bir düzeltme numarasıyla yayınlayın ve KmlLayer adresine iletilen URL'yi geçerli sürümle dinamik olarak güncellemek için sunucu tarafı kodu kullanın.
• KML dosyalarınızdaki değişiklikleri dakikada bir kez olacak şekilde sınırlandırın.
  
  Tüm dosyaların boyutu 1 MB'tan büyükse (sıkıştırılmamış) değişiklikleri 5 dakikada bir ile sınırlandırın.
• Coğrafi bir veri sunucusu kullanırken, katmanların görüntü alanını sınırlamak için sorgu parametreleri kullanmaktan kaçının.
  
  Bunun yerine, bounds_changed görüntü alanıyla harita görüntü alanını sınırlandırabilirsiniz. Kullanıcılara yalnızca otomatik olarak görüntülenebilecek özellikler gönderilecek.
  
  Coğrafi veri sunucunuzda büyük miktarda veri varsa bunun yerine veri katmanları kullanmayı düşünebilirsiniz.
• Coğrafi bir 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 ö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 uygulamak için imzalı URL'ler veya geçici jetonlar gibi özellikleri kullanmaktan kaçının. Bunlar, önbelleğe almayı istemeden engelleyebilir.
• Tüm noktaların kesinliğini uygun bir kesinliğe düşürün.
• Poligonlar ve çoklu çizgiler gibi benzer özelliklerin geometrisini birleştirin ve basitleştirin.
• Kullanılmayan tüm öğeleri veya resim kaynaklarını kaldırın.
• Desteklenmeyen öğeleri kaldırın.

Özel verilere erişmeniz, önbelleğe almayı önlemeniz veya tarayıcı görünümünü sorgu parametresi olarak coğrafi bir veri sunucusuna göndermeniz gerekiyorsa KmlLayer yerine veri katmanlarını kullanmanızı öneririz. Bu, kullanıcılarınızın tarayıcılarını doğrudan web sunucunuzdan kaynak isteğinde bulunmaya 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ı gösterilmektedir.