Google Maps JavaScript API 使用入门

受众

本文适用于熟悉 JavaScript 编程和面向对象编程概念的读者。您还应该从用户的角度熟悉 Google 地图。您可以从网上找到很多 JavaScript 教程

本文属于概念性文档,旨在帮助您快速开始使用 Google Maps API 探索和开发应用。我们还发布了 Google Maps API 参考

获取 API 密钥

所有的 Maps API 应用*都应使用 API 密钥加载 Maps API。使用 API 密钥可让您监控应用的 Maps API 使用情况,并确保 Google 能够在需要时与您联系讨论您的应用。如果您应用的 Maps API 使用次数超出使用限制,就必须使用 API 密钥加载 Maps API 来购买额外配额。

*Google Maps API for Business** 开发者不得在其请求中加入密钥。__有关 Business 专用说明,请参考加载 Google Maps JavaScript API

要创建 API 密钥,请执行以下操作:

  1. 访问 API 控制台(网址为 https://code.google.com/apis/console)并使用您的 Google 帐户登录。
  2. 点击左侧菜单中的服务链接。
  3. 激活 Google Maps API v3 服务。
  4. 点击左侧菜单中的 API 访问链接。您可以从 API 访问页上的简单 API 访问部分获取 API 密钥。Maps API 应用会使用适用于浏览器应用的密钥

默认情况下,密钥可在任何网站上使用。强烈建议您将自己的密钥限制为在您所管理的域中使用,以防止未授权的网站使用该密钥。针对您的密钥点击修改允许的引用者... 链接,即可指定要允许哪些域使用该 API 密钥。

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 onload="initialize()">  
    <div id="map_canvas" style="width:100%; height:100%"></div>  
  </body>  
</html>

查看示例 (map-simple.html)

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

  1. 在此示例中,使用 <!DOCTYPE html> 声明将应用声明为 HTML5。
  2. 使用 script 标记加入 Maps API JavaScript。
  3. 创建一个名为“map_canvas”的 div 元素以存储该地图。
  4. 创建 Javascript 对象常量以存储若干地图属性。
  5. 编写 JavaScript 函数以创建“map”对象。
  6. 通过 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 密钥。有关详情,请参阅获取 API 密钥。请注意,此密钥不适用于 v2 API,且必须通过 API 控制台生成。

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

有关如何在应用中加载 Maps API 的重要信息,Google Maps API for Business 用户应参考 Business 文档中的加载 Google Maps JavaScript API

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 提供其他功能的代码模块,不过只有在您专门请求时才会加载。有关详情,请参阅 V3 Maps 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;

查看示例 (map-simple-async.html)

地图 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 内的地图图片会被分割为地图“图块”和“缩放级别”两部分。在低缩放级别下,一小组地图图块就可以覆盖广阔的区域;而在高缩放级别下,图块的分辨率较高,覆盖的区域则较小。

以下三张图片分别反映了东京的同一位置在缩放级别为 0、7、18 下的情景。

  

如需了解 Maps API 是如何根据当前缩放级别加载图块的,请参阅“地图类型”文档中的图块坐标

地图类型

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

mapTypeId: google.maps.MapTypeId.ROADMAP

系统支持以下地图类型:

有关地图类型的详情,请参阅地图类型部分。不过大部分情况下,了解如何使用上述基本类型即可满足您的需求。

地图对象

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_](https://developers.google.com/maps/documentation/javascript/tutorial?hl=zh-cn#MapOptions)) 使用传递的任何(可选)参数在给定的 HTML 容器(通常为 DIV 元素)中创建新的地图。

加载地图

  <body onload="initialize()">

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

body 标记的 onload 属性为一个事件处理程序示例。Google Maps JavaScript API 还提供了一组事件,供您处理以确定状态变化。有关详情,请参阅地图事件