显示 KML

概览

本教程介绍了如何在 Google 地图和边栏中显示 KML 文件的信息。如需详细了解如何在地图中使用 KML 文件,请参阅 KML 图层指南。请试着点击下方地图上的标记,在边栏中查看相关数据。

下文显示了创建地图和边栏所需的完整代码。

var map;
var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });

  var kmlLayer = new google.maps.KmlLayer(src, {
    suppressInfoWindows: true,
    preserveViewport: false,
    map: map
  });
  kmlLayer.addListener('click', function(event) {
    var content = event.featureData.infoWindowHtml;
    var testimonial = document.getElementById('capture');
    testimonial.innerHTML = content;
  });
}
<div id="map"></div>
<div id="capture"></div>
html, body {
  height: 370px;
  padding: 0;
  margin: 0;
  }
#map {
 height: 360px;
 width: 300px;
 overflow: hidden;
 float: left;
 border: thin solid #333;
 }
#capture {
 height: 360px;
 width: 480px;
 overflow: hidden;
 float: left;
 background-color: #ECECFB;
 border: thin solid #333;
 border-left: none;
 }
<!-- Replace the value of the key parameter with your own API key. -->
<script async
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

亲自尝试

您可以通过点击代码窗口右上角的 <> 图标,在 JSFiddle 中尝试以下代码。

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no">
    <meta charset="utf-8">
    <title>KML Click Capture Sample</title>
    <style>
      html, body {
        height: 370px;
        padding: 0;
        margin: 0;
        }
      #map {
       height: 360px;
       width: 300px;
       overflow: hidden;
       float: left;
       border: thin solid #333;
       }
      #capture {
       height: 360px;
       width: 480px;
       overflow: hidden;
       float: left;
       background-color: #ECECFB;
       border: thin solid #333;
       border-left: none;
       }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <div id="capture"></div>
    <script>
      var map;
      var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: new google.maps.LatLng(-19.257753, 146.823688),
          zoom: 2,
          mapTypeId: 'terrain'
        });

        var kmlLayer = new google.maps.KmlLayer(src, {
          suppressInfoWindows: true,
          preserveViewport: false,
          map: map
        });
        kmlLayer.addListener('click', function(event) {
          var content = event.featureData.infoWindowHtml;
          var testimonial = document.getElementById('capture');
          testimonial.innerHTML = content;
        });
      }
    </script>
    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
  </body>
</html>

开始使用

创建本教程中的地图和边栏分为以下几个阶段:

  1. 设置 KML 文件
  2. 显示 KMLlayer
  3. 在边栏中显示数据

设置要导入的 KML 文件

您的 KML 文件应符合 KML 标准。如需详细了解此标准,请访问开放地理空间联盟网站。Google 的 KML 文档也介绍了这种语言,还提供了参考文档和概念性开发者文档。

如果您只是要学习,并且没有 KML 文件,则可以:

  • 使用以下 KML 文件来进行本教程的操作:

    https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml
    
  • 在网上找一个 KML 文件。您可以使用 Google 的 filetype 搜索运算符。

    您可以用任意搜索字词替换 velodromes,也可以完全省略搜索字词,查找所有 KML 文件。

如果您要自行创建文件,此示例中的代码基于以下假设:

  • 您已将该文件公开托管在互联网上。所有将 KML 加载到 KMLLayer 中的应用都必须满足这一要求,这样 Google 的服务器才能查找并检索内容,以将其显示在地图上。
  • 该文件不在受密码保护的网页上。
  • 您的地图项包含信息窗口内容。您可以在 description 元素中包含该内容,也可以使用 ExtendedData 元素和实体替换将其包含在内(详情请参阅下文)。这两者都可作为地图项的 infoWindowHtml 属性进行访问。

ExtendedData 元素

在本教程的 KML 文件中,地图项信息包含在 ExtendedData 元素中。若要将此类信息添加到地图项的说明中,请使用实体替换,这实际上就是 BalloonStyle 标记中的一个变量。

下表介绍了本部分所用的代码。

代码和说明

<Style id="west_campus_style">
  <IconStyle>
    <Icon>
      <href>https://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png
      </href>
    </Icon>
  </IconStyle>
  <BalloonStyle>
    <text>$[video]</text>
  </BalloonStyle>
</Style>

KML 文件有一个应用于所有地标的 Style 元素。
Style 元素会将 #[video] 的值分配给 BalloonStyle 的文本元素。
$[x] 格式会指示 KML 解析器查找名为 videoData 元素并将其用作提示框文本。

<Placemark>
    <name>Google West Campus 1</name>
    <styleUrl>#west_campus_style</styleUrl>
    <ExtendedData>
      <Data name="video">
        <value><![CDATA[<iframe width="640" height="360"
          src="https://www.youtube.com/embed/ZE8ODPL2VPI" frameborder="0"
          allowfullscreen></iframe><br><br>]]></value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-122.0914977709329,37.42390182131783,0</coordinates>
    </Point>
</Placemark>

每个 Placemark 均包含一个 ExtendedData 元素,用于保存 Data 元素。请注意,每个 Placemark 都有一个名称属性为 videoData 元素。
本教程的文件使用嵌入式 YouTube 视频作为每个地标的提示框文本值。

如需详细了解实体替换,请参阅 KML 文档的添加自定义数据一章。

显示 KMLLayer

初始化地图

下表介绍了本部分所用的代码。

代码和说明

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });
}

若要在地图上显示 KML,您需要先创建地图。
这段代码会创建一个新的 Google 地图对象,告知该对象以何处为中心和在何处进行缩放,并将地图附加到 div
如需详细了解创建 Google 地图的基础知识,请参阅向网站添加 Google 地图教程。

创建 KMLLayer

下表介绍了用于创建 KMLLayer 的代码。

代码和说明

var kmlLayer = new google.maps.KmlLayer();

创建新的 KMLLayer 对象以显示 KML。

var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';
var kmlLayer = new google.maps.KmlLayer(src, {
  suppressInfoWindows: true,
  preserveViewport: false,
  map: map
});

KMLLayer 构造函数会设置 KML 文件的网址,还会为 KMLLayer 对象定义用于执行以下操作的属性:
  • 指示图层在用户点击时不显示信息窗口。
  • 指示地图根据图层内容的边界框设置中心位置和进行缩放。
  • 将地图设置为之前创建的 Map 对象。
Maps JavaScript API 参考指南中列出了此图层的所有可用选项。
加载 HTML 文件,将 KML 文件内容显示为覆盖在基本地图上的图层。不过,点击任意地图项尚不会产生任何操作。

在边栏中显示数据

本部分介绍的设置会在您点击地图上的地图项时,在边栏中显示信息窗口内容。这是通过以下操作实现的:

  • 监听任何 KMLLayer 地图项的点击事件。
  • 获取所点击地图项的数据。
  • 将此类数据写入边栏。

添加事件监听器

Google 地图提供了一个函数,用于监听和响应地图上的用户事件,例如点击或键盘按键。该函数会为此类 click 事件添加监听器。

下表介绍了本部分所用的代码。

代码和说明

kmlLayer.addListener('click', function(event) {});

kmlLayer.addListener 事件监听器重点监听以下各项:
  • 要监听的事件的类型,在本教程中为 click 事件。
  • 在事件发生时调用的函数。
如需详细了解事件,请参阅开发者指南

将 KML 地图项数据写入边栏

到本教程的这一阶段,您已经捕获了图层地图项的点击事件。现在,您可以将应用设置为将地图项的数据和信息窗口内容写入边栏。

下表介绍了本部分所用的代码。

代码和说明

var content = event.featureData.infoWindowHtml;

将信息窗口内容写入变量。

var testimonial = document.getElementById('capture');
testimonial.innerHTML = content;

确定要写入到的 div,并将其中的 HTML 替换为地图项的内容。

kmlLayer.addListener('click', function(event) {
  var content = event.featureData.infoWindowHtml;
  var testimonial = document.getElementById('capture');
  testimonial.innerHTML = content;
});

这些代码行会成为 addListener 构造函数内的函数。

现在,您每次点击地图上的 KML 地图项时,边栏都会进行更新以显示其信息窗口内容。

更多信息

详细了解如何使用 KML 文件