KML 和 GeoRSS 圖層

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

總覽

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

Maps JavaScript API 會將提供的地理 XML 資料轉換成 KML 表示法，這種表示法使用 Maps JavaScript API 地圖方塊疊加層在地圖上顯示。這個 KML 的外觀（與一些行為）與熟悉的 Maps JavaScript API 疊加層元素非常相似。KML <Placemark> 和 GeoRSS point 元素會轉譯成標記，例如，<LineString> 元素會轉譯成折線，<Polygon> 元素會轉譯成多邊形。同樣地，<GroundOverlay> 元素會轉譯成地圖上的矩形影像。不過請務必記得，這些物件「不是」Google Maps JavaScript 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);
}

<div id="map"></div>

/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

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
  });
}

<div id="map"></div>

/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

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 JavaScript 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://googlemaps.github.io/kml-samples/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;
  }
}

<div id="map"></div>
<div id="content-window"></div>

html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  float: left;
  height: 100%;
  width: 79%;
}
#content-window {
  float: left;
  font-family: 'Roboto','sans-serif';
  height: 100%;
  line-height: 30px;
  padding-left: 10px;
  width: 19%;
}

 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

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://googlemaps.github.io/kml-samples/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 範例

KML 轉譯的大小與複雜性限制

Google Maps JavaScript API 對載入的 KML 檔案有大小與複雜性限制。以下是目前限制的摘要：

注意：這些限制可能會隨時變更。

擷取的檔案大小上限（原始 KML、原始 GeoRSS 或壓縮的 KMZ）

3MB

未壓縮的 KML 檔案大小上限

10MB

網路連結數目上限

10

全文件特徵總數上限

1,000

KML 圖層數目

可顯示在單一 Google 地圖上的 KML 圖層數目有限制。如果您超過此限制，地圖上將不會出現任何圖層，並會在網頁瀏覽器的 JavaScript 控制台中回報錯誤。此限制會根據建立的 KMLLayer 類別數目和用以建立那些圖層之所有網址總長的組合而定。每一個新建立的 KMLLayer 都占用一部分圖層限制，而另一部分的限制則取決於 KML 檔案載入來源的網址長度。因此，您可以新增的圖層數目會隨應用程式而異；您平均能載入 10 到 20 個圖層，而不會達到限制。若您仍達到限制，請使用短網址產生器（例如 https://goo.gl）來縮短 KML 網址。或者，針對個別的 KML 網址建立包含 NetworkLinks 的單一 KML 檔案。

支援的 KML 元素

Google Maps JavaScript API 支援下列 KML 元素。KML 剖析器一般會以無訊息方式略過它無法理解的 XML 標記。

• 地點標記
• 圖示
• 資料夾
• 描述性 HTML—透過 <BalloonStyle> 與 <text> 進行實體取代
• KMZ （壓縮的 KML，包括附加的映像）
• 折線與多邊形
• 折線與多邊形的樣式，包括色彩、填滿與不透明度
• 可動態匯入資料的網路連結
• 地面疊加層與螢幕疊加層

下表提供所支援 KML 元素的完整詳細資料。