طبقات KML وGeoRSS

تعرض KmlLayer عناصر KML وGeoRSS في شكل تراكب مربّعات واجهة برمجة تطبيقات JavaScript للخرائط

نظرة عامة

تتوافق واجهة برمجة تطبيقات JavaScript للخرائط مع تنسيقات بيانات KML وGeoRSS لعرض المعلومات الجغرافية يتم عرض تنسيقات البيانات هذه على باستخدام كائن KmlLayer، تأخذ دالته الإنشائية عنوان URL ملف KML أو GeoRSS متاح للجميع.

ملاحظة: الفئة KmlLayer التي إنشاء طبقات KML في واجهة برمجة تطبيقات JavaScript للخرائط خدمة تستضيفها Google لاسترداد ملفات KML وتحليلها من أجل عرضها. وبالتالي، لا يمكن عرض ملفات KML إلا إذا كانت مستضافة على عنوان URL متاح للجميع ولا يتطلب المصادقة للوصول إليه.

إذا كنت بحاجة إلى الوصول إلى ملفات خاصة، أو حتى التحكم الدقيق في ذاكرات التخزين المؤقت إرسال إطار عرض المتصفح إلى خادم بيانات جغرافية مكانية كمعلمة طلب بحث، ننصح باستخدام البيانات طبقات بدلاً من KmlLayer. سيؤدي هذا إلى توجيه زيارات المستخدمين المتصفحات لطلب الموارد مباشرة من خادم الويب.

تعمل واجهة برمجة تطبيقات JavaScript للخرائط على تحويل المواقع الجغرافية بيانات XML إلى تمثيل KML يتم عرضه على الخريطة باستخدام تراكب مربّعات واجهة برمجة تطبيقات JavaScript للخرائط يبدو ملف KML هذا (ويتصرف نوعًا ما) مثل واجهة برمجة تطبيقات JavaScript المألوفة للخرائط وعناصر التراكب. KML <Placemark> وGeoRSS point كعلامات، فعلى سبيل المثال، عناصر <LineString> هي التي يتم عرضها على شكل خطوط متعددة، كما يتم عرض عناصر <Polygon> على شكل مضلّعات. وبالمثل، فإن عناصر <GroundOverlay> كصور مستطيلة على الخريطة. ومع ذلك، من المهم أن تكون هذه الكائنات ليست واجهة برمجة تطبيقات JavaScript للخرائط Markers، Polylines أو Polygons أو GroundOverlays وبدلاً من ذلك، يتم عرضها في كائن واحد على الخريطة.

تظهر KmlLayer عناصر على الخريطة بعد map. تم تعيين خاصيته. يمكنك إزالتها من الخريطة عن طريق الاتصال تم تجاوز setMap() مسافة null. KmlLayer عرض هذه العناصر الفرعية عن طريق استرداد الخصائص المناسبة لحدود الخريطة. نظرًا لأن العمود تتغير الحدود، يتم تلقائيًا تغيير العناصر في إطار العرض الحالي المعروضة.

ولأنّ المكوّنات ضمن KmlLayer يتم عرضها عند الطلب، تتيح لك الطبقة إدارة عرض الآلاف من العلامات بسهولة، والخطوط المتعددة والمضلّعات. تجدر الإشارة إلى أنه لا يمكنك الوصول إلى هذه الأقسام مباشرةً، على الرغم من أن كل منها يقدم أحداث النقر التي تعرض بيانات هذه الكائنات الفردية.

خيارات طبقة KML

تمرر الدالة الإنشائية KmlLayer() بشكل اختياري عددًا من KmlLayerOptions:

• map يحدد Map الذي سيتم عرض KmlLayer يمكنك إخفاء KmlLayer من خلال ضبط هذا الإعداد إلى null ضمن طريقة setMap().
• 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 مباشرةً. بدلاً من ذلك، ميزات مختلفة، يتم عرضها لتبدو كأنها قابلة للنقر تراكبات API للخرائط يؤدي النقر على كل ميزة على حدة تلقائيًا إلى إظهار InfoWindow يحتوي على KML <title> و <description> من المعلومات حول الميزة المحددة. فضلاً عن ذلك، تؤدي النقرة على ميزة KML إلى إنشاء KmlMouseEvent، الذي يجتاز المعلومات التالية:

• تشير position إلى إحداثيات خط العرض/خط الطول في لتحديد InfoWindow لميزة KML هذه. هذا النمط بشكل عام هو الموقع الذي تم النقر عليه للمضلّعات والخطوط المتعددة GroundOverlays، ولكن المصدر الحقيقي للعلامات.
• تشير القيمة 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"
}

يعرض المثال التالي ميزة 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

تفرض واجهة برمجة تطبيقات JavaScript للخرائط قيودًا على حجم مدى تعقيد ملفات KML التي تم تحميلها. في ما يلي ملخّص للحدود الحالية.

ملاحظة: تخضع هذه الحدود للتغيير في أي وقت الوقت.

جلب الحد الأقصى من حجم الملف (KML غير منسق، أو GeoRSS غير منسق، أو KMZ مضغوط)

3 ميغابايت

الحد الأقصى لحجم ملف KML غير مضغوط

10 ميغابايت

الحد الأقصى لحجم ملف الصور غير المضغوط في ملفات KMZ

500 كيلوبايت لكل ملف

الحد الأقصى لعدد روابط الشبكة

10

الحد الأقصى للعدد الإجمالي للميزات على مستوى المستند بأكمله

1,000

عدد طبقات KML

هناك حد لعدد طبقات KML التي يمكن على خريطة Google واحدة. إذا تجاوزت هذا الحد، لن تكون ستظهر الطبقات على الخريطة، وسيتم الإبلاغ عن خطأ في الويب وحدة تحكم JavaScript في المتصفح. ويستند هذا الحدّ إلى تركيبة من عدد الصفوف التي تم إنشاؤها (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 أو خدمة أخرى للتخزين في السحابة الإلكترونية، تجنب استخدام ميزات مثل عناوين URL الموقَّعة أو الرموز المميّزة المؤقتة لفرض عناصر التحكّم في الوصول يمكن أن منع التخزين المؤقت بدون قصد.
• قلّل دقة جميع النقاط إلى بالدقة المناسبة.
• دمج الأشكال الهندسية لخصائص متشابهة وتبسيطها، مثل المضلّعات والخطوط المتعددة.
• أزِل أي عناصر أو موارد صور غير مستخدَمة.
• أزِل أي عناصر غير متوافقة.

إذا كنت بحاجة إلى الوصول إلى بيانات خاصة، أو منع التخزين المؤقت، أو إرسال المتصفح إطار العرض إلى خادم بيانات جغرافية مكانية كمعلمة طلب البحث، نوصي باستخدام طبقات بيانات بدلاً من KmlLayer سيؤدي هذا إلى توجيه زيارات المستخدمين المتصفحات إلى لطلب الموارد من خادم الويب.

عناصر KML المتوافقة

تدعم واجهة برمجة تطبيقات JavaScript للخرائط عناصر KML التالية. يتجاهل المحلل اللغوي لـ KML عادة علامات XML التي لا يفهمها.

• علامات موضعية
• الرموز
• المجلدات
• HTML وصفي: استبدال الكيان عبر <BalloonStyle> أو &lt;text&gt;
• KMZ‏ (KML مضغوط، بما في ذلك الصور المرفقة)
• الخطوط المتعددة والمضلعات
• نمط الخطوط المتعددة والمضلعات، بما في ذلك اللون، والتعبئة، والتعتيم
• روابط الشبكة لاستيراد البيانات ديناميكيًا
• تراكبات الأرض وتراكبات الشاشة

يقدم الجدول التالي تفاصيل كاملة عن عناصر KML المتوافقة.