KML 和 GeoRSS 圖層

1. 總覽
2. KML 圖層選項
3. KML 特徵詳細資料

KmlLayer 會將 KML 和 GeoRSS 元素轉譯到 Maps API V3 地圖方塊疊加層。

總覽

Google Maps API 支援 KML 和 GeoRSS 資料格式來顯示地理資訊。這些資料格式是使用 KmlLayer 物件在地圖上顯示，它的建構函式可接受開放存取之 KML 或 GeoRSS 檔案的 URL。

注意：請參閱 KML 文件的 KML 支援頁面，以取得支援的元素及大小與複雜性限制的相關資訊。

Maps API 會將提供的地理 XML 資料轉換成 KML 表示法，這種表示法使用 V3 地圖方塊疊加層在地圖上顯示。這個 KML 的外觀 (與一些行為) 與熟悉的 V3 疊加層元素非常相似。KML <Placemark> 和 GeoRSS point 元素會轉譯成標記，例如，<LineString> 元素會轉譯成折線，<Polygon> 元素會轉譯成多邊形。同樣地，<GroundOverlay> 元素會轉譯成地圖上的矩形影像。不過請務必記得，這些物件不是 Google Maps API Markers、Polylines、Polygons 或 GroundOverlays，而是會轉譯為地圖上的單一物件。

設定好 KmlLayer 物件的 map 屬性之後，該物件就會在地圖上顯示。呼叫 setMap() 並傳遞 null，即可從地圖上移除它們。KmlLayer 物件可管理這些子元素的轉譯，方法是針對地圖指定邊界自動擷取適當的特徵。隨著邊界的變更，目前檢視點中的特徵也會自動轉譯。

因為 KmlLayer 內的元件會隨需要轉譯，所以圖層可讓您輕鬆管理數千個標記、折線和多邊形的轉譯。請注意，雖然這些構成物件都提供可以傳回那些個別物件上資訊的點擊事件，但您並不能直接存取這些構成物件。

KML 圖層選項

KmlLayer() 建構函式可選擇性地傳遞一些 KmlLayerOptions：

• map 可指定要在其上轉譯 KmlLayer 的 Map。在 setMap() 方法內將此值設成 null，即可隱藏 KmlLayer。
• preserveViewport 可指定顯示圖層時，不應該將地圖調整到 KmlLayer 內容的邊界。根據預設，顯示 KmlLayer 時，地圖會縮放並調整位置，以完整顯示圖層的內容。
• suppressInfoWindows 指出 KmlLayer 內的可點選特徵不應該觸發 InfoWindow 物件的顯示。

此外，KmlLayer 完成轉譯之後，會包含不可變的 metadata 屬性，其中會在 KmlLayerMetadata 物件常值內包含圖層的名稱、描述、程式碼片段和作者。您可以使用 getMetadata() 方法來檢查這個資訊。因為轉譯 KmlLayer 物件需要與外部伺服器進行非同步通訊，所以您需要接聽 metadata_changed 事件，而該事件將會指示屬性已經填入。

下列範例會從指定的 GeoRSS 摘要建構一個 KmlLayer：

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 49.496675, lng: -102.65625}
  });

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}

檢視 GeoRSS 範例

下列範例會從指定的 KML 摘要建構一個 KmlLayer：

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 41.876, lng: -87.624}
  });

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}

檢視 KML 範例

KML 特徵詳細資料

因為 KML 可能包含大量特徵，所以您不能直接從 KmlLayer 物件存取特徵資料。反之，特徵在顯示時，會被轉譯為讓它們看起來像是可點選的 Maps API 疊加層。根據預設，按一下個別特徵會在指定特徵上顯示包含 KML <title> 和 <description> 資訊的 InfoWindow。此外，按一下 KML 特徵會產生一個 KmlMouseEvent，它會傳遞下列資訊：

• position 指出錨定此 KML 特徵 InfoWindow 的緯度/經度座標。這個位置一般是多邊形、折線和 GroundOverlays 的已點選位置，但也是標記的真正起點。
• pixelOffset 指出上述 position 的位移，以錨定 InfoWindow 的「尾部」。對於多邊形物件，這個位移通常是 0,0，但是針對標記則會包含標記的高度。
• featureData 包含 KmlFeatureData 的 JSON 結構。

下列顯示範例的 KmlFeatureData 物件：

{
  author: {
    email: "[email protected]",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

下列範例會在按一下特徵時，於側邊 <div> 內顯示 KML 特徵 <Description> 文字：

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: {lat: 37.06, lng: -95.68}
  });

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://kml-samples.googlecode.com/svn/trunk/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}

檢視 KML 範例