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 数据转换成利用 V3 图块叠层显示在地图上的 KML 表示。该 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 叠层类似。默认情况下，点击单个特征会调出一个 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;
  }
}

查看 KML 示例