عرض 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 المضمّن كقيمة لنص البالون لكل علامة موضعية.

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

يشرح هذا الجدول التعليمة البرمجية التي تنشئ 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.
  • الحصول على بيانات الميزة التي تم النقر عليها.
  • كتابة تلك البيانات على الشريط الجانبي.

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

توفر خرائط 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.