عرض بيانات KML

نظرة عامة

يوضّح لك هذا البرنامج التعليمي كيفية عرض معلومات ملف KML في خريطة Google وشريط جانبي. لمزيد من المعلومات حول استخدام ملفات KML في الخرائط، يمكنك الاطّلاع على دليل طبقات KML. جرِّب النقر على محدّد على الخريطة أدناه للاطّلاع على البيانات في الشريط الجانبي.

يعرض القسم أدناه الرمز الكامل الذي تحتاج إليه لإنشاء الخريطة والشريط الجانبي.

var map;
var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });

  var kmlLayer = new google.maps.KmlLayer(src, {
    suppressInfoWindows: true,
    preserveViewport: false,
    map: map
  });
  kmlLayer.addListener('click', function(event) {
    var content = event.featureData.infoWindowHtml;
    var testimonial = document.getElementById('capture');
    testimonial.innerHTML = content;
  });
}
 
<div id="map"></div>
<div id="capture"></div>
 
html, body {
  height: 370px;
  padding: 0;
  margin: 0;
  }
#map {
 height: 360px;
 width: 300px;
 overflow: hidden;
 float: left;
 border: thin solid #333;
 }
#capture {
 height: 360px;
 width: 480px;
 overflow: hidden;
 float: left;
 background-color: #ECECFB;
 border: thin solid #333;
 border-left: none;
 }
 
<!-- Replace the value of the key parameter with your own API key. -->
<script async
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

جرِّب هذه الميزة بنفسك

يمكنك تجربة هذا الرمز في JSFiddle من خلال النقر على الرمز <> في أعلى يسار نافذة الرمز.

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no">
    <meta charset="utf-8">
    <title>KML Click Capture Sample</title>
    <style>
      html, body {
        height: 370px;
        padding: 0;
        margin: 0;
        }
      #map {
       height: 360px;
       width: 300px;
       overflow: hidden;
       float: left;
       border: thin solid #333;
       }
      #capture {
       height: 360px;
       width: 480px;
       overflow: hidden;
       float: left;
       background-color: #ECECFB;
       border: thin solid #333;
       border-left: none;
       }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <div id="capture"></div>
    <script>
      var map;
      var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: new google.maps.LatLng(-19.257753, 146.823688),
          zoom: 2,
          mapTypeId: 'terrain'
        });

        var kmlLayer = new google.maps.KmlLayer(src, {
          suppressInfoWindows: true,
          preserveViewport: false,
          map: map
        });
        kmlLayer.addListener('click', function(event) {
          var content = event.featureData.infoWindowHtml;
          var testimonial = document.getElementById('capture');
          testimonial.innerHTML = content;
        });
      }
    </script>
    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
  </body>
</html>

البدء

في ما يلي مراحل إنشاء الخريطة والشريط الجانبي لهذا البرنامج التعليمي:

  1. إعداد ملف KML
  2. عرض KMLlayer
  3. عرض البيانات في الشريط الجانبي

إعداد ملف KML للاستيراد

يجب أن يتوافق ملف KML مع معيار KML. للحصول على تفاصيل حول هذا المعيار، يُرجى الرجوع إلى موقع Open Geospatial Consortium الإلكتروني. توضّح مستندات KML من Google أيضًا اللغة، وتوفّر مرجعًا ومستندات مفاهيمية للمطوّرين.

إذا كنت في بداية التعلّم وليس لديك ملف KML، يمكنك إجراء ما يلي:

  • استخدِم ملف KML التالي لهذا البرنامج التعليمي:

    https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml

  • ابحث عن ملف KML على الويب. يمكنك استخدام عامل تشغيل البحث filetype من Google.

    استبدِل velodromes بأي عبارة بحث، أو احذف العبارة بالكامل للعثور على جميع ملفات KML.

إذا كنت تنشئ ملفك الخاص، يفترض الرمز البرمجي في هذا المثال ما يلي:

  • استضفت الملف بشكل علني على الإنترنت. هذا شرط أساسي لجميع التطبيقات التي تحمّل ملفات KML إلى KMLLayer، وذلك لكي تتمكّن خوادم Google من العثور على المحتوى واسترداده لعرضه على الخريطة.
  • يجب ألا يكون الملف مضمَّنًا في صفحة محمية بكلمة مرور.
  • تحتوي عناصرك على محتوى نافذة المعلومات. يمكنك تضمين هذا المحتوى في العنصر description أو تضمينه باستخدام العنصر ExtendedData واستبدال الكيان (اطّلِع على مزيد من المعلومات أدناه). ويمكن الوصول إلى كليهما كسمة infoWindowHtml الخاصة بالعنصر.

عناصر ExtendedData

يتضمّن ملف KML في هذا البرنامج التعليمي معلومات حول الميزات في عنصر ExtendedData. لإضافة هذه المعلومات إلى وصف الميزة، استخدِم استبدال العنصر، وهو في الأساس متغيّر في العلامة BalloonStyle.

يوضّح الجدول أدناه الرمز البرمجي لهذا القسم.

الرمز والوصف 
<Style id="west_campus_style">
  <IconStyle>
    <Icon>
      <href>https://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png
      </href>
    </Icon>
  </IconStyle>
  <BalloonStyle>
    <text>$[video]</text>
  </BalloonStyle>
</Style>
يحتوي ملف KML على عنصر Style واحد يتم تطبيقه على جميع العلامات المكانية.
يعيّن عنصر Style هذا القيمة #[video] لعنصر النص BalloonStyle.
يطلب تنسيق $[x] من محلّل KML البحث عن عنصر Data باسم video واستخدامه كنص البالون.		 
<Placemark>
    <name>Google West Campus 1</name>
    <styleUrl>#west_campus_style</styleUrl>
    <ExtendedData>
      <Data name="video">
        <value><![CDATA[<iframe width="640" height="360"
          src="https://www.youtube.com/embed/ZE8ODPL2VPI" frameborder="0"
          allowfullscreen></iframe><br><br>]]></value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-122.0914977709329,37.42390182131783,0</coordinates>
    </Point>
</Placemark>
يحتوي كل Placemark على عنصر ExtendedData الذي يتضمّن العنصر Data. لاحظ أنّ كل Placemark يحتوي على عنصر Data واحد يتضمّن سمة اسم بقيمة video.
يستخدم الملف الخاص بهذا البرنامج التعليمي فيديو YouTube المضمّن كقيمة لنص البالون الخاص بكل علامة موضعية.

يمكنك الاطّلاع على مزيد من المعلومات حول استبدال العناصر في فصل إضافة بيانات مخصّصة ضمن مستندات KML.

عرض KMLLayer

إعداد الخريطة

يوضّح هذا الجدول الرمز الخاص بهذا القسم.

الرمز والوصف 
function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });
}
لعرض ملف KML على خريطة، عليك أولاً إنشاء الخريطة.
ينشئ هذا الرمز عنصر "خريطة Google" جديدًا، ويحدد الموقع الجغرافي الذي يجب توسيطه ومستوى التكبير/التصغير، ويربط الخريطة بالعنصر div.
لمزيد من المعلومات حول أساسيات إنشاء خريطة Google، يمكنك الاطّلاع على البرنامج التعليمي حول إضافة خريطة Google إلى موقعك الإلكتروني.

إنشاء KMLLayer

يوضّح هذا الجدول الرمز البرمجي الذي ينشئ KMLLayer.

الرمز والوصف 
var kmlLayer = new google.maps.KmlLayer();
تنشئ هذه السمة عنصر KMLLayer جديدًا لعرض ملف KML.		 
var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';
var kmlLayer = new google.maps.KmlLayer(src, {
  suppressInfoWindows: true,
  preserveViewport: false,
  map: map
});
يضبط منشئ KMLLayer عنوان URL لملف KML. تحدّد أيضًا سمات لكائن KMLLayer تنفّذ ما يلي:
  • تُعلم هذه السمة الطبقة بعدم عرض نافذة معلومات عند النقر عليها.
  • يطلب من الخريطة توسيط المحتوى وتكبيره إلى حجم المربّع المحيط بالطبقة.
  • تضبط هذه السمة الخريطة على عنصر الخريطة الذي تم إنشاؤه سابقًا.
يسرد دليل مرجع واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" جميع الخيارات المتاحة لهذه الطبقة.
حمِّل ملف HTML لعرض محتوى ملف KML كطبقة فوق الخريطة الأساسية. ومع ذلك، لن يؤدي النقر على أي ميزة إلى اتخاذ أي إجراء حتى الآن.

عرض البيانات في الشريط الجانبي

يوضّح هذا القسم الإعدادات التي تعرض محتوى نافذة المعلومات في الشريط الجانبي عند النقر على عنصر في الخريطة. ويتم ذلك من خلال:

  • الاستماع إلى حدث النقر على أي من عناصر KMLLayer
  • الحصول على بيانات الميزة التي تم النقر عليها
  • كتابة هذه البيانات في الشريط الجانبي

إضافة أداة معالجة الأحداث

توفّر &quot;خرائط Google&quot; وظيفة للاستماع إلى أحداث المستخدمين والاستجابة لها على الخريطة، مثل النقرات أو ضغطات مفاتيح لوحة المفاتيح. تضيف هذه السمة أداة معالجة لأحداث click من هذا النوع.

يوضّح الجدول أدناه الرمز البرمجي لهذا القسم.

الرمز والوصف 
kmlLayer.addListener('click', function(event) {});
يركّز متتبّع الأحداث kmlLayer.addListener على ما يلي:
  • نوع الحدث الذي سيتم الاستماع إليه. في هذا البرنامج التعليمي، يكون الحدث هو click.
  • دالة يتم استدعاؤها عند وقوع الحدث.
يمكنك الاطّلاع على مزيد من المعلومات حول الأحداث في دليل المطوّر.

كتابة بيانات عنصر KML في الشريط الجانبي

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

يوضّح الجدول أدناه الرمز البرمجي لهذا القسم.

الرمز والوصف 
var content = event.featureData.infoWindowHtml;
يكتب محتوى نافذة المعلومات إلى متغيّر. 
var testimonial = document.getElementById('capture');
testimonial.innerHTML = content;
تحدّد هذه السمة div الذي سيتم الكتابة إليه، وتستبدل رمز HTML فيه بمحتوى الميزة. 
kmlLayer.addListener('click', function(event) {
  var content = event.featureData.infoWindowHtml;
  var testimonial = document.getElementById('capture');
  testimonial.innerHTML = content;
});
تصبح أسطر الرمز هذه هي الدالة داخل الدالة الإنشائية addListener.

الآن، في كل مرة تنقر فيها على عنصر KML على الخريطة، يتم تعديل الشريط الجانبي لعرض محتوى نافذة المعلومات الخاصة به.

مزيد من المعلومات

مزيد من المعلومات عن استخدام ملفات KML