عرض بيانات 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. عرض طبقة KML
  3. عرض البيانات في الشريط الجانبي

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

يجب أن يتوافق ملف KML مع معيار KML. للحصول على تفاصيل حول هذا المعيار، يُرجى الرجوع إلى موقع الاتحاد الجغرافي المكاني المفتوح. تصف مستندات 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 المضمّن كقيمة لنص بالون كل علامة Placemark.

يمكنك معرفة المزيد من المعلومات حول استبدال الكيان في فصل إضافة البيانات المخصّصة من مستندات 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 إلى موقعك الإلكتروني.

إنشاء طبقة KML

يوضّح هذا الجدول الرمز البرمجي الذي ينشئ طبقة KML.

الرمز والوصف 
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 للخرائط جميع الخيارات المتاحة لهذه الطبقة.
حمِّل ملف HTML لعرض محتوى ملف KML كطبقة فوق الخريطة الأساسية. ومع ذلك، لن يؤدي النقر على أي ميزة إلى اتخاذ أي إجراء حتى الآن.

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

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

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

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

توفّر "خرائط Google" وظيفة للاستماع إلى أحداث المستخدمين على الخريطة والاستجابة لها، مثل النقرات أو الضغط على مفاتيح لوحة المفاتيح. تضيف خدمة معالجة الحدث لأحداث 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.