本頁面由 Cloud Translation API 翻譯而成。

KML 與 GeoRSS 圖層

選取平台： Android iOS JavaScript

KmlLayer 會將 KML 和 GeoRSS 元素算繪成 Maps JavaScript API 圖塊疊加層。

總覽

Maps JavaScript API 支援顯示地理資訊的 KML 和 GeoRSS 資料格式。這些資料格式使用 KmlLayer 物件顯示在地圖上，該物件的建構函式接受可公開存取的 KML 或 GeoRSS 檔案網址。

注意：在 Maps JavaScript API 中產生 KML 疊加層的 KmlLayer 類別，會以 Google 代管的服務擷取和剖析 KML 檔案，並進行算繪。因此，只有當 KML 檔案代管在無需驗證即可公開存取的網址時，才能顯示這些檔案。

如果您需要存取私人檔案、精確控制快取，或是將瀏覽器可視區域做為查詢參數傳送至地理空間資料伺服器，建議使用資料層，而非 KmlLayer。這會引導使用者的瀏覽器直接向您的網路伺服器要求資源。

Maps JavaScript API 會將提供的地理 XML 資料轉換成 KML 表示法，並使用 Maps JavaScript API 圖塊疊加層顯示在地圖上。這個 KML 不僅外觀與 Maps JavaScript API 疊加層元素十分相似，兩者的某些行為也十分雷同。舉例來說，KML <Placemark> 與 GeoRSS point 元素都會算繪為標記，<LineString> 元素會算繪為折線，而 <Polygon> 元素則會算繪為多邊形。同樣地，<GroundOverlay> 元素在地圖上會算繪為矩形圖片。但請注意，這些物件不是 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：

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: 49.496675, lng: -102.65625 },
    }
  );

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: 49.496675, lng: -102.65625 },
  });
  const 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);
}

window.initMap = initMap;index.js

CSS

/* 
 * 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;
}
style.css

HTML

<html>
  <head>
    <title>GeoRSS Layers</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

測試範例

JSFiddle.net Google Cloud Shell

以下範例是根據指定的 KML 動態饋給來建構 KmlLayer：

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 41.876, lng: -87.624 },
    }
  );

  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 41.876, lng: -87.624 },
  });
  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

window.initMap = initMap;index.js

CSS

/* 
 * 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;
}
style.css

HTML

<html>
  <head>
    <title>KML Layers</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

測試範例

JSFiddle.net Google Cloud Shell

KML 地圖項目詳細資料

KML 可能包含大量地圖項目，因此您無法直接從 KmlLayer 物件存取地圖項目資料。不過，顯示地圖項目時，系統會進行算繪，使地圖項目看起來像是可點選的 Maps JavaScript API 疊加層。根據預設，點選個別地圖項目時，系統會顯示 <title>，其中包含與指定地圖項目相關的 KML <title> 和 <description> 資訊。此外，點選 KML 地圖項目會產生 KmlMouseEvent 並傳遞下列資訊：

position 表示錨定此 KML 地圖項目 InfoWindow 的經緯度座標。這個位置通常是多邊形、折線和地面疊加層的點選位置，但對標記而言，則是實際起點。
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> 文字：

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 12,
      center: { lat: 37.06, lng: -95.68 },
    }
  );

  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text: string) {
    const sidebar = document.getElementById("sidebar") as HTMLElement;

    sidebar.innerHTML = text;
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 37.06, lng: -95.68 },
  });
  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    const sidebar = document.getElementById("sidebar");

    sidebar.innerHTML = text;
  }
}

window.initMap = initMap;index.js

CSS

/* Optional: Makes the sample page fill the window. */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#container {
  height: 100%;
  display: flex;
}

#sidebar {
  flex-basis: 15rem;
  flex-grow: 1;
  padding: 1rem;
  max-width: 30rem;
  height: 100%;
  box-sizing: border-box;
  overflow: auto;
}

#map {
  flex-basis: 0;
  flex-grow: 4;
  height: 100%;
}
style.css

HTML

<html>
  <head>
    <title>KML Feature Details</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="container">
      <div id="map"></div>
      <div id="sidebar"></div>
    </div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

測試範例

JSFiddle.net Google Cloud Shell

KML 算繪的大小和複雜度限制

Maps JavaScript API 會限制所載入 KML 檔案的大小和複雜度。以下摘要列出目前的限制：

注意：這些限制隨時可能有所變動。

可擷取檔案大小上限 (原始 KML、原始 GeoRSS 或壓縮過的 KMZ): 3 MB
未壓縮 KML 檔案大小上限: 10 MB
KMZ 檔案中未壓縮圖片檔大小上限: 每個檔案 500 KB
網路連結數量上限: 10
整份文件的地圖項目總數上限: 1,000
KML 圖層數量: 單一 Google 地圖可顯示的 KML 圖層數量有上限。如果超過此上限，地圖上就不會顯示您的任何圖層，且網路瀏覽器的 JavaScript 控制台中會顯示錯誤訊息。這個上限取決於兩項因素，即已建立的 KmlLayer 類別數量，以及用於建立這些圖層的所有網址總長度。您建立的所有新 KmlLayer 都會佔圖層上限的一部分，而 KML 檔案載入來源的網址長度也會佔另一部分。因此，可新增的圖層數量會因應用程式而異。平均來說，您應該可以載入 10 到 20 個圖層，而不會達到上限。如果您仍達到上限，請使用網址縮短工具縮短 KML 網址。您也可以建立單一 KML 檔案，在其中納入指向個別 KML 網址的 NetworkLink。

效能和快取注意事項

Google 的伺服器會暫時快取 KML 檔案，以降低伺服器的負載。這也會在使用者點選、平移和縮放地圖時，為 KML 檔案提供適當區隔以有效利用空間呈現方式，進而改善使用者體驗。

為獲得最佳成效，建議您：

在 KML 中使用適當的 <expires> 標記。

KmlLayer 決定如何快取 KML 檔案時，「不會」使用 HTTP 標頭。
請勿在要求時動態產生檔案。

請改為在有需要前就產生檔案，並以靜態方式提供。如果伺服器需要較長的時間來傳輸 KML 檔案，KmlLayer 可能無法顯示。
除非您明確知道檔案已更新，否則請勿嘗試略過快取。

如果網站使用者突然增加，且您提供大型的 KML 檔案，則一律略過快取 (例如透過附加隨機號碼或使用者的時鐘時間做為查詢參數) 會導致伺服器過載。

此外，如果使用者的時鐘不正確，且 <expires> 標記未正確設定，還可能會導致快取為使用者提供過時的資料。

請改為使用獨立的新修訂版本編號發布更新後的靜態檔案，然後使用伺服器端程式碼，將傳送至 KmlLayer 的網址動態更新為目前版本。
將您的 KML 檔案變更頻率限制為每分鐘一次。

如果所有檔案的總大小 (未壓縮) 超過 1 MB，則將變更頻率限制為每 5 分鐘一次。
使用地理空間資料伺服器時，請避免使用查詢參數來限制圖層的可視區域。

您可以改為使用 bounds_changed 事件來限制地圖可視區域。系統只會向使用者傳送可自動顯示的地圖項目。

如果地理空間資料伺服器中有大量資料，建議您改用資料層。
使用地理空間資料伺服器時，請針對要允許使用者切換的每個地圖項目群組使用多個 KmlLayer，而不要使用具備不同查詢參數的單一 KmlLayer。
使用壓縮的 KMZ 檔案縮減檔案大小。
如果您使用 Google Cloud Storage 或其他雲端儲存空間解決方案，請「避免」使用經簽署的網址或臨時權杖等功能來強制執行存取權控管。這類操作可能會意外造成快取作業無法執行。
將所有點的精確度降低為適當的精確度。
合併並簡化類似地圖項目 (例如多邊形和折線) 的幾何圖形。
移除所有未使用的元素或圖片資源。
移除所有不支援的元素。

如果您需要存取私人資料、防止快取，或是將瀏覽器可視區域傳送至地理空間資料伺服器做為查詢參數，建議您使用資料層，而非 KmlLayer。這會引導使用者的瀏覽器直接向您的網路伺服器要求資源。

支援的 KML 元素

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>	是
hint	是	支援 `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>	是	已淘汰

KML 與 GeoRSS 圖層 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

KML 圖層選項

TypeScript

JavaScript

CSS

HTML

測試範例

TypeScript

JavaScript

CSS

HTML

測試範例

KML 地圖項目詳細資料

TypeScript

JavaScript

CSS

HTML

測試範例

KML 算繪的大小和複雜度限制

效能和快取注意事項

支援的 KML 元素

KML 與 GeoRSS 圖層