نمایش KML

بررسی اجمالی

این آموزش به شما نشان می دهد که چگونه اطلاعات یک فایل KML را در نقشه و نوار کناری گوگل نمایش دهید. برای اطلاعات بیشتر در مورد استفاده از فایل‌های 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 مطابقت داشته باشد. برای جزئیات بیشتر در مورد این استاندارد، به وب سایت کنسرسیوم فضایی باز مراجعه کنید. اسناد KML گوگل همچنین زبان را توصیف می کند و هم یک مرجع و هم مستندات مفهومی توسعه دهنده را ارائه می دهد.

اگر تازه در حال یادگیری هستید و فایل KML ندارید، می توانید:

  • برای این آموزش از فایل KML زیر استفاده کنید:

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

  • یک فایل KML را در وب پیدا کنید. می توانید از اپراتور جستجوی filetype گوگل استفاده کنید.

    هر عبارت جستجویی را جایگزین 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 است.
فایل این آموزش از ویدیوی یوتیوب جاسازی شده به عنوان مقدار متن بالون هر 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 روی نقشه، ابتدا باید نقشه را ایجاد کنید.
این کد یک شیء جدید نقشه گوگل ایجاد می کند، به آن می گوید که کجا باید مرکز و بزرگنمایی کند، و نقشه را به div متصل می کند.
برای کسب اطلاعات بیشتر در مورد اصول ایجاد نقشه گوگل، آموزش افزودن نقشه گوگل به وب سایت خود را مطالعه کنید.

ایجاد 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 تعریف می کند که موارد زیر را انجام می دهد:
  • به لایه می گوید که هنگام کلیک کردن، پنجره اطلاعات نمایش داده نشود.
  • به نقشه می‌گوید در مرکز و بزرگنمایی کادر محتویات لایه قرار گیرد.
  • نقشه را روی شی Map که قبلاً ایجاد شده است تنظیم می کند.
راهنمای مرجع Maps JavaScript API همه گزینه های موجود برای این لایه را فهرست می کند.
فایل HTML خود را برای نمایش محتوای فایل KML به صورت یک لایه در بالای نقشه پایه بارگیری کنید. با این حال، کلیک کردن روی هر ویژگی هنوز هیچ اقدامی را در پی نخواهد داشت.

نمایش داده ها در نوار کناری

این بخش تنظیماتی را توضیح می دهد که وقتی روی یک ویژگی روی نقشه کلیک می کنید، محتوای پنجره اطلاعات را در نوار کناری نمایش می دهد. این کار توسط:

  • گوش دادن به رویداد کلیک روی هر یک از ویژگی های KMLLayer.
  • گرفتن داده های ویژگی کلیک شده.
  • نوشتن آن داده ها در نوار کناری

افزودن شنونده رویداد

Google Maps عملکردی را برای گوش دادن و پاسخ به رویدادهای کاربر روی نقشه، مانند کلیک‌ها یا فشار دادن کلیدهای صفحه کلید، ارائه می‌کند. برای چنین رویدادهای 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 بیشتر بخوانید.