لایه های KML و GeoRSS

KmlLayer عناصر KML و GeoRSS را به یک همپوشانی کاشی API جاوا اسکریپت Maps تبدیل می کند.

نمای کلی

Maps JavaScript API از فرمت های داده های KML و GeoRSS برای نمایش اطلاعات جغرافیایی پشتیبانی می کند. این قالب‌های داده با استفاده از یک شی KmlLayer ، که سازنده آن URL یک فایل KML یا GeoRSS در دسترس عموم را می‌گیرد، روی نقشه نمایش داده می‌شود.

توجه: کلاس KmlLayer که همپوشانی های KML را در Maps JavaScript API ایجاد می کند از یک سرویس میزبانی شده Google برای بازیابی و تجزیه فایل های KML برای رندر استفاده می کند. در نتیجه، نمایش فایل‌های KML تنها در صورتی امکان‌پذیر است که آن‌ها در یک URL در دسترس عموم میزبانی شوند که برای دسترسی به احراز هویت نیازی ندارد.

اگر به دسترسی به فایل‌های خصوصی، کنترل دقیق روی حافظه‌های پنهان، یا ارسال نمای مرورگر به سرور داده‌های مکانی به عنوان پارامتر جستجو نیاز دارید، توصیه می‌کنیم به جای KmlLayer از لایه‌های داده استفاده کنید. با این کار مرورگرهای کاربران شما مستقیماً از سرور وب شما درخواست منابع می کنند.

Maps JavaScript API داده های XML جغرافیایی ارائه شده را به یک نمایش KML تبدیل می کند که با استفاده از همپوشانی کاشی Maps JavaScript API روی نقشه نمایش داده می شود. این KML به نظر می رسد (و تا حدودی رفتار می کند) مانند عناصر همپوشانی Maps JavaScript API آشنا. عناصر point KML <Placemark> و GeoRSS به عنوان نشانگر ارائه می شوند، برای مثال، عناصر <LineString> به صورت چند خط و عناصر <Polygon> به صورت چند ضلعی ارائه می شوند. به طور مشابه، عناصر <GroundOverlay> به صورت تصاویر مستطیلی بر روی نقشه ارائه می شوند. با این حال، نکته مهم این است که این اشیاء Markers Maps JavaScript API، Polylines ، Polygons یا GroundOverlays نیستند . در عوض، آنها به یک شیء واحد روی نقشه تبدیل می شوند.

اشیاء KmlLayer پس از تنظیم ویژگی map آنها روی نقشه ظاهر می شوند. می توانید با فراخوانی setMap() و passing null آنها را از نقشه حذف کنید. شی KmlLayer رندر این عناصر فرزند را با بازیابی خودکار ویژگی های مناسب برای محدوده های داده شده نقشه مدیریت می کند. با تغییر مرزها، ویژگی‌ها در نمای فعلی به طور خودکار ارائه می‌شوند.

از آنجایی که اجزای یک KmlLayer بر حسب تقاضا رندر می شوند، این لایه به شما اجازه می دهد تا به راحتی رندر هزاران نشانگر، چند خط و چند ضلعی را مدیریت کنید. توجه داشته باشید که نمی‌توانید مستقیماً به این اشیاء تشکیل دهنده دسترسی پیدا کنید، اگرچه هر کدام رویدادهای کلیکی را ارائه می‌کنند که داده‌ها را روی آن اشیاء مجزا برمی‌گرداند.

گزینه های لایه KML

سازنده KmlLayer() به صورت اختیاری تعدادی KmlLayerOptions را ارسال می کند:

• map Map را مشخص می کند که روی آن KmlLayer رندر شود. با تنظیم این مقدار در متد setMap() می‌توانید یک KmlLayer را مخفی null .
• preserveViewport مشخص می کند که هنگام نمایش لایه، نقشه نباید با محدوده محتوای KmlLayer تنظیم شود. به‌طور پیش‌فرض، هنگام نمایش KmlLayer ، نقشه بزرگ‌نمایی می‌شود و در موقعیتی قرار می‌گیرد که کل محتوای لایه را نشان دهد.
• suppressInfoWindows نشان می دهد که ویژگی های قابل کلیک در KmlLayer نباید نمایش اشیاء InfoWindow را فعال کنند.

علاوه بر این، هنگامی که KmlLayer رندر شد، حاوی یک ویژگی metadata تغییرناپذیر است که شامل نام، توضیحات، قطعه و نویسنده لایه در یک شیء KmlLayerMetadata به معنای واقعی کلمه است. می توانید این اطلاعات را با استفاده از متد getMetadata() بررسی کنید. از آنجایی که رندر کردن اشیاء KmlLayer نیاز به ارتباط ناهمزمان با یک سرور خارجی دارد، می‌خواهید به رویداد metadata_changed گوش دهید، که نشان می‌دهد ویژگی پر شده است.

مثال زیر یک KmlLayer را از فید GeoRSS می سازد:

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

مثال زیر یک KmlLayer از فید KML داده شده می سازد:

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 به نظر می‌رسند. با کلیک بر روی ویژگی های فردی، به طور پیش فرض، یک InfoWindow حاوی اطلاعات KML <title> و <description> در مورد ویژگی داده شده ظاهر می شود. علاوه بر این، با کلیک بر روی یک ویژگی KML یک KmlMouseEvent ایجاد می‌شود که اطلاعات زیر را ارسال می‌کند:

• position مختصات طول و عرض جغرافیایی را نشان می دهد که در آن InfoWindow برای این ویژگی KML لنگر می زند. این موقعیت عموماً مکانی است که برای چند ضلعی ها، چندخطوط و روکش های زمین کلیک می شود، اما منشا واقعی نشانگرها است.
• pixelOffset فاصله را از position بالا برای لنگر انداختن "دم" InfoWindow نشان می دهد. برای اشیاء چند ضلعی، این افست معمولاً 0,0 است اما برای نشانگرها شامل ارتفاع نشانگر می شود.
• featureData شامل ساختار JSON KmlFeatureData است.

نمونه شیء KmlFeatureData در زیر نشان داده شده است:

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

مثال زیر وقتی روی ویژگی کلیک می‌شود، متن <Description> ویژگی KML را در یک سمت <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

حداکثر تعداد کل ویژگی های سند

1000

تعداد لایه های KML

محدودیتی در تعداد لایه های KML وجود دارد که می توانند در یک نقشه گوگل نمایش داده شوند. اگر از این حد تجاوز کنید، هیچ یک از لایه‌های شما روی نقشه ظاهر نمی‌شود و خطایی در کنسول جاوا اسکریپت مرورگر وب شما گزارش می‌شود. این محدودیت بر اساس ترکیبی از تعداد کلاس های KmlLayer ایجاد شده و طول کل همه URL های استفاده شده برای ایجاد آن لایه ها است. هر KmlLayer جدیدی که ایجاد می‌کنید، بسته به طول URL که فایل KML از آنجا بارگذاری شده است، بخشی از محدودیت لایه و بخش دیگری از محدودیت را اشغال می‌کند. در نتیجه، تعداد لایه‌هایی که می‌توانید اضافه کنید بسته به برنامه متفاوت است. به طور متوسط، شما باید بتوانید بین 10 تا 20 لایه را بدون رسیدن به حد مجاز بارگذاری کنید. اگر همچنان به حد مجاز رسیدید، از کوتاه کننده URL برای کوتاه کردن URL های KML استفاده کنید. از طرف دیگر، یک فایل KML منفرد متشکل از NetworkLinks به URL های فردی KML ایجاد کنید.

ملاحظات مربوط به عملکرد و حافظه پنهان

سرورهای Google به طور موقت فایل های KML را برای کاهش بار روی سرورهای شما کش می کنند. این همچنین با ارائه یک نمایش فضای کارآمد از بخش های مناسب فایل KML شما، عملکرد را برای کاربران شما بهبود می بخشد، زیرا کاربران روی نقشه کلیک می کنند، حرکت می کنند و بزرگنمایی می کنند.

برای بهترین عملکرد، توصیه می کنیم:

• از یک تگ <expires> مناسب در KML استفاده کنید.
  
  KmlLayer از هدرهای HTTP هنگام تصمیم گیری در مورد نحوه ذخیره فایل های KML استفاده نمی کند.
• در زمان درخواست فایل ها را به صورت پویا تولید نکنید.
  
  در عوض، فایل‌ها را قبل از نیاز ایجاد کنید و آنها را به صورت ایستا سرو کنید. اگر سرور شما مدت زیادی طول بکشد تا فایل KML را منتقل کند، KmlLayer ممکن است نمایش داده نشود.
• سعی نکنید کش ها را دور بزنید مگر اینکه به طور قطعی بدانید که فایل شما به روز شده است.
  
  دور زدن حافظه پنهان (مثلاً با اضافه کردن یک عدد تصادفی یا زمان ساعت کاربر به عنوان پارامتر پرس و جو) می تواند به راحتی باعث شود که سرورهای شما در صورتی که سایت شما به طور ناگهانی محبوب شود و فایل های KML بزرگی را ارائه می دهید، غرق شوند.
  
  همچنین می‌تواند باعث شود که حافظه پنهان داده‌های قدیمی را به کاربران ارائه دهد، اگر ساعت هر کاربر نادرست باشد و تگ <expires> به درستی تنظیم نشده باشد.
  
  در عوض، فایل‌های استاتیک به‌روزرسانی‌شده را با یک شماره ویرایش جدید و مجزا منتشر کنید و از کد سمت سرور برای به‌روزرسانی پویا URL ارسال شده به KmlLayer با نسخه فعلی استفاده کنید.
• تغییرات فایل های KML خود را به یک بار در دقیقه محدود کنید.
  
  اگر حجم همه فایل‌ها بیش از 1 مگابایت باشد (غیر فشرده)، تغییرات را به یک بار در 5 دقیقه محدود کنید.
• هنگام استفاده از سرور داده های مکانی، از استفاده از پارامترهای پرس و جو برای محدود کردن نمای لایه ها اجتناب کنید.
  
  در عوض، می‌توانید نمای نقشه را با رویداد bounds_changed محدود کنید. فقط ویژگی هایی برای کاربران ارسال می شود که می توانند به طور خودکار نمایش داده شوند.
  
  اگر مقدار زیادی داده در سرور داده های مکانی شما وجود دارد، به جای آن از لایه های داده استفاده کنید.
• هنگام استفاده از سرور داده‌های مکانی، از چندین KmlLayer برای هر گروه از ویژگی‌هایی که می‌خواهید به کاربران اجازه تغییر آن‌ها را بدهید، به جای یک KmlLayer منفرد با پارامترهای جستجوی مختلف، استفاده کنید.
• برای کاهش حجم فایل از فایل های KMZ فشرده استفاده کنید.
• اگر از Google Cloud Storage یا راه‌حل ذخیره‌سازی ابری دیگری استفاده می‌کنید، از استفاده از ویژگی‌هایی مانند نشانی‌های اینترنتی امضا شده یا نشانه‌های موقت برای اعمال کنترل‌های دسترسی خودداری کنید . اینها می توانند به طور ناخواسته از کش کردن جلوگیری کنند.
• دقت تمام نقاط را به دقت مناسب کاهش دهید.
• ادغام و ساده کردن هندسه ویژگی های مشابه، مانند چند ضلعی و چند خطی.
• هر عنصر یا منبع تصویر استفاده نشده را حذف کنید.
• هر عنصر پشتیبانی نشده را حذف کنید.

اگر نیاز به دسترسی به داده های خصوصی، جلوگیری از کش کردن، یا ارسال نمای مرورگر به سرور داده های مکانی به عنوان پارامتر جستجو دارید، توصیه می کنیم به جای KmlLayer از لایه های داده استفاده کنید. با این کار مرورگرهای کاربران شما مستقیماً از سرور وب شما درخواست منابع می کنند.

عناصر KML پشتیبانی شده

Maps JavaScript API از عناصر KML زیر پشتیبانی می کند. تجزیه‌کننده KML معمولاً تگ‌های XML را که متوجه نمی‌شود نادیده می‌گیرد.

• مکان‌ها
• نمادها
• پوشه ها
• HTML توصیفی - جایگزینی نهاد از طریق <BalloonStyle> و <text>
• KMZ (KML فشرده، شامل تصاویر پیوست شده)
• چند خط و چند ضلعی
• سبک برای چند خط و چند ضلعی، از جمله رنگ، پر کردن، و کدورت
• پیوندهای شبکه برای وارد کردن داده ها به صورت پویا
• روکش های زمینی و روکش های صفحه نمایش

جدول زیر جزئیات کامل عناصر KML پشتیبانی شده را نشان می دهد.