طبقات KML وGeoRSS

يعرض KmlLayer عناصر KML وGeoRSS في ملف KmlLayer كشريحة مركبة في واجهة برمجة التطبيقات Maps JavaScript API.

نظرة عامة

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

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

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

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

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

بما أنّه يتم عرض المكوّنات ضمن 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 قد يتضمّن عددًا كبيرًا من العناصر، قد لا تتمكّن من الوصول إلى data من عنصر KmlLayer مباشرةً. وبدلاً من ذلك، أثناء عرض الميزات، يتم عرضها لتبدو مثل العناصر التي يمكن النقر عليها في واجهة برمجة التطبيقات JavaScript لـ "خرائط Google". يؤدي النقر على ميزات فردية تلقائيًا إلى عرض InfoWindow يحتوي على <title> KML و <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"
}

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

هناك حدّ أقصى لعدد طبقات 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 المتوافقة

تتيح Maps JavaScript API عناصر KML التالية. يتجاهل المحلل اللغوي لـ KML عادة علامات XML التي لا يفهمها.

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

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