您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps JavaScript API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps JavaScript API 與相關服務
  3. 建立適當的金鑰
繼續

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 MarkersPolylinesPolygonsGroundOverlays,而是會轉譯為地圖上的單一物件。

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

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

KML 圖層選項

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

  • map 可指定要在其上轉譯 KmlLayerMap。在 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: "nobody@google.com",
    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 元素的完整詳細資料。

KML 元素 API 中是否支援? 註解
<address>
<AddressDetails>
<Alias> 不適用 不支援 <Model>
<altitude>
<altitudeMode>
<atom:author>
<atom:link>
<atom:name>
<BalloonStyle> 部分 只支援 <text>
<begin> 不適用 不支援 <TimeSpan>
<bgColor>
<bottomFov> 不適用 不支援 <PhotoOverlay>
<Camera>
<Change> 部分 只支援樣式變更
<color> 部分 包括 #AABBGGRR 與 #BBGGRR;在 <IconStyle>、<ScreenOverlay> 與 <GroundOverlay> 中不支援
<colorMode>
<cookie>
<coordinates>
<Create>
<Data>
<Delete>
<description> 允許有 HTML 內容但會被清除,以免受到跨瀏覽器攻擊的危害。不支援 $[dataName] 形式的實體取代
<displayMode>
<displayName>
<Document> 部分 以隱含方式支援子項;作為其他特徵的子項無效
<drawOrder>
<east>
<end> 不適用 不支援 <TimeSpan>
<expires> 如需詳細資料,請參閱「摘要」一節
<ExtendedData> 部分 只限不具類型的 <Data>,不得有 <SimpleData> 或 <Schema>,且不支援 $[dataName] 形式的實體取代。
<extrude>
<fill>
<flyToView>
<Folder>
<geomColor> 已淘汰
<GeometryCollection> 已淘汰
<geomScale> 已淘汰
<gridOrigin> 不適用 不支援 <PhotoOverlay>
<GroundOverlay> 無法旋轉
<h> 已淘汰
<heading>
提示 支援 target=...
<hotSpot>
<href>
<httpQuery>
<Icon> 無法旋轉
<IconStyle>
<ImagePyramid> 不適用 不支援 <PhotoOverlay>
<innerBoundaryIs> 從 <LinearRing> 順序暗示
<ItemIcon> 不適用 不支援 <ListStyle>
<key> 不適用 不支援 <StyleMap>
<kml>
<labelColor> 已淘汰
<LabelStyle>
<latitude>
<LatLonAltBox>
<LatLonBox>
<leftFov> 不適用 不支援 <PhotoOverlay>
<LinearRing>
<LineString>
<LineStyle>
<Link>
<linkDescription>
<linkName>
<linkSnippet>
<listItemType> 不適用 不支援 <ListStyle>
<ListStyle>
<Location> 不適用 不支援 <Model>
<Lod>
<longitude>
<LookAt>
<maxAltitude>
<maxFadeExtent>
<maxHeight> 不適用 不支援 <PhotoOverlay>
<maxLodPixels>
<maxSessionLength>
<maxWidth> 不適用 不支援 <PhotoOverlay>
<message>
<Metadata> 已淘汰
<minAltitude>
<minFadeExtent>
<minLodPixels>
<minRefreshPeriod> <NetworkLink>
<Model>
<MultiGeometry> 部分 已轉譯,但在左側面板顯示為個別的特徵
<name>
<near> 不適用 不支援 <PhotoOverlay>
<NetworkLink>  
<NetworkLinkControl> 部分 部分支援 <Update> 與 <expires>。API 會略過 HTTP 標頭中的到期設定,但會使用 KML 中指定的到期設定。缺少到期設定或在時間有效期內時,Google 地圖會針對未指定的持續時間從網際網路快取所擷取的資料。重新命名文件和以不同的網址擷取它,或確定文件包含適當的到期設定,可以強制從網際網路重新擷取資料。
<north>
<open>
<Orientation> 不適用 不支援 <Model>
<outerBoundaryIs> 從 <LinearRing> 順序暗示
<outline>
<overlayXY>
<Pair> 不適用 不支援 <StyleMap>
<phoneNumber>
<PhotoOverlay>
<Placemark>
<Point>
<Polygon>
<PolyStyle>
<range>
<refreshInterval> 部分 僅限 <Link>;<Icon> 則否
<refreshMode> "onExpire" 模式不支援 HTTP 標頭。請參閱上述 <Update> 與 <expires> 的注意事項。
<refreshVisibility>
<Region>
<ResourceMap> 不適用 不支援 <Model>
<rightFov> 不適用 不支援 <PhotoOverlay>
<roll> 不適用 不支援 <Camera> 與 <Model>
<rotation>
<rotationXY>
<Scale> 不適用 不支援 <Model>
<scale>
<Schema>
<SchemaData>
<ScreenOverlay> 無法旋轉
<screenXY>
<shape> 不適用 不支援 <PhotoOverlay>
<SimpleData> 不適用 不支援 <SchemaData>
<SimpleField> 不適用 不支援 <Schema>
<size>
<Snippet>
<south>
<state> 不適用 不支援 <ListStyle>
<Style>
<StyleMap> 不支援滑鼠游標懸停效果(醒目顯示)
<styleUrl> 不適用 不支援 <StyleMap>
<targetHref> 部分 <Update> 中支援,但 <Alias> 則否
<tessellate>
<text> 不支援取代 $[geDirections]
<textColor>
<tileSize> 不適用 不支援 <PhotoOverlay>
<tilt>
<TimeSpan>
<TimeStamp>
<topFov> 不適用 不支援 <PhotoOverlay>
<Update> 部分 僅樣式變更,<Create> 或 <Delete> 則否
<Url> 已淘汰
<value>
<viewBoundScale>
<viewFormat>
<viewRefreshMode> 部分 支援 "onStop"
<viewRefreshTime>
<ViewVolume> 不適用 不支援 <PhotoOverlay>
<visibility> 部分 對於 <Folder> 為是 - 子項地點標記會繼承其能見度
<w> 已淘汰
<west>
<when> 不適用 不支援 <TimeStamp>
<width>
<x> 已淘汰
<y> 已淘汰

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps JavaScript API
Google Maps JavaScript API
需要協助嗎?請前往我們的支援網頁