Google 地图 API

Google 地图 API
- 开发人员指南
  - 基础知识
  - 事件
  - 控件
  - 叠加层
  - 服务
- API 参考
- 代码示例：
  - 演示
  - 示例
- 更多资源：
  - 文章
  - 演示文稿
  - 已知问题
  - 实用工具库
  - 案例研究新！

Google Maps API（Flash 版）
- 主页
- 文档

静态地图 API
- 开发人员指南

Mapplet 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 Maps JavaScript API Example</title>
    <script src="http://ditu.google.cn/maps?file=api&amp;v=2&amp;key=abcdefg&sensor=true_or_false"
            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.9493, 116.3975), 13);
      }
    }

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

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

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

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

下面说明了这些步骤。

加载 Google 地图 API

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

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

请注意，我们也传递 sensor 参数以指明此应用程序是否使用传感器来确定用户位置。在此示例中，我们将其设为变量“true_or_false”以强调您必须显式地将此值设置为 true 或 false。

地图 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"));

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

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

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

构造函数	说明
GMap2(container, opts?)	在通常是一个 `DIV` 元素的指定 HTML `container` 内创建新地图。您也可以通过 `opts` 参数传递 `GMap2Options` 类型的可选参数。

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

初始化地图

  map.setCenter(new GLatLng(39.9493, 116.3975), 13);

通过 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)

注意：将“地址”转变为地理点的过程称为“地址解析”，将在“Google 地图 API 服务”部分中详细讨论。

就像它可用于轻松地引用地理点一样，它也可用于定义对象的地理边界。例如，地图在称为视口的窗口内显示整个世界的当前“窗口”。此视口可以通过四个角上的矩形点来定义。GLatLngBounds 对象提供了这个功能，通过使用分别表示边界框的西南角和东北角的两个 GLatLng 对象定义一个矩形区域来实现。

GLatLng 对象在 Google 地图 API 中用途广泛。例如，GMarker 对象在其构造函数中具有 GLatLng，并在地图上的指定地理位置放置标记“叠加层”。

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

function initialize() {
  var map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(new GLatLng(39.9493, 116.3975), 13);
 
  // Add 10 markers to the map at random locations
  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 对象的详细信息位于叠加层部分中。

地图属性

默认情况下，在 Google 地图 API 中，地图使用标准的“绘制”图块显示。但是，Google 地图 API 也支持其他地图类型。以下是标准地图类型：

G_NORMAL_MAP- 默认视图
G_SATELLITE_MAP - 显示 Google 地球卫星图像
G_HYBRID_MAP - 混合显示普通视图和卫星视图
G_DEFAULT_MAP_TYPES - 这三个类型的数组，在需要重复处理的情况下非常有用

可以使用 GMap2 对象的 setMapType() 方法设置地图类型。例如，下面的代码将地图设置为使用 Google 地球的卫星视图：

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

地图还包含对了解情况非常有用的大量属性。例如，要了解当前视口的尺寸，可使用 GMap2 对象的 getBounds() 方法来返回 GLatLngBounds 值。

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

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

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

地图交互

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

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

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

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

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

查看示例 (map-animate.html)

可以通过使用 Google 地图 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.9493, 116.3975), 13);
map.openInfoWindow(map.getCenter(),
                   document.createTextNode("Hello, world"));

查看示例 (map-infowindow.html)

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


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

Google 地图 API