KML 层和 GeoRSS 层

KmlLayer 将 KML 和 GeoRSS 元素渲染成 Google Maps JavaScript API 图块叠层。

概览

Google Maps JavaScript API 支持用于显示地理信息的 KML 和 GeoRSS 数据格式。这些数据格式利用 KmlLayer 对象显示在地图上，该对象的构造函数接受可公开访问的 KML 或 GeoRSS 文件的 URL。

Maps JavaScript API 会将提供的地理 XML 数据转换成利用 Maps JavaScript API 图块叠层显示在地图上的 KML 表示形式。该 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 叠层类似。默认情况下，点击单个特征会调出一个 InfoWindow，其中包含有关给定特征的 KML <title> 和 <description> 信息。此外，点击 KML 特征还会生成一个 KmlMouseEvent，该事件会传递以下信息：

• position 表示为该 KML 特征锚定 InfoWindow 时锚点的纬度/经度坐标。对于多边形、多段线和底面叠层，此位置通常是点击位置；但对于标记，则是坐标原点。
• pixelOffset 表示锚定 InfoWindow“尾部”时与以上 position 的偏移。对于多边形对象，该偏移通常是 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 文件，其中包含指向各 KML 网址的 NetworkLink。

支持的 KML 元素

Google Maps JavaScript API 支持下列 KML 元素。KML 解析器通常以静默方式忽略其无法识别的 XML 标记。

• 标注
• 图标
• 文件夹
• 描述性 HTML—通过 <BalloonStyle> 和 <text> 进行的实体替换
• KMZ（压缩 KML，包括附带的图片）
• 多段线和多边形
• 多段线和多边形的样式，包括颜色、填充和不透明度
• 用于动态导入数据的网络链接
• 底面叠层和屏幕叠层

下表提供了所支持 KML 元素的完整详情。