عرض بيانات 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. لمعرفة تفاصيل عن هذا المعيار، يُرجى الرجوع إلى موقع 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

يوضّح هذا الجدول الرمز البرمجي الذي ينشئ طبقة 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 لـ "خرائط Google" جميع الخيارات المتاحة لهذه الطبقة.
حمِّل ملف 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.