顯示 KML

總覽

本教學課程說明如何在 Google 地圖和側欄中顯示 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 標準。如要進一步瞭解這項標準,請參閱開放地理空間協會網站。Google KML 說明文件也介紹這種語言,並提供參考資料和開發人員概念說明文件。

如果您只是在學習,且沒有 KML 檔案,可以:

  • 使用以下 KML 檔案進行本教學課程:

    https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml
    
  • 在網路上尋找 KML 檔案。您可以使用 Google 的 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 剖析器尋找名為 videoData 元素,並用來做為說明框文字。

<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 都有一個名稱屬性為 videoData 元素。
本教學課程的檔案會使用內嵌 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 建構函式會設定 KML 檔案的網址,也會定義 KMLLayer 物件用於執行下列操作的屬性:
  • 指示圖層在發生點擊時不顯示資訊視窗。
  • 指示地圖根據圖層內容的定界框設定中心和縮放。
  • 將地圖設為先前建立的地圖物件。
Maps JavaScript API 參考指南列出這個圖層的所有可用選項。
請載入 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 檔案