KML और GeoRSS लेयर

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

खास जानकारी

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

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

अगर आपको निजी फ़ाइलों का ऐक्सेस चाहिए, कैश मेमोरी का बेहतर कंट्रोल चाहिए या ब्राउज़र व्यूपोर्ट को जियोस्पेशियल डेटा सर्वर पर क्वेरी पैरामीटर के तौर पर भेजना है, तो हमारा सुझाव है कि आप 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 नहीं हैं. इसके बजाय, इन्हें मैप पर एक ही ऑब्जेक्ट में रेंडर किया जाता है.

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

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

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

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

• map से उस Map के बारे में पता चलता है जिस पर KmlLayer को रेंडर करना है. KmlLayer को छिपाने के लिए, setMap() तरीके में इस वैल्यू को null पर सेट करें.
• 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"
}

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

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

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

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

सबसे अच्छी परफ़ॉर्मेंस के लिए, हमारा सुझाव है कि आप:

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

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

इस्तेमाल किए जा सकने वाले KML एलिमेंट

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

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

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