Google 地图 API V3 使用入门1

Hello, World

要开始了解 Google Maps API，最简单的方法就是查看简单的示例。以下网页显示了一张以澳大利亚新南威尔士的悉尼为中心的地图：

<!DOCTYPE html>
<html><head><meta name="viewport" content="initial-scale=1.0, user-scalable=no" /><style type="text/css">html { height: 100% }body { height: 100%; margin: 0; padding: 0 }#map_canvas { height: 100% }</style><script type="text/javascript"src="http://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=SET_TO_TRUE_OR_FALSE"></script><script type="text/javascript">function initialize() {var mapOptions = {center: new google.maps.LatLng(-34.397, 150.644),zoom: 8,mapTypeId: google.maps.MapTypeId.ROADMAP};var map = new google.maps.Map(document.getElementById("map_canvas"),mapOptions);}</script></head><body οnlοad="initialize()"><div id="map_canvas" style="width:100%; height:100%"></div></body>
</html>

尽管此示例较为简单，也请注意以下事项：

在此示例中，使用 <!DOCTYPE html> 声明将应用声明为 HTML5。
使用 script 标记加入 Maps API JavaScript。
创建一个名为“map_canvas”的 div 元素以存储该地图。
创建 Javascript 对象常量以存储若干地图属性。
编写 JavaScript 函数以创建“map”对象。
通过 body 标记的 onload 事件初始化该地图对象。

下面对这些步骤进行了说明。

将您的应用声明为 HTML5

建议您在自己的网络应用内声明一个真实的 DOCTYPE。在本文的示例中，我们使用简单的 HTML5 DOCTYPE 将应用声明为 HTML5，如下所示：

<!DOCTYPE html>

当前的大多数浏览器会以“标准模式”呈现使用此 DOCTYPE 声明的内容，这意味着您的应用应具有更强的跨浏览器适应能力。DOCTYPE 还设计为可适度降级；无法理解该声明的浏览器会将其忽略，并使用“兼容模式”来显示其内容。

请注意，某些在兼容模式下工作的 CSS 在标准模式中是无效的。具体地说，所有以百分比表示的大小必须继承自父块元素，而如果这些父元素中的某个父元素没有指定大小，则系统会将其大小假定为 0x0 像素。因此，我们加入了以下 <style> 声明：

<style type="text/css">html { height: 100% }body { height: 100%; margin: 0; padding: 0 }#map_canvas { height: 100% }
</style>

该 CSS 声明用于表示地图容器 <div> （名为 map_canvas ）应占据 HTML 主体的整个高度。请注意，我们还必须明确声明 <body> 和 <html> 所占的百分比。

加载 Google Maps API

<html><head><script type="text/javascript"src="http://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=SET_TO_TRUE_OR_FALSE"></script>

script 标记中包含指向 JavaScript 文件所处位置的网址，该 JavaScript 文件可加载使用 Google Maps API 所需的所有符号和定义。script 为必填标记。

key 参数包含您应用的 API 密钥。请注意，此密钥不适用于 v2 API，且必须通过 API 控制台生成。V3版本不需要。

网址的 sensor 参数（必须添加）用于表示应用是否会使用 GPS 定位器等传感器来确定用户的位置。在此示例中，我们将该参数设为变量“set_to_true_or_false”，用于强调您必须将该值明确设为 true 或 false。

HTTPS

如果您的应用是 HTTPS 应用，那么您可改为通过 HTTPS 加载 Google Maps JavaScript API：

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=SET_TO_TRUE_OR_FALSE"type="text/javascript"></script>

在 SSL 应用中必须通过 HTTPS 加载 Maps API，以免在大多数浏览器中显示安全警告，并且建议您对请求中包含用户所处位置等敏感用户数据的应用也采用该做法。

库

在通过 http://maps.googleapis.com/maps/api/js 网址加载 JavaScript Maps API 时，您也可以选择使用 libraries 参数加载其他库。库是用于向主 JavaScript API 提供其他功能的代码模块，不过只有在您专门请求时才会加载。

异步加载 API

您可能希望在网页完全加载后或根据需要加载 Maps API JavaScript 代码。为此，您可以插入自己的 <script> 标记作为针对 window.onload 事件或函数调用的响应，不过您还需要指示 Maps JavaScript API 引导程序在 Maps JavaScript API 代码完全加载后再执行应用代码。要实现此目的，您可以使用 callback 参数，该参数为函数要在 API 完全加载后执行的变量。

以下代码指示应用在网页完全加载后再加载 Maps API（使用 window.onload），并在该网页中将 Maps JavaScript API 写入 <script> 标记。此外，我们还向 Maps API 引导程序传递了 callback=initialize，从而指示该 API 仅在自身完全加载后执行 initialize() 函数：

function initialize() {var mapOptions = {zoom: 8,center: new google.maps.LatLng(-34.397, 150.644),mapTypeId: google.maps.MapTypeId.ROADMAP}var map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions);
}function loadScript() {var script = document.createElement("script");script.type = "text/javascript";script.src = "http://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=TRUE_OR_FALSE&callback=initialize";document.body.appendChild(script);
}window.onload = loadScript;

地图 DOM 元素

<div id="map_canvas" style="width: 100%; height: 100%"></div>

对于要在网页上显示的地图，我们需要为其留出一个位置。通常，我们会创建一个名为 div 的元素，然后在浏览器的文档对象模型 (DOM) 中获取对此元素的引用。

在以上示例中，我们定义了一个名为“map_canvas”的 <div>，并使用样式属性为其设置大小。请注意，这一大小已设置为“100％”，这将会展开地图，使之符合移动设备的屏幕大小。您可能需要根据浏览器的屏幕大小和填充区域调整这些值。请注意，地图将始终根据其中所包含的元素的大小决定其本身大小，因此，您必须始终为 <div> 明确设置一个适用的大小。

地图选项

var mapOptions = {center: new google.maps.LatLng(-34.397, 150.644),zoom: 8,mapTypeId: google.maps.MapTypeId.ROADMAP
};

要初始化地图，我们需要先创建一个 Map options 对象来包含地图初始化变量。该对象不是构建出来的，而是以对象常量的形式创建得到的。

var mapOptions = {};

纬度和经度

由于我们要通过 center 将地图中心设为特定的点，因此会创建 LatLng 对象，同时按 {纬度,经度} 的顺序传递位置的坐标，以存储该位置：

center = new google.maps.LatLng(-34.397, 150.644)

将地址转换为地理地点的过程称为“地理编码”。此版本的 Google Maps API 支持地理编码。有关详情，请参阅此指南的服务章节中的地理编码。

缩放级别

地图显示时的初始分辨率可以通过 zoom 属性进行设置，其中缩放 0 相当于地球地图可缩小的最低级别，并且缩放级别越高，地图放大的分辨率就越高。

zoom: 8

如果要将包含完整地球的地图作为单张图片提供，要么需要极大的地图，要么需要分辨率较低的小型地图。因此，Google 地图和 Maps API 内的地图图片会被分割为地图“图块”和“缩放级别”两部分。在低缩放级别下，一小组地图图块就可以覆盖广阔的区域；而在高缩放级别下，图块的分辨率较高，覆盖的区域则较小。

地图类型

此时，您还必须明确设置一个初始地图类型。

mapTypeId: google.maps.MapTypeId.ROADMAP

系统支持以下地图类型：

ROADMAP，用于显示 Google 地图的默认、普通 2D 图块。
SATELLITE，用于显示拍摄的图块。
HYBRID，用于同时显示拍摄的图块和重要地图项（道路、城市名）的图块图层。
TERRAIN，用于显示自然地形图块，其中包含海拔和水体地图项（山脉、河流等）。

地图对象

var map = new google.maps.Map(document.getElementById("map_canvas"),mapOptions);

用于代表地图的 JavaScript 类属于 Map 类。此类的对象定义了网页上的单个地图。（您可以创建多个此类的实例，每个对象都将在网页上定义一个单独的地图。）我们使用 Javascript new 运算符创建了一个此类的新实例。

创建新的地图实例时，您需要在网页中指定一个 <div> HTML 元素作为地图的容器。HTML 节点是 Javascript document 对象的子对象，我们通过document.getElementById() 方法获取了对该元素的引用。

此代码用于定义一个变量（名为 map），然后将其分配至新的 Map 对象，同时传递到 mapOptions 对象常量所定义的选项中。这些选项将用于初始化地图的属性。Map() 函数称为“构造函数”，其定义如下：

构造函数	说明
`Map(mapDiv:Node, opts?:MapOptions)`	使用传递的任何（可选）参数在给定的 HTML 容器（通常为 DIV 元素）中创建新的地图。

加载地图

<body οnlοad="initialize()">

呈现 HTML 网页时，系统会扩展文档对象模型 (DOM)，接收所有外部图片和脚本并将其合并到 document 对象中。为确保系统在网页完全加载后才将我们的地图放到网页上，我们只会在 HTML 网页的 <body> 元素收到 onload 事件后，才开始执行用于构建 Map 对象的函数。这样做可以避免出现意外行为，并让我们更好地控制地图的绘制方式和时间。

body 标记的 onload 属性为一个事件处理程序示例。Google Maps JavaScript API 还提供了一组事件，供您处理以确定状态变化。

Last updated 二月 1, 2013.