Google Maps API

地图 API
- 开发指南
  - 基础
  - 事件
  - 控件
  - 叠加层
  - 服务
- 示例
- 参考

Mapplets API
- 主页
- 文档

地图基础

简介
Google 地图的“Hello, World”
经纬度
地图属性
地图交互
信息窗口

简介

任何 Google 地图 API 应用程序中的基础元素都是地图本身。本文档讨论 GMap2 基础对象的用法和地图操作的基础。

Google地图的“Hello, World”

开始学习 Google 地图 API 最简单的方式是看一个简单的示例。以下网页显示以北京的故宫博物院为中心的 500x300 地图。

<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Strict//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google 地图 JavaScript API 示例</title>
    <script src="http://ditu.google.com/maps?file=api&amp;v=2&amp;key=abcdefg"
            type="text/javascript"></script>
    <script type="text/javascript">

    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(document.getElementById("map_canvas"));
        map.setCenter(new GLatLng(39.917, 116.397), 14);
      }
    }

    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map_canvas" style="width: 500px; height: 300px"></div>
  </body>
</html>

您可以查看此示例以及下载、编辑和播放该示例，但必须将该文件中的密钥（key）替换为您自己的地图 API 密钥。（如果注册了特定目录的密钥，也可以将其用于所有子目录。）

即使在此简单的示例中，也需要注意五点：

使用 script 标签包含地图 API JavaScript。
创建名为 "map_canvas" 的 div 元素存放地图。
编写 JavaScript 函数创建“map”对象。
将地图中的中心设置为给定的地理点。
从 body 标签的 onLoad 事件初始化地图对象。

下面说明了这些步骤。

加载 Google 地图 API

<script src="http://ditu.google.com/maps?file=api&v=2&key=abcdefg"
        type="text/javascript">
</script>

http://ditu.google.com/maps?file=api&v=2&key=abcdefg 网址指向包含使用 Google 地图 API 所需所有符号和定义的 JavaScript 文件的位置。您的页面必须包含指向此网址的 script 标签，使用注册获取 API 时收到的密钥。在此示例中，该密钥为“abcdefg”。

地图 DOM 元素

<div id="map_canvas" style="width: 500px; height: 300px"></div>

要使地图在网页上显示，必须为其留出一个位置。通常，我们通过创建名为 div 的元素并在浏览器的文档对象模型 (DOM) 中获取此元素的引用执行此操作。

在上述示例中，我们定义名为 "map_canvas" 的 div，并使用样式属性设置其尺寸。地图会自动使用容器尺寸调整自身的尺寸，除非使用构造函数中的 GMapOptions 为地图明确指定尺寸。

`GMap2` - 基本对象

var map = new GMap2(document.getElementById("map_canvas"));

表示地图的 JavaScript 类是 GMap2 类。此类的对象在页面上定义单个地图。（可以创建此类的多个实例，每个对象将在页面上定义一个不同的地图。）我们使用 JavaScript new 操作符创建此类的一个新实例。

当创建新的地图实例时，在页面中指定一个 DOM 节点（通常是 div 元素）作为地图的容器。HTML 节点是 JavaScript document 对象的子节点，我们通过 document.getElementById() 方法获取对此元素的引用。

此代码定义一个变量（名为 map），并将该变量分配给新的 GMap2 对象。函数 GMap2() 称为构造函数，其定义（在 Google 地图 API 参考中简述）如下所示：

构造函数	描述
GMap2(container, opts?)	在给定的 HTML `container`（通常是 `DIV` 元素）中创建新的地图。还可以传递类型为 `GMap2Options` 的可选参数 `opts`。

请注意因为 JavaScript 是松散类型的语言，我们可以不填写构造函数的任何可选参数，此处也未这样做。

初始化地图

  map.setCenter(new GLatLng(39.917, 116.397), 14);

通过 GMap2 构造函数创建地图之后，还需要执行一个操作，即将其初始化。初始化通过地图的 setCenter() 方法完成。setCenter() 方法需要 GLatLng 经纬度坐标和缩放级别，并且调用此方法必须在对地图执行任何其它操作（包括设置地图本身的任何其它属性）之前。

加载地图

  <body onload="initialize()" onunload="GUnload()">

当 HTML 页面显示时，文档对象模型 (DOM) 即会扩展，接收其他外部图像和脚本并将其合并到 document 对象中。为了确保只有在完全加载页面后才将我们的地图放在页面上，我们仅在 HTML 页面的 <body> 元素收到 onload 事件后才执行构造 GMap2 的函数。这样做可以避免出现不可预期的行为，并使我们可以对地图绘制的方式和时间进行更多控制。

onload 属性是事件处理程序的示例。Google 地图 API 还提供可以“侦听”状态变化的大量事件。请参阅地图事件和事件侦听器以了解更多信息。

GUnload() 函数是设计为防止内存泄露的工具函数。

经纬度

既然现在已经有地图了，我们还需要一种方式来引用地图的上位置。在 Google 地图 API 中，GLatLng 对象提供了此类机制。可以构造一个 GLatLng 对象，按照制图学的惯例以（纬度，经度）的顺序传递参数：

  var myGeographicCoordinates = new GLatLng(myLatitude, myLongitude)

注意：将地址转换为地理点的过程称为地址解析（geocoding），会在 Google 地图 API 服务一节中详细讨论。

就象它可用于轻松地引用地理点一样，它也可用于定义对象的地理边界。例如，显示整个中国的当前地图"窗口"，称为视图（viewport）。此视图可以通过四个角的点定义。GLatLngBounds 对象提供此功能，使用分别表示边界框的西南角和东北角的两个 GLatLng 对象定义一个矩形区域。

GLatLng 对象在 Google 地图 API 中有许多用途。例如，GMarker 对象在其构造函数中接收 GLatLng 参数，并在地图上给定的地理位置上叠加一个标记。

以下示例使用 getBounds() 返回当前视图，然后在地图上这些边界内随机放置 10 个标记：

function initialize() {
  var map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(new GLatLng(39.917, 116.397), 14);
 
  // 在随机位置向地图中添加 10 个标记
  var bounds = map.getBounds();
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();
  for (var i = 0; i < 10; i++) {
    var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
        southWest.lng() + lngSpan * Math.random());
    map.addOverlay(new GMarker(point));
  }
}

查看示例 (map-markers.html)

注意：有关 GMarker 对象的更多信息，请参见叠加层一节。

地图属性

地图包含用于了解各种情况的大量属性。例如，要了解当前视图的尺寸，请使用 GMap2 对象的 getBounds() 方法返回 GLatLngBounds 值。

每个地图还包含一个缩放级别，它定义当前视图的分辨率。普通地图视图中，可以使用 0（最低缩放级别，在地图上可以看到整个世界）到 19（最高缩放级别，可以看到每个建筑物）之间的缩放级别。缩放级别因所查看地区而异，因为地图上某些地区的数据比其它地区更详细。

可以通过使用 GMap2 对象的 getZoom() 方法检索当前地图所使用的缩放级别。

关于缩放级别、地图图块以及创建自己的定制地图类型的更多信息，请参阅图块叠加层一节。

地图交互

既然现在有了 GMap2 对象，就可以与之进行交互了。基本地图对象的外观和行为都非常像您在 Google 地图网站上交互的地图，并带有大量内置行为。GMap2 对象还提供了大量配置方法来改变地图对象本身的行为。

默认情况下，地图对象会和 http://ditu.google.com 上一样对用户的活动做出反应。但您可以使用大量工具函数改变此行为。例如，函数 GMap2.disableDragging() 禁用单击地图和将地图拖到新位置的功能。

还可以通过编程与地图交互。GMap2 对象支持可以直接改变地图状态的大量方法。例如，setCenter()、panTo、zoomIn() 和 setCenter() 方法以程序方式而不是通过用户交互在地图上操作。

以下示例显示一个地图，等两秒，然后平移到新的中心点。panTo 方法将地图的中心设置在给定点。如果指定点在地图的可见部分，则地图会平稳地移动到该点，否则地图会跳到该点。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.917, 116.397), 14);
window.setTimeout(function() {
  map.panTo(new GLatLng(39.927, 116.407));
}, 1000);

查看示例 (map-animate.html)

可以通过使用地图 API 事件进行更复杂的交互。

信息窗口

Google 地图 API 中的每个地图可以显示类型为 GInfoWindow 的单个“信息窗口”，它在地图上方的浮动窗口中显示 HTML 内容。信息窗口的外观有点象漫画书上表示人谈话的气球状标识符；一个内容区域和锥形的箭头，箭头指向地图上的给定点。可以通过单击 Google 地图上的标记而看到活动的信息窗口。

GInfoWindow 对象没有构造函数。当创建地图时，会有一个信息窗口自动创建并与地图关联。对给定的地图，一次不能显示多个信息窗口，但可以移动信息窗口并更改其内容（如果需要）。

GMap2 对象提供了一个 openInfoWindow() 方法，它取一个点和一个 HTML DOM 元素作为参数。HTML DOM 元素追加到信息窗口容器中，信息窗口的头固定在给定点上。

GMap2 的 openInfoWindowHtml() 方法类似，但它取一个 HTML 字符串而不是 DOM 元素作为第二个参数。

要创建信息窗口，请调用 openInfoWindow 方法，并向其传递要显示的位置和 DOM 元素。以下示例代码显示固定到地图中心并显示简单的“Hello, world”消息的信息窗口。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.917, 116.397), 14);
map.openInfoWindow(map.getCenter(),
                   document.createTextNode("Hello, world"));

查看示例 (map-infowindow.html)

有关信息窗口的完整文档，请查阅 Google 地图 API 参考


例如，“ajax api”或“开源”