第5章 Google地图API开发指南

第5章Google地图API开发指南Google Maps JavaScript API允许把Google地图嵌入到自己的网页内。要使用这个API，首先需要申请一个API key（https://www.sodocs.net/doc/fd13936082.html,/apis/maps/signup.html）。收到

5.1地图基础

5.1.1Google Maps上的Hello World例子

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

学习这个API最简单的方法就是看一个简单的例子。下面的网页显示一个500x300的

Maps API key申请的授权码，否则看不到效果。

也需要注意五点：

1)使用script标签包含地图API JavaScript。

2)创建名为"map_canvas"的div元素存放地图。

3)编写JavaScript函数创建“map”对象。

4) 将地图中的中心设置为给定的地理点。

5) 从body标签的onLoad事件初始化地图对象。

下面说明了这些步骤。

1．加载Google地图API

https://www.sodocs.net/doc/fd13936082.html,/maps?file=api&v=2&key=abcdefg

用Google地图API所需所有符号和定义的JavaScript文件的位置。页面必须包含指向此网址的script标签，使用注册获取API时收到的密钥。此示例中，该密钥为“abcdefg”。

浏览器的文档对象模型(DOM)中获取此元素的引用执行此操作。

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

建此类的多个实例，每个对象将在页面上定义一个不同的地图。）使用JavaScript new操作符创建此类的一个新实例。

当创建新的地图实例时，在页面中指定一个DOM节点（通常是div元素）作为地图的容器。HTML节点是JavaScript document对象的子节点，通过

document.getElementById()方法获取对此元素的引用。

此代码定义一个变量（名为map），并将该变量分配给新的GMap2对象。函数GMap2()

也未这样做。

过地图的setCenter()方法完成。setCenter()方法需要GLatLng经纬度坐标和缩放级别，并且调用此方法必须在对地图执行任何其它操作（包括设置地图本身的任何其它属性）之前。

其合并到document对象中。为了确保只有在完全加载页面后才将的地图放在页面上，仅在HTML页面的元素收到onload事件后才执行构造GMap2的函数。以避免出现不可预期的行为，并可以对地图绘制的方式和时间进行更多控制。

onload属性是事件处理程序的示例。

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

5.1.2经纬度

已经有地图后还需要一种方式来引用地图的上位置。在Google地图API中，GLatLng 对象提供了此类机制。可以构造一个GLatLng对象，按照制图学的惯例以（纬度，经度）

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

查看示例(map-markers.html)

5.1.3地图属性

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

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

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

5.1.4地图交互

有了GMap2对象，就可以与之进行交互了。GMap2对象还提供了大量配置方法来改变地图对象本身的行为和外观。

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

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

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

查看示例(map-animate.html)

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

5.1.5信息窗口

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

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

GMap2对象提供了一个openInfoWindow()方法，它取一个点和一个HTML DOM元素作为参数。HTML DOM元素追加到信息窗口容器中，信息窗口的头固定在给定点上。GMap2的openInfoWindowHtml()方法类似，但它取一个HTML字符串而不是DOM元素作为第二个参数。

要创建信息窗口，请调用openInfoWindow方法，并向其传递要显示的位置和DOM

查看示例(map-infowindow.html)

5.2 事件

5.2.1地图事件概述

浏览器中的JavaScript是事件驱动的，意味着JavaScript通过生成事件来响应交互，并用程序来侦听有趣的事件。例如，在浏览器中，用户鼠标和键盘交互会创建在DOM内传播的事件。对某些事件感兴趣的程序将为这些事件注册JavaScript事件侦听器，并在收到这些事件时执行代码。

Google地图API通过为地图API对象定义定制事件而成为这种事件模型的一部分。注意地图API事件与标准DOM事件不同。另外，由于不同的浏览器支持不同的DOM事件模型，地图API还提供侦听和响应这些DOM事件而无需处理各种跨浏览器特性的机制。

5.2.2事件侦听器

处理Google地图API中的事件的方式是使用GEvent名称空间中的工具函数注册事件侦听器。每个地图API对象都导出了多个命名事件。例如，GMap2对象导出click、dblclick

和move事件，以及许多其他事件。每个事件都在给定环境下发生，并且可以传递标识该环境的参数。例如，当用户在地图对象中移动鼠标时，会触发mousemove事件，并传递鼠标所在地理位置的GLatLng。

要注册以获取这些事件相关的通知，使用静态方法GEvent.addListener()。该方法的参数为待侦听对象、待侦听事件以及回调函数。例如，在以下代码片段中，每次用户单击

查看示例(event-simple.html)

侦听器也能够捕获事件的环境。在以下示例代码中，显示用户缩放地图后地图的缩放级

查看示例(event-context.html)

5.2.3在事件侦听器中使用closures

当执行事件侦听器时，通常较好的做法是同时将私有数据和持久数据与一个对象关联。JavaScript不支持“私有”实例数据，但它支持允许内部函数访问外部变量的closures。在事件侦听器中要访问通常与事件发生相关对象不关联的变量时，closures非常有用。

以下示例在事件侦听器中使用closures将一个秘密消息分配给一组标记（Marker）。

查看示例(event-closure.html)

5.2.4在事件中使用传递的参数

地图API事件系统中的许多事件在触发时都可以传递参数。例如，GMap2 "click"事件可以传递两个参数(overlay,point)。可以通过将指定的符号直接传递给事件侦听器中的函数而访问这些参数。

例如，地图上的"click"事件可以传递overlay和point参数。在回调函数内直接传递

查看示例(event-arguments.html)

5.2.5将事件绑定到对象方法

当要将事件侦听器与对象的特定实例相关联时，函数非常有用。相反，如果希望在响应事件时对象的所有实例都调用某方法，可以使用GEvent.bind()。在以下示例中，一个应

查看示例(event-bind.html)

5.2.6侦听DOM事件

Google地图API事件模型创建并管理着自己的定制事件。然而DOM也创建和分派自己的事件，它取决于当前使用的特定浏览器事件模型。如果要捕获并响应这些事件，Google 地图API提供了独立于浏览器的包装器来侦听和绑定DOM事件，而无需定制代码。

静态方法GEvent.addDomListener()为DOM节点上的DOM事件注册事件处理程序。类似地，静态方法GEvent.bindDom()允许为类实例上的DOM事件注册事件处理程序。

5.2.7删除事件侦听器

当不再需要一个事件侦听器时，应将其删除。甚至在事件仅需要触发一次的情况下，也可能需要进行此操作。删除closure内的匿名函数所定义的事件侦听器十分困难，不过addListener()、addDomListener()和bind()函数都返回bindDom()句柄，它可以用于最终取消注册处理程序。

以下实例响应单击，在地图上添加标注。之后的任何单击将会删除该事件侦听器。注意结果将不再执行removeOverlay()代码。同时，请注意甚至可以从事件侦听器本身的内部

查看示例(event-removal.html)

5.3控件

5.3.1控件概述

https://www.sodocs.net/doc/fd13936082.html,（或https://www.sodocs.net/doc/fd13936082.html,）上的地图包含允许用户与地图交互的UI元素。这些元素称为控件，可以在Google地图API应用程序中包含这些控件的变种。还可以通过建立GControl类的子类构建自己的定制控件。

地图API带有大量可以在地图中使用的内置控件：

GlargeMapControl：在Google地图上使用的大号平移/缩放控件。默认情况下位于地图的左上角。

GsmallMapControl：在Google地图上使用的小号型平移/缩放控件。默认情况下位于地图的左上角。

GsmallZoomControl：在Google地图上用于显示驾车方向的小地图弹出窗口中使用的小号缩放控件（无平移控件）。

GscaleControl：地图比例尺

GoverviewMapControl：位于屏幕一角，可折叠的缩略图。

所有这些控件都是基于GControl对象。

5.3.2向地图添加控件

使用GMap2方法addControl()向地图添加控件。例如，要将在Google地图上看到

GScaleControl控件，分别可以平移/缩放地图，以及显示地图比例尺。在地图中添加标

查看示例(control-simple.html)

5.3.3在地图上放置控件

addControl方法有一个可选的第二参数GControlPosition，可以指定该控件在地图上的位置，如果不包含此参数，则地图API将使用控件指定的默认位置。它可以是以下值之一，分别指定要放置控件的地图的一个角：

?G_ANCHOR_TOP_RIGHT

?G_ANCHOR_TOP_LEFT

?G_ANCHOR_BOTTOM_RIGHT

?G_ANCHOR_BOTTOM_LEFT

GControlPosition（可选）可以指定一个偏移值，表示放置的控件距离地图边多少像素。该偏移值使用GSize对象指定。

本示例会将GScaleControl添加到地图的右上角，边距为10像素。双击地图上的任

查看示例(control-positioning.html)

5.3.4定制地图控件

Google地图API还允许创建GControl的子类而定制地图控件。（从技术角度上讲，不是使用JavaScript建立对象的"subclass"，而是将prototype对象分配给GControl对象的实例。）

要创建可用的定制控件，需要至少为该类的以下两个方法定义句柄：initialize()和getDefaultPosition()。initialize()方法必须返回DOM元素，而getDefaultPosition()方法必须返回类型为GControlPosition的对象。

所有地图控件均应添加到地图容器，后者可以通过GMap2的getContainer()方法访问。

在本示例中，创建一个简单的缩放控件，它使用文本链接而不是标准的Google地图缩

查看示例(control-custom.html)

5.4 地图叠加层

5.4.1地图叠加层概述

叠加层（Overlay）是地图上绑定到经纬度坐标的对象，会随拖动或缩放地图而移动。叠加层表现为“添加”到地图上以指明点、线或区域的对象。

地图API有如下几种叠加层：

◆地图上的点使用标记（Marker）显示，经常使用定制图标。标记是类型为GMarker

的对象，可以使用GIcon类型。

◆地图上的线使用折线（Polyline）（表示点的集合）显示。线是类型为GPolyline

的对象。

◆地图上的区域显示为多边形（Polygon）（如果是任意形状的区域）或底面叠加层

（Groundoverlay）（如果是矩形区域）。多边形类似于由闭环点集合组成的折线，可以是任意形状。底面叠加层常用于将地图上一块矩形区域的底图设置为某个图

片。

◆地图本身使用图块叠加层（Tileoverlay）显示。可以通过GTileLayerOverlay

来使用自己的一组图块，或者通过使用GMapType创建自己的地图类型

◆信息窗口也是一种特殊的叠加层。但是，请注意信息窗口会自动添加到地图，并且

仅有一个类型为GInfoWindow的对象与一个地图关联。

每个叠加层都实现GOverlay接口。可以使用GMap2.addOverlay()方法向地图添加叠加层，使用GMap2.removeOverlay()方法删除叠加层。（注意信息窗口默认情况下会自动添加到地图。）

5.4.2标记

标记标识地图上的点。默认情况下，它们使用G_DEFAULT_ICON（也可以指定定制的图标）。GMarker构造函数取GLatLng和GMarkerOptions（可选）对象作为参数。

标记设计为可交互。例如，默认情况下它们接收"click"事件，常用于在事件侦听器中打开

查看示例(marker-simple.html)

1．可拖拽标记

标记是可以单击和拖到新位置的交互对象。在本示例中，将一个可拖拽标记放在地图上，并侦听其若干简单事件。可拖拽标记实现以下四种事件：click、dragstart、drag和dragend，来表示其拖拽状态。默认情况下，标记可单击但不可拖拽，所以它们需要通过将额外的标记选项draggable设置为true来初始化。可拖拽标记默认情况下会弹跳。如果不

查看示例(marker-drag.html)

2．图标

标记可以用自定义的新图标来显示，以替代默认图标。因为地图API中单个图标由多个不同的图像组成，所以定义图标非常复杂。一个图标最少应定义前景图像、类型为GSize 的尺寸和用于放置图标的图标偏移值。

最简单的图标的基础是G_DEFAULT_ICON类型。基于此类型创建图标可以通过仅修改若干属性即可快速更改默认图标。

在下面的示例中，使用G_DEFAULT_ICON类型创建一个图标，然后将其修改为使用其他图像。（使用不同图像时要谨慎，因为它们需要设置为与默认图像相同的正确尺寸才能正

查看示例(icon-simple.html)

多数图标包含前景图像和阴影图像。阴影图像应是以45度角（向右上方）看前景图像所对应的阴影，阴影图像的左下角应与图标前景图像的左下角对齐。阴影图像应是半透明的24位PNG图像，以便图像边界可以在地图上正确显示。

以下示例使用Google Ride Finder的“迷你”标记作为示例。必须指定前景图像、阴影图像以及将图标锚定在地图上和将信息窗口锚定到图标的一些点。请注意该图标通过

GMarkerOptions

用构造函数实例化的，而是使用名-值对进行简单声明。

查看示例(icon-complex.html)

3．定制图标

GIcon对象也有若干其它属性，应将其适当设置，以便为图标获取最大的浏览器兼容性和功能。例如，imageMap属性指定图标图像不透明部分的形状。如果不在图标中设置此属性，则在Firefox/Mozilla中整个图标图像（包括透明部分）都将是可单击的。

在许多情况下，图标可以有不同的前景，但具有相同的形状和阴影。实现这点最简单的方式是使用GIcon类的复制构造函数（它将所有属性复制到新的图标），然后再对其进行

查看示例(icon-custom.html)

4．使用标记管理器

向Google地图添加大量标记可能会降低显示地图的速度，也会产生太多视觉混乱，尤其是在处于某些缩放级别时。标记管理器工具提供了一个解决这些问题的方案，允许在同一个地图上高效显示数百个标记，并能够指定应显示标记的缩放级别。

标记管理器工具包在GMaps Utility Libaray中提供。该库是开放源代码，包含不属于核心Google地图API的工具包。要添加该库中的工具包，可以使用