KML और GeoRSS लेयर

KmlLayer, KML और GeoRSS एलिमेंट को Maps JavaScript API टाइल ओवरले में रेंडर करता है.

खास जानकारी

Maps JavaScript API, भौगोलिक जानकारी दिखाने के लिए, KML और GeoRSS डेटा फ़ॉर्मैट के साथ काम करता है. इन डेटा फ़ॉर्मैट को KmlLayer ऑब्जेक्ट का इस्तेमाल करके मैप पर दिखाया जाता है. इस ऑब्जेक्ट के कन्स्ट्रक्टर में, सार्वजनिक तौर पर ऐक्सेस की जा सकने वाली KML या GeoRSS फ़ाइल का यूआरएल डाला जाता है.

ध्यान दें: Maps JavaScript API में KML ओवरले जनरेट करने वाली KmlLayer क्लास, रेंडर करने के लिए KML फ़ाइलों को वापस पाने और पार्स करने के लिए, Google की होस्ट की गई सेवा का इस्तेमाल करती है. इसलिए, केएमएल फ़ाइलों को सिर्फ़ तब दिखाया जा सकता है, जब उन्हें ऐसे यूआरएल पर होस्ट किया गया हो जिसे सार्वजनिक तौर पर ऐक्सेस किया जा सकता हो और जिसे ऐक्सेस करने के लिए पुष्टि करने की ज़रूरत न हो.

अगर आपको निजी फ़ाइलों का ऐक्सेस चाहिए, कैश मेमोरी पर बेहतर तरीके से कंट्रोल चाहिए या क्वेरी पैरामीटर के तौर पर ब्राउज़र व्यूपोर्ट को जियोस्पेशल डेटा सर्वर पर भेजना है, तो हमारा सुझाव है कि आप KmlLayer के बजाय डेटा लेयर का इस्तेमाल करें. इससे, उपयोगकर्ताओं के ब्राउज़र को सीधे आपके वेब सर्वर से संसाधनों का अनुरोध करने के लिए निर्देश मिलेगा.

Maps JavaScript API, दिए गए भौगोलिक एक्सएमएल डेटा को KML में बदल देता है. इसे Maps JavaScript API टाइल ओवरले का इस्तेमाल करके मैप पर दिखाया जाता है. यह KML, Maps JavaScript API के ओवरले एलिमेंट की तरह दिखता है और कुछ हद तक उसी तरह काम करता है. KML <Placemark> और GeoRSS point एलिमेंट को मार्कर के तौर पर रेंडर किया जाता है. उदाहरण के लिए, <LineString> एलिमेंट को पॉलीलाइन के तौर पर और <Polygon> एलिमेंट को पॉलीगॉन के तौर पर रेंडर किया जाता है. इसी तरह, <GroundOverlay> एलिमेंट को मैप पर आयताकार इमेज के तौर पर रेंडर किया जाता है. हालांकि, यह अहम है कि ये ऑब्जेक्ट, Maps JavaScript API Markers, Polylines, Polygons या GroundOverlays नहीं हैं; इसके बजाय, इन्हें मैप पर एक ऑब्जेक्ट के तौर पर रेंडर किया जाता है.

KmlLayer ऑब्जेक्ट, मैप पर तब दिखते हैं, जब उनकी map प्रॉपर्टी सेट हो जाती है. setMap() passing null को कॉल करके, उन्हें मैप से हटाया जा सकता है. KmlLayer ऑब्जेक्ट, इन चाइल्ड एलिमेंट को रेंडर करने की प्रोसेस को मैनेज करता है. इसके लिए, यह मैप के तय किए गए बॉउंड के लिए, सही सुविधाओं को अपने-आप रीट्रिव करता है. सीमाओं में बदलाव होने पर, मौजूदा व्यूपोर्ट में मौजूद सुविधाएं अपने-आप रेंडर हो जाती हैं.

KmlLayer में मौजूद कॉम्पोनेंट, मांग पर रेंडर किए जाते हैं. इसलिए, इस लेयर की मदद से हज़ारों मार्कर, पॉलीलाइन, और पॉलीगॉन को आसानी से रेंडर किया जा सकता है. ध्यान दें कि इन कॉम्पोनेंट ऑब्जेक्ट को सीधे तौर पर ऐक्सेस नहीं किया जा सकता. हालांकि, इनमें से हर एक क्लिक इवेंट उपलब्ध कराता है, जो उन अलग-अलग ऑब्जेक्ट पर डेटा दिखाता है.

KML लेयर के विकल्प

KmlLayer() कंस्ट्रक्टर, वैकल्पिक तौर पर कई KmlLayerOptions पास करता है:

• map उस Map के बारे में बताता है जिस पर KmlLayer को रेंडर करना है. setMap() तरीके में इस वैल्यू को null पर सेट करके, KmlLayer को छिपाया जा सकता है.
• preserveViewport से पता चलता है कि लेयर दिखाते समय, मैप को KmlLayer के कॉन्टेंट के दायरों के हिसाब से अडजस्ट नहीं किया जाना चाहिए. डिफ़ॉल्ट रूप से, KmlLayer दिखाते समय, लेयर के पूरे कॉन्टेंट को दिखाने के लिए, मैप को ज़ूम करके सही जगह पर ले जाया जाता है.
• suppressInfoWindows से पता चलता है कि KmlLayer में मौजूद क्लिक की जा सकने वाली सुविधाओं से, InfoWindow ऑब्जेक्ट का डिसप्ले ट्रिगर नहीं होना चाहिए.

इसके अलावा, KmlLayer रेंडर होने के बाद, इसमें एक ऐसी metadata प्रॉपर्टी होती है जिसे बदला नहीं जा सकता. इसमें KmlLayerMetadata ऑब्जेक्ट लिटरल में लेयर का नाम, जानकारी, स्निपेट, और लेखक शामिल होता है. getMetadata() तरीके का इस्तेमाल करके, इस जानकारी की जांच की जा सकती है. KmlLayer ऑब्जेक्ट को रेंडर करने के लिए, किसी बाहरी सर्वर के साथ असाइनोक्रोनस तरीके से कम्यूनिकेट करना ज़रूरी होता है. इसलिए, आपको metadata_changed इवेंट को सुनना होगा. इससे यह पता चलेगा कि प्रॉपर्टी में डेटा भर दिया गया है.

नीचे दिए गए उदाहरण में, दिए गए GeoRSS फ़ीड से KmlLayer बनाया गया है:

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

यहां दिए गए उदाहरण में, दिए गए KML फ़ीड से KmlLayer बनाया गया है:

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 सुविधा की जानकारी

KML में कई सुविधाएं शामिल हो सकती हैं. इसलिए, हो सकता है कि आप सीधे KmlLayer ऑब्जेक्ट से सुविधा का डेटा ऐक्सेस न कर पाएं. इसके बजाय, सुविधाओं को दिखाने के लिए, उन्हें क्लिक किए जा सकने वाले Maps JavaScript API ओवरले की तरह रेंडर किया जाता है. अलग-अलग सुविधाओं पर क्लिक करने से, डिफ़ॉल्ट रूप से एक InfoWindow दिखता है. इसमें, उस सुविधा के बारे में KML <title> और <description> जानकारी होती है. इसके अलावा, किसी KML फ़ीचर पर क्लिक करने से एक KmlMouseEvent जनरेट होता है, जो यह जानकारी पास करता है:

• position से पता चलता है कि इस KML सुविधा के लिए, InfoWindow को किस अक्षांश/देशांतर निर्देशांक पर ऐंकर करना है. आम तौर पर, यह पोज़िशन पॉलीगॉन, पॉलीलाइन, और ग्राउंडओवर के लिए क्लिक की गई जगह होती है. हालांकि, मार्कर के लिए यह असल ऑरिजिन होती है.
• pixelOffset, InfoWindow के “टेल” को ऐंकर करने के लिए, ऊपर दिए गए position से ऑफ़सेट दिखाता है. पॉलीगॉनल ऑब्जेक्ट के लिए, यह ऑफ़सेट आम तौर पर 0,0 होता है. हालांकि, मार्कर के लिए इसमें मार्कर की ऊंचाई शामिल होती है.
• featureData में KmlFeatureData का JSON स्ट्रक्चर शामिल है.

KmlFeatureData ऑब्जेक्ट का सैंपल यहां दिया गया है:

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

नीचे दिए गए उदाहरण में, KML सुविधा <Description> पर क्लिक करने पर, साइड <div> में टेक्स्ट दिखता है:

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 रेंडरिंग के लिए साइज़ और जटिलता से जुड़ी पाबंदियां

Maps JavaScript API में, लोड की गई KML फ़ाइलों के साइज़ और मुश्किली से जुड़ी सीमाएं हैं. मौजूदा सीमाओं की खास जानकारी यहां दी गई है.

ध्यान दें: इन सीमाओं में कभी भी बदलाव किया जा सकता है.

प्राप्त अधिकतम फ़ाइल आकार (सामान्य KML, सामान्य GeoRSS, या संपीडित KMZ)

3 एमबी

अधिकतम असंपीडित KML फ़ाइल आकार

10 एमबी

KMZ फ़ाइलों में, कंप्रेस न की गई इमेज फ़ाइल का ज़्यादा से ज़्यादा साइज़

हर फ़ाइल 500 केबी से ज़्यादा नहीं होनी चाहिए

नेटवर्क लिंक की ज़्यादा से ज़्यादा संख्या

10

पूरे दस्तावेज़ में अधिकतम विशेषताओं की संख्या

1,000

KML लेयर की संख्या

किसी एक Google Maps पर, जितनी KML लेयर दिखाई जा सकती हैं उनकी संख्या तय होती है. इस सीमा से ज़्यादा लेयर जोड़ने पर, मैप पर आपकी कोई भी लेयर नहीं दिखेगी. साथ ही, आपके वेब ब्राउज़र के JavaScript कंसोल में गड़बड़ी की सूचना दी जाएगी. यह सीमा, बनाई गई KmlLayer क्लास की संख्या और उन लेयर को बनाने के लिए इस्तेमाल किए गए सभी यूआरएल की कुल लंबाई के आधार पर तय की जाती है. आपके बनाए गए हर नए KmlLayer लेयर के लिए, तय सीमा का एक हिस्सा इस्तेमाल होगा. साथ ही, यूआरएल की लंबाई के आधार पर, तय सीमा का एक और हिस्सा भी इस्तेमाल होगा. इसलिए, हर ऐप्लिकेशन के हिसाब से लेयर जोड़ी जा सकती हैं. औसतन, सीमा के बिना 10 से 20 लेयर लोड की जा सकती हैं. अगर अब भी यह सीमा पूरी हो जाती है, तो KML यूआरएल को छोटा करने के लिए, यूआरएल छोटा करने वाले टूल का इस्तेमाल करें. इसके अलावा, एक ऐसी KML फ़ाइल बनाएं जिसमें अलग-अलग KML यूआरएल के लिए, NetworkLinks शामिल हों.

परफ़ॉर्मेंस और कैश मेमोरी में सेव करने से जुड़ी बातें

आपके सर्वर पर लोड कम करने के लिए, Google के सर्वर कुछ समय के लिए KML फ़ाइलों को कैश मेमोरी में सेव कर लेंगे. इससे आपके उपयोगकर्ताओं के लिए परफ़ॉर्मेंस भी बेहतर होगी. ऐसा इसलिए, क्योंकि आपकी KML फ़ाइल के सही सेगमेंट को कम जगह में दिखाया जाएगा. ऐसा तब होगा, जब उपयोगकर्ता मैप पर क्लिक करेंगे, पैन करेंगे, और ज़ूम करेंगे.

बेहतर परफ़ॉर्मेंस के लिए, हमारा सुझाव है कि:

• KML में सही <expires> टैग का इस्तेमाल करें.
  
  KmlLayer, KML फ़ाइलों को कैश मेमोरी में सेव करने का तरीका तय करते समय, एचटीटीपी हेडर का इस्तेमाल नहीं करेगा.
• अनुरोध के समय, फ़ाइलों को डाइनैमिक तौर पर जनरेट न करें.
  
  इसके बजाय, फ़ाइलों को ज़रूरत पड़ने से पहले जनरेट करें और उन्हें स्टैटिक तौर पर दिखाएं. अगर आपके सर्वर को KML फ़ाइल को ट्रांसमिट करने में काफ़ी समय लगता है, तो हो सकता है कि KmlLayer न दिखे.
• कैश मेमोरी को तब तक बायपास न करें, जब तक आपको यह पक्का पता न हो कि आपकी फ़ाइल अपडेट हो गई है.
  
  हमेशा कैश मेमोरी को बायपास करने से (उदाहरण के लिए, क्वेरी पैरामीटर के तौर पर कोई रैंडम नंबर या उपयोगकर्ता के घड़ी का समय जोड़कर) आपके सर्वर पर आसानी से लोड बढ़ सकता है. ऐसा तब होता है, जब आपकी साइट अचानक लोकप्रिय हो जाती है और बड़ी KML फ़ाइलें दिखाई जाती हैं.
  
  अगर किसी उपयोगकर्ता की घड़ी गलत है और <expires> टैग सही तरीके से सेट नहीं किया गया है, तो कैश मेमोरी की वजह से उपयोगकर्ताओं को पुराना डेटा भी दिख सकता है.
  
  इसके बजाय, अपडेट की गई स्टैटिक फ़ाइलों को नए और अलग-अलग रिविज़न नंबर के साथ पब्लिश करें. साथ ही, KmlLayer को पास किए गए यूआरएल को मौजूदा वर्शन के साथ डाइनैमिक तौर पर अपडेट करने के लिए, सर्वर-साइड कोड का इस्तेमाल करें.
• अपनी KML फ़ाइलों में हर मिनट में एक बार से ज़्यादा बदलाव न करें.
  
  अगर सभी फ़ाइलों का साइज़ (बिना कंप्रेस किए) 1 एमबी से ज़्यादा है, तो यह सीमा हर पांच मिनट में एक बार बदलती है.
• जियोस्पेशियल डेटा सर्वर का इस्तेमाल करते समय, लेयर के व्यूपोर्ट को सीमित करने के लिए, क्वेरी पैरामीटर का इस्तेमाल करने से बचें.
  
  इसके बजाय, bounds_changed इवेंट की मदद से मैप व्यूपोर्ट को सीमित किया जा सकता है. उपयोगकर्ताओं को सिर्फ़ वे सुविधाएं भेजी जाएंगी जो अपने-आप दिख सकती हैं.
  
  अगर आपके जियोस्पेशियल डेटा सर्वर में बहुत ज़्यादा डेटा है, तो इसके बजाय डेटा लेयर का इस्तेमाल करें.
• जियोस्पेशियल डेटा सर्वर का इस्तेमाल करते समय, अलग-अलग क्वेरी पैरामीटर वाले एक KmlLayer के बजाय, उन सुविधाओं के हर ग्रुप के लिए कई KmlLayer का इस्तेमाल करें जिन्हें आपको उपयोगकर्ताओं को टॉगल करने की अनुमति देनी है.
• फ़ाइल का साइज़ कम करने के लिए, कंप्रेस की गई KMZ फ़ाइलों का इस्तेमाल करें.
• अगर Google Cloud Storage या किसी दूसरे क्लाउड स्टोरेज का इस्तेमाल किया जा रहा है, तो ऐक्सेस कंट्रोल लागू करने के लिए, हस्ताक्षर किए गए यूआरएल या अस्थायी टोकन जैसी सुविधाओं का इस्तेमाल करने से बचें. इनकी वजह से, कैश मेमोरी में सेव किए जाने की प्रोसेस को अनजाने में रोका जा सकता है.
• सभी पॉइंट की सटीकता को कम करके, ज़रूरत के मुताबिक सटीक बनाएं.
• पॉलीगॉन और पॉलीलाइन जैसी मिलती-जुलती फ़ीचर की ज्यामिति को मर्ज और आसान बनाएं.
• इस्तेमाल नहीं किए गए एलिमेंट या इमेज रिसॉर्स हटाएं.
• इस्तेमाल नहीं किए जा सकने वाले एलिमेंट हटाएं.

अगर आपको निजी डेटा ऐक्सेस करना है, कैश मेमोरी में सेव होने से रोकना है या ब्राउज़र व्यूपोर्ट को क्वेरी पैरामीटर के तौर पर किसी जियोस्पेशल डेटा सर्वर पर भेजना है, तो हमारा सुझाव है कि आप KmlLayer के बजाय डेटा लेयर का इस्तेमाल करें. इससे, उपयोगकर्ताओं के ब्राउज़र सीधे आपके वेब सर्वर से संसाधनों का अनुरोध करेंगे.

काम करने वाले KML एलिमेंट

Maps JavaScript API, इन KML एलिमेंट के साथ काम करता है. सामान्य रूप से, समझ नहीं आने पर KML पार्सर, XML टैग को चुपचाप अनदेखा करता है.

• प्लेसमार्क
• आइकन
• फ़ोल्डर
• जानकारी देने वाला एचटीएमएल—<BalloonStyle> और <text> की मदद से इकाई बदलना
• KMZ (संलग्न चित्र सहित संपीडित KML)
• बहुरेखा तथा बहुभुज
• रंग, भराव तथा अपारदर्शिता सहित बहुरेखाओं व बहुभुजों के लिए शैलियां
• डेटा को डायनॉमिक तरीके से आयात करने के लिए नेटवर्क लिंक
• ग्राउंड ओवरले तथा स्क्रीन ओवरले

यहां दी गई टेबल में, काम करने वाले KML एलिमेंट के बारे में पूरी जानकारी दी गई है.