开发人员指南
地图基础知识
1简介
2Google 地图的“Hello, World”
2加载Google 地图API
2地图DOM 元素
2GMap2 - 基本对象
2初始化地图
2加载地图
3经度和纬度
4地图属性
5地图交互
6信息窗口
简介
任何Google 地图API 应用程序中的基础元素都是“地图”本身。本文档讨论GMap2基础对象的用法和地图操作的基础知识。
Google 地图的“Hello, World”
开始学习Google 地图API 最简单的方式是看一个简单的示例。下面的网页显示以北京的故宫博物院为中心的500x300 的地图。
您可以查看此示例及下载、编辑和调试该示例，但必须将该文件中的密钥替换为您自己的密钥。（如果注册了特定目录的密钥，也可以将其用于所有子目录。）即使在此简单的示例中，也需要注意五点：
7使用script标签包含Google 地图API JavaScript。
8创建名为“map_canvas”的div元素来包含地图。
9编写JavaScript 函数创建“map”对象。
10将地图的中心设置为指定的地理点。
11从body标签的onLoad事件初始化地图对象。
下面说明了这些步骤。
加载Google 地图API
https://www.doczj.com/doc/d72516799.html,/maps?file=api&v=2&key=abcdefg网址指向包含使用Google 地图API 所需所有符号和定义的JavaScript 文件的位置。您的页面必须包含指向此网址的script标签，使用注册API 时收到的密钥。在此示例中，该密钥显示为“abcdefg”。请注意，我们也传递sensor参数以指明此应用程序是否使用传感器来确定用户位置。在此示例中，我们将其设为变量“true_or_false”以强调您必须显式地将此值设置为true或false。
地图DOM 元素
要让地图在网页上显示，必须为其留出一个位置。通常，我们通过创建名为div的元素并在浏览器的文档对象模型(DOM) 中获取此元素的引用执行此操作。
在上述示例中，我们定义名为“map_canvas”的div，并使用样式属性设置其尺寸。地图会自动使用容器尺寸调整自身的尺寸，除非使用构造函数中的GMapOptions显式地为地图指定尺寸。
GMap2 - 基本对象
GMap2类是表示地图的JavaScript 类。此类的对象在页面上定义单个地图。（可以创建此类的多个实例，每个对象将在页面上定义一个不同的地图。）我们使用JavaScript new操作符创建此类的一个新实例。
当创建新的地图实例时，在页面中指定一个DOM 节点（通常是div元素）作为地图的容器。HTML 节点是JavaScript document对象的子对象，而且我们通过document.getElementById()方法获得该元素的引用。
此代码定义了一个变量（名为map），并将新GMap2对象赋值给该变量。函数GMap2()称为“构造函数”，其定义（在Google 地图API 参考中简述）如下所示：
请注意因为JavaScript 是松散类型的语言，我们可以不填写构造函数的任何可选参数，此处也未这样做。
初始化地图
通过GMap2构造函数创建地图后，我们需要再做一件事：将其初始化。初始化通过地图的setCenter()方法完成。setCenter()方法要求有GLatLng坐标和缩放级别，而且必须先发送此方法，然后再在地图上执行其他任何操作，包括设置地图本身的其他任何属性。
加载地图
当HTML 页面显示时，文档对象模型(DOM) 即会扩展，接收其他外部图像和脚本并将其合并到document对象中。为确保我们的地图仅放置在完全加载后的页面上，我们仅在HTML 页面的
元素收到onload事件后才执行构造GMap2对象的函数。这样做可以避免出现不可预期的行为，并使我们可以对地图绘制的方式和时间进行更多控制。onload属性是事件处理程序的示例。Google 地图API 还提供了大量事件可以用来“监听”状态变化。请参阅地图事件和事件监听器以了解更多信息。GUnload()函数是用来防止内存泄漏的实用工具函数。
经度和纬度
既然现在已经有地图了，我们还需要一种方法来引用地图上的位置。在Google 地图API 中，GLatLng对象提供了此类机制。可以构造一个GLatLng对象，按照制图学的惯例以{经度, 纬度} 的顺序传递参数：
注意：将“地址”转变为地理点的过程称为“地址解析”，将在“Google 地图API 服务”部分中详细讨论。
就像它可用于轻松地引用地理点一样，它也可用于定义对象的地理边界。例如，地图在称为视口的窗口内显示整个世界的当前“窗口”。此视口可以通过四个角上的矩形点来定义。GLatLngBounds对象提供了这个功能，通过使用分别表示边界框的西南角和东北角的两个GLatLng对象定义一个矩形区域来实现。
GLatLng对象在Google 地图API 中用途广泛。例如，GMarker对象在其构造函数中具有GLatLng，并在地图上的指定地理位置放置标记“叠加层”。
下面的示例使用getBounds()返回当前视口，然后在地图上的这些边界内随机放置10 个标记：
查看示例(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 地球的卫星视图：
地图还包含对了解情况非常有用的大量属性。例如，要了解当前视口的尺寸，可使用GMap2对象的getBounds()方法来返回GLatLngBounds值。
每个地图还包含一个“缩放级别”，用于定义当前视图的分辨率。在普通地图视图内，可以使用0（最低缩放级别，在地图上可以看到整个世界）到19（最高缩放级别，可以看到独立建筑物）之间的缩放级别。缩放级别因所查看地区而异，因为地球上某些地区的数据比其他地区更详细。在卫星视图中可以使用多达20 个缩放级别。
可以通过使用GMap2对象的getZoom()方法检索地图当前使用的缩放级别。
关于缩放级别、地图图块以及创建自己的自定义地图类型的更多信息，请参阅图块叠加层部分。
地图交互
既然现在有了GMap2对象，就可以与之进行交互了。基本地图对象的外观和行为与您在Google 地图网站上交互的地图非常相似，并带有大量内置行为。GMap2对象还提供了大量配置方法来改变地图对象本身的行为。
默认情况下，和在https://www.doczj.com/doc/d72516799.html,上一样，地图对象会对用户的活动做出反应。但您可以使用大量实用工具方法改变此行为。例如，GMap2.disableDragging()方法禁止了点击并拖拽地图到新位置的功能。
您还可以通过编程与地图交互。GMap2对象支持可以直接改变地图状态的大量方法。例如，setCenter()、panTo和zoomIn()方法通过编程来操作地图，而不是通过用户交互来操作地图。
下面的示例显示一个地图，等待两秒钟，然后平移到新中心点。panTo方法将地图中心设置在指定点处。如果指定点位于地图的可见部分，则地图会平稳地平移到该点，否则会跳至该点。
查看示例(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”。
查看示例(map-infowindow.html)
有关信息窗口的完整文档，请查阅Google 地图API 参考
事件
1地图事件概述
2事件监听器
3在事件监听器中使用闭包
4在事件中使用传递的参数
5将事件绑定到对象
6监听DOM 事件
7删除事件监听器
地图事件概述
浏览器中的JavaScript 是“事件驱动的”，这表示JavaScript 通过生成事件来响应交互，并期望程序能够“监听”感兴趣的活动。例如，在浏览器中，用户的鼠标和键盘交互可以创建在DOM 内传播的事件。对某些事件感兴趣的程序会为这些事件注册JavaScript 事件监听器，并在接收这些事件时执行代码。
Google 地图API 通过为地图API 对象定义自定义事件而添加到此事件模型中。请注意，地图API 事件是独立的，与标准DOM 事件不同。但是，由于不同的浏览器实现不同的DOM 事件模型，因此地图API 还提供监听和响应这些DOM 事件但无需处理各种跨浏览器特性的机制。
事件监听器
通过使用GEvent命名空间中的实用工具函数注册事件监听器，来处理Google 地图API 中的事件。每个地图API 对象都导出大量已命名的事件。例如，GMap2对象导出click、dblclick和move事件，以及其他许多事件。每个事件都在指定的环境下发生，并且可以传递标识环境的参数。例如，当用户在地图对象中移动鼠标时，会触发mousemove事件，并且该事件会传递鼠标所在地理位置的GLatLng。
有关GMap2事件及其生成的参数的完整列表，请参见GMap2.Events。
注册用来获取这些事件的相关通知的监听器，请使用静态方法GEvent.addListener()。该方法有三个参数，一个对象，一个待监听事件以及一个在指定事件发生时调用的函数。例如，每当用户点击地图时,下面的代码段都会显示警告:
查看示例(event-simple.html)
监听器也能够捕获事件的环境。在下面的示例代码中，显示用户拖动地图后地图中心的经度和纬度。
查看示例(event-context.html)
在事件监听器中使用闭包
当执行事件监听器时，一个常用的好方法就是将私有数据和持久性数据附加到一个对象。JavaScript 不支持“私有”实例数据，但它却支持闭包，闭包允许内部函数访问外部变量。在事件监听器中，访问通常不附加到发生事件的对象的变量时，闭包非常有用。
下面的示例在事件监听器中使用函数闭包将加密消息分配给一组标记。点击每个标记都可以看到加密消息的一部分，该消息并不包含在标记自身内部。
查看示例(event-closure.html)
在事件中使用传递的参数
地图API 事件系统中的许多事件在触发事件时都会传递参数。例如，如果地图点击发生在叠加层上，GMap2“点击”事件会传递overlay和overlaylatlng；否则，它传递地图坐标的latlng。可以通过将指定的符号直接传递给事件监听器中的函数来访问这些参数。在下面的示例中，我们首先进行测试，即检查是否定义了latlng参数，以确保点击发生在地图图块上；这样，我们就可以在坐标点的上方打开一个信息窗口，并在信息窗口中显示转化为像素的坐标以及地图的缩放级别。
查看示例(event-arguments.html)
将事件绑定到对象方法
当您希望将事件监听器附加到对象的特定实例时，函数非常有用。如果您不希望这样，而是希望响应事件时对象的所有实例都调用某方法，可以使用GEvent.bind()。在下面的示例中，MyApplication 的实例将地图事件与其成员方法绑定在一起，当触发事件时会修改类状态：
查看示例(event-bind.html)
监听DOM 事件
Google 地图API 事件模型创建并管理自己的自定义事件。但是，DOM 也会根据当前使用的特定浏览器事件模型创建和调度自己的事件。如果您希望捕获并响应这些事件，Google 地图API 提供的独立于浏览器的包装器可以监听和绑定DOM 事件而不需要自定义代码。
GEvent.addDomListener()静态方法为DOM 节点上的DOM 事件注册事件处理程序。同样，GEvent.bindDom()静态方法允许您为类实例上的DOM 事件注册事件处理程序。删除事件监听器
不再需要事件监听器时，应将其删除。甚至在事件只需触发一次的情况下，也可能需要删除。删除闭包内的匿名函数所定义的事件监听器可能很困难。但是，addListener()、addDomListener()、bind()和bindDom()函数会返回GEventListener句柄，可用来最终取消注册处理程序。
下面的示例通过在地图上放置标记来响应点击。任何后续点击都可删除事件监听器。请注意，这会导致不再执行removeOverlay()代码。另请注意，您甚至可以从事件监听器自身内部删除事件监听器。
查看示例(event-removal.html)
控件
1地图控件概述
2向地图添加控件
3在地图上放置控件
4修改标准控件的结构
5创建自定义控件
控件概述
https://www.doczj.com/doc/d72516799.html,上的地图包含允许用户与地图交互的UI 元素，这些元素称为“控件”。您可以在Google 地图API 应用程序中添加这些控件的多种组合。您还可以通过子类化GControl类来构建自己的自定义控件。
地图API 带有大量可以在地图中使用的内置控件：
?GLargeMapControl - 一个在Google 地图上使用的大平移/缩放控件。默认情况下显示在地图的左上角。
?GSmallMapControl - 一个在Google 地图上使用的小一点的平移/缩放控件。默
认情况下显示在地图的左上角。
?GSmallZoomControl - 小型缩放控件（无平移控件），用于在Google 地图上显示行车路线的小地图弹出窗口。
?GScaleControl - 地图比例尺
?GMapTypeControl - 让用户切换地图类型（例如“地图”和“卫星”）的按钮?GHierarchicalMapTypeControl- 用于放置多个地图类型选择器的一组精选的嵌套按钮和菜单项。
?GOverviewMapControl - 位于屏幕一角的可折叠概览地图。
所有这些控件都基于GControl对象。
GMapTypeControl和GHierarchicalMapTypeControl是特殊情况，因为它们还可以进行配置。这些控件增加的功能可以更改Google 地图API 中的地图当前所用的GMapType。有关配置这些控件的详细信息，请参见修改标准控件的结构。
下面是当前支持的地图类型列表：
?G_NORMAL_MAP显示Google 地图默认的普通二维图块
?G_SATELLITE_MAP显示拍摄的图块
?G_HYBRID_MAP同时显示拍摄的图块和普通（突出显示道路、城市名等明显地图特征）图块
?G_PHYSICAL_MAP根据地形信息显示实际地图图块
如果您有图像或者已经定义好的叠加层，也可以定义自己的自定义地图类型。
默认情况下，Google 地图API 提供三种地图类型：G_NORMAL_MAP、
G_SATELLITE_MAP和G_HYBRID_MAP。您可以通过这两种方式来改变地图上可用的地图类型：使用GMap2.removeMapType()删除地图类型；使用GMap2.addMapType()添加地图类型。无论您何时创建地图类型控件，它都使用当前地图上已经添加的地图类型，并通过控件让用户可以切换这些地图类型。请注意，您必须在添加地图类型控件（主要指GHierarchicalMapTypeControl）之前指定各地图类型之间的阶层关系，以便地图类型控件可以准确反映这些关系。
使用下面的代码可将G_HYBRID_MAP从添加到地图上的可用地图类型中删除，只剩下两种地图类型。添加GMapTypeControl后，便只有这两种地图类型可用。
查看示例(control-maptypes.html)
向地图添加控件
可以使用GMap2方法addControl()向地图添加控件。例如，要将Google 地图上显示的平移/缩放控件添加到您的地图中，您可以在您的地图初始化代码中添加下面这行语句：
可以向地图添加多个控件。在本例中，我们添加内置GSmallMapControl和GMapTypeControl控件，它们分别可以平移/缩放地图以及切换“地图”与“卫星”这两种类型。在地图中添加标准控件后，它们即刻完全生效。
查看示例(control-simple.html)
在地图上放置控件
addControl方法有第二个可选的参数GControlPosition，可用于指定控件在地图上的位置。它可以是以下值之一，这些值分别指定要放置控件的地图某个角：
?G_ANCHOR_TOP_RIGHT
?G_ANCHOR_TOP_LEFT
?G_ANCHOR_BOTTOM_RIGHT
?G_ANCHOR_BOTTOM_LEFT
如果不包含此参数，则地图API 会使用控件指定的默认位置。
GControlPosition还可以指定偏移量，来指示控件的放置位置与地图边界间隔多少像素。这些偏移量使用GSize对象指定。
本示例会将GMapTypeControl添加到地图的右上角，填充为10 个像素。双击地图上的任何位置可以删除该控件，将其放在地图的右下角。
查看示例(control-positioning.html)
请参见GControlPosition类参考以了解详细信息。
修改标准控件的结构
Google 地图API 内的大多数控件都提供具有标准行为的简单控件。但是，有些控件需要初始化才能正常使用。例如，GHierarchicalMapTypeControl通常需要一定的初始化才能在层叠“菜单”中以正确顺序显示地图类型。
此示例将带有十字准线图块层叠加层的G_PHYSICAL_MAP地图类型添加到地图中，然后创建GHierarchicalMapTypeControl来排列添加到地图的其他地图类型。
查看示例(control-initialization.html)
自定义地图控件
Google 地图API 还允许您通过子类化GControl来创建自定义地图控件。（您并没有在JavaScript 中实现一个“子类化”对象，而是把这个对象的prototype指定为GControl 对象的实例。）
要创建可用的自定义控件，您需要实现在该类中定义的至少两个方法：initialize()和getDefaultPosition()。initialize()方法必须返回DOM 元素，而getDefaultPosition()方法必须返回类型为GControlPosition的对象。
所有自定义的地图控件中的DOM 元素最终都应该添加到地图容器（也是DOM 元素）中去，这个地图容器可以通过GMap2getContainer()方法获得。
在此示例中，我们创建一个简单的缩放控件，它具有文本链接，而不是标准Google 地图缩放控件中使用的图形图标。
查看示例(control-custom.html)
地图叠加层
1地图叠加层概述
2标记
2可拖动的标记
2图标
2自定义图标
2标记管理器
3折线
3绘制折线
3测地折线
3编码折线
4多边形
5底面叠加层
6图块叠加层
6图块层叠加层
6自定义地图类型
Google 地图坐标
版权
投影
7层
8自定义叠加层
地图叠加层概述
叠加层是地图上绑定到经度/纬度坐标的对象，会随您拖动或缩放地图而移动。叠加层用于反映您“添加”到地图上以指明点、线或区域的对象。。
地图API 有如下几种叠加层：
?地图上的点使用标记来显示，通常显示自定义图标。标记是GMarker类型的对象，并且可以利用GIcon类型的对象来自定义图标。
?地图上的线使用折线（表示点的集合）来显示。线是类型为GPolyline的对象。
?地图上的区域显示为多边形（如果是任意形状的区域）或底面叠加层（如果是矩形区域）。多边形类似于闭合的折线，因此可以是任何形状。地面叠加层通常用于地图上与图块有直接或间接关联的区域。
?地图本身使用图块叠加层显示。如果您有自己的系列图块，可以使用GTileLayerOverlay类来改变地图上已有的图块，甚至可以使用GMapType来创建您自己的地图类型。
信息窗口也是一种特殊的叠加层。但是请注意，信息窗口会自动添加到地图中，并且地图只能添加一个类型为GInfoWindow的对象。
每个叠加层都实现GOverlay接口。可以使用GMap2.addOverlay()方法向地图添加叠加层，使用GMap2.removeOverlay()方法删除叠加层。（请注意，默认情况下信息窗口会自动添加到地图。）
标记
标记标识地图上的点。默认情况下，它们使用G_DEFAULT_ICON（您也可以指定自定义图标）。GMarker构造函数将GLatLng和GMarkerOptions（可选）对象作为参数。标记设计为可交互。例如，默认情况下它们接收"click"事件，常用于在事件侦听器中打开信息窗口。
查看示例(marker-simple.html)
可拖动的标记
标记是可以点击和拖动到新位置的交互式对象。在此示例中，我们将一个可拖动的标记放置在地图上，并监听它的几个较简单事件。可拖动标记通过实现以下四类事件来表示其拖动状态：click、dragstart、drag和dragend。默认情况下，标记可点击但不可拖动，所以它们需要通过将额外的标记选项draggable设置为true 来初始化。可拖动标记拖动结束后默认有弹跳效果。如果不喜欢这种效果，请将bouncy选项设置为false，标记会平缓放下。
查看示例(marker-drag.html)
图标（标记）
标记可以用自定义的新图标来显示，以替代默认图标。因为地图API 中一个图标（GIcon 对象）需要由多个不同的图像组成，所以定义图标较为复杂。一个图标最少应定义前景图像、类型为GSize的尺寸和用于定位图标的图标偏移值。
最简单的自定义图标是基于G_DEFAULT_ICON类型来创建。基于此类型创建图标让您仅通过修改若干属性即可快速更改默认图标。
在下面的示例中，我们先用G_DEFAULT_ICON类型创建一个图标，然后使用其他图像来改变默认图像。（使用不同图像时要谨慎，因为它们需要设置为与默认图像相同的正确尺寸才能正常显示。）
查看示例(icon-simple.html)
多数图标包含前景图像和阴影图像。阴影图像应该和前景图像成45 度夹角（向右上方倾斜），阴影图像的左下角应与图标前景图像的左下角对齐。阴影图像应是经过Alpha 透明处理的24 位PNG 图像，以便图像边界可以在地图上正确显示。
以下示例使用Google Ride Finder“迷你”标记为例，创建一种新类型的图标。我们必须指定前景图像、阴影图像以及一些将图标锚定到地图、将信息窗口锚定到图标的点。请注意该图标的参数都是通过GMarkerOptions中的选项来指定的。