Google Maps JavaScript API V3 基础知识

欢迎使用最近更新的 Google Maps JavaScript API V3 正式版！该版本 JavaScript API 现在正式取代了 Google Maps JavaScript API 第 2 版。两个版本看起来类似，但在内在机制方面有了较大的变化：第 3 版（在本文档中称为 V3）旨在实现快速载入，尤其是在移动浏览器上，如基于 Android 的设备和 iPhone™。

欢迎您在 Google Maps JavaScript API V3 论坛上对此版本的 Google Maps API 发表反馈和评论意见。

欢迎使用第 3 版

欢迎使用第 3 版的 Google Maps API。这一版本的 Javascript API 看上去会与现有的第 2 版的 Google Maps API 相似。但两者在内在机制方面有了较大的变化：第 3 版（在本文档中称为 V3）旨在实现快速载入，尤其是在移动浏览器上，例如基于 Android 的设备和 iPhone™。与 V2 API 中所提供的地图项集相比，V3 首次发布的版本中提供了较小的地图项集。我们会将其他地图项从 V2 迁移到 V3，同时尽量确保使用较少的 JavaScript 代码，并保持优化过的载入速度。欢迎您在 Google Maps API 第 3 版论坛上对此版本的 Google Maps API 发表反馈意见和评论意见。

我们已经使用已修改过的 MVC 框架，实现了这一最新版本的 Google Maps API。例如，MVC 对象（如地图）的所有状态更改都是通过特定格式的“setter”和“getter”进行处理的。此外，MVC 对象的所有状态均存储为该对象的属性，而通过事件处理程序对状态更改所作的所有观测也都是特定的格式。

此 API 已特别强调了在移动浏览器上启用可靠而快速的地图。我们建议您在移动设备上试用此 API，并在上文提到的论坛中发布有关特定设备问题的帖子。

请注意：此版本的 Google Maps Javascript API 不再需要 API 密钥！

受众

本文档适用于熟悉 JavaScript 编程以及面向对象编程概念的读者。您还应该从用户的角度熟悉 Google Maps。您可以从网络上找到很多 Javascript 辅导手册。

本文档是概念性文档，旨在帮助您快速开始使用 Google Maps API 探索和开发很酷的应用程序。我们还发布了 Google Maps API 参考。

本概念性文档分为以下几部分：

• 基本地图对象
• 地图事件
• 地图控件
• 地图叠加层
• 地图服务

欢迎您对此版本的 API 及其文档提出反馈意见。请一定要将反馈意见发布到 Google Maps Javascript API 第 3 版网上论坛中。

地理定位

地理定位指通过各种数据收集机制识别用户或计算设备的地理位置。通常而言，大多数地理定位服务使用网络路由地址或内部 GPS 设备来确定该位置。请注意，地理定位是特定于设备的 API。某些浏览器/设备支持地理定位，但某些则不支持（或无法支持），因此您不能始终假定网络应用程序具备该功能。

检测用户位置

目前，在浏览器中可通过以下几种方式检测用户的位置。这些方法都不属于 Google Maps API，而是公用的行业标准。

• 一些较新版本的浏览器正开始支持 W3C Geolocation 标准。此标准是 HTML5 的一部分，以后很可能会成为真正的标准。所有希望执行地理定位的应用程序都应当支持此标准。
• 某些带 Google Gears 的浏览器可以使用 Google Gears Geolocation API。由于即将实现对 W3C 标准的广泛支持，因此，检查 Gears 不失为一项好的后备方案。
• 某些浏览器使用 IP 地址来检测用户的位置，不过这种方式只能提供很粗略的估计。

由于用户的 IP 地址只能提供对用户位置的粗略估计，因此我们不建议使用这种地理定位方法。W3C 是最简单且支持最广泛的方法，应优先采用此方法，然后再考虑其他方法。如果您决定使用 Google Gears，那么首先应检查浏览器是否支持 W3C 标准。（请注意，如果您要使用 Google Gears，则需要载入 Gears 初始化 JavaScript。）

下例首先尝试通过 W3C navigator.geolocation 属性确定用户位置，然后尝试 Google Gears 方法，如果两种方法都无效则放弃。

// Note that using Google Gears requires loading the Javascript  // at http://code.google.com/apis/gears/gears_init.js    var initialLocation;  var siberia = new google.maps.LatLng(60, 105);  var newyork = new google.maps.LatLng(40.69847032728747, -73.9514422416687);  var browserSupportFlag =  new Boolean();    function initialize() {    var myOptions = {      zoom: 6,      mapTypeId: google.maps.MapTypeId.ROADMAP    };    var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);        // Try W3C Geolocation (Preferred)    if(navigator.geolocation) {      browserSupportFlag = true;      navigator.geolocation.getCurrentPosition(function(position) {        initialLocation = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);        map.setCenter(initialLocation);      }, function() {        handleNoGeolocation(browserSupportFlag);      });    // Try Google Gears Geolocation    } else if (google.gears) {      browserSupportFlag = true;      var geo = google.gears.factory.create('beta.geolocation');      geo.getCurrentPosition(function(position) {        initialLocation = new google.maps.LatLng(position.latitude,position.longitude);        map.setCenter(initialLocation);      }, function() {        handleNoGeoLocation(browserSupportFlag);      });    // Browser doesn't support Geolocation    } else {      browserSupportFlag = false;      handleNoGeolocation(browserSupportFlag);    }        function handleNoGeolocation(errorFlag) {      if (errorFlag == true) {        alert("Geolocation service failed.");        initialLocation = newyork;      } else {        alert("Your browser doesn't support geolocation. We've placed you in Siberia.");        initialLocation = siberia;      }      map.setCenter(initialLocation);    }  }

查看示例 (map-geolocation.html)

指定传感器参数

使用 Google Maps API 会要求您指明您的应用程序是否在使用传感器（例如 GPS 定位器）确定用户的位置。这对移动设备尤为重要。应用程序必须将所需的 sensor 参数传递给包含 Maps API JavaScript 代码的 <script> 标记，以指示您的应用程序是否正在使用传感器设备。

在载入 Google Maps API Javascript 时，通过传感器确定用户位置的应用程序必须传递 sensor=true。

#  # Example using sensor when loading the Maps JavaScript API  #  <script type="text/javascript" src="https://maps.google.com/maps/api/js?sensor=true"></script>

请注意，即使您的设备并没有使用传感设备，您仍然需要传递此参数，将参数值设为 false。

针对移动设备（iPhone 和 Android 设备）的开发

Google Maps API 第 3 版的设计旨在实现快速载入，并使其在移动设备上稳定运行。尤其是我们早已专注于对高级移动设备的开发，例如 iPhone 和运行 Android 操作系统的手机。与传统的桌面浏览器相比，移动设备的屏幕尺寸更小。而且，移动设备通常具备其独有的特定行为（例如 iPhone 上的“触摸缩放”）。如果您想让自己的应用程序在移动设备上稳定运行，我们建议您进行以下操作：

• 将包含地图的 <div> 设置为具有 100% 的宽度属性和高度属性。但请注意，在一些旧版的桌面浏览器上使用这些值不会得到良好的显示效果。

• 您可通过检查 DOM 中的 navigator.userAgent 属性检测 iPhone 和 Android 设备：

  function detectBrowser() {    var useragent = navigator.userAgent;    var mapdiv = document.getElementById("map_canvas");          if (useragent.indexOf('iPhone') != -1 || useragent.indexOf('Android') != -1 ) {      mapdiv.style.width = '100%';      mapdiv.style.height = '100%';    } else {      mapdiv.style.width = '600px';      mapdiv.style.height = '800px';    }  }

  这样，您就可以改变特定设备的布局，正如我们在此更改每个设备的屏幕实际使用面积。

• iPhone 设备符合以下 <meta> 标签：

  <meta name="viewport" content="initial-scale=1.0, user-scalable=no" />

  这一设置指定应当以全屏模式显示该地图，且用户不能调整地图的大小。运行 1.5 版软件 (Cupcake) 的 Android 设备同样可以支持这些参数。请注意，要使用 iPhone 的 Safari 浏览器，您需要在网页的 <head> 元素中添加此 <meta> 标签。

有关 iPhone 开发的详细信息，请参考 Apple 的开发人员文档。有关 Android 设备开发的详细信息，请参考 Android 文档。

Google Maps API V3 的本地化

您可以通过更改默认语言设置和设置应用程序的区域代码来本地化您的 Google Maps API 应用程序，从而根据给定的国家或地区改变应用程序的运行方式。

语言本地化

Google Maps API 在显示文本信息（如控件名称、版权声明、行车路线和地图上的标签）时，使用浏览器的首选语言设置。大多数情况下，这是可取的做法，通常您不会想覆盖用户的首选语言设置。不过，如果您希望更改 Google Maps API 以忽略浏览器的语言设置，并强制浏览器采用特定语言显示信息，那么可以将可选的 language 参数添加到包含 Maps API JavaScript 代码的 <script> 标记，以指定要使用的语言。

例如，要用日语显示 Google Maps API 应用程序，可将 &language=ja 添加到 <script> 标记，如下所示：

<script type="text/javascript" src="https://maps.google.com/maps/api/js?sensor=false&language=ja">

注意：按照上述方式载入 API 后，不论用户使用的是何种偏好设置，系统都将对所有用户显示日语。在设置此选项之前，请确保您确实希望这么做。

查看示例 (map-language.html)

Google Maps JavaScript API 还支持双向 (Bidi) 文本，即同时包含从左到右 (LTR) 及从右到左 (RTL) 语言字符的文本。例如，阿拉伯语、希伯来语和波斯语都属于 RTL 语言。通常，您应当将 dir='rtl' 添加到网页的 <html> 元素中，以正确渲染 RTL 语言网页。下例渲染一幅采用阿拉伯语控件的埃及开罗地图。

查看示例 (map-rtl.html)

另请参见支持的语言列表。请注意，我们会经常更新支持的语言，因此该列表可能并不详尽。

区域本地化

默认情况下，Google Maps API 根据载入 API 的主域所在的国家/地区（对于 maps.google.com，为美国），提供地图图块并修正应用程序行为。如果您希望更改应用程序以提供不同的地图图块或修正应用程序（如修正地址解析结果使之靠近某区域），那么可以将 region 参数添加到包含 Maps API JavaScript 代码的 <script> 标记中，以覆盖该默认行为。

region 参数接受 Unicode 区域子标记标识符，该标识符通常与国家及地区代码顶级域名 (ccTLD) 具有一对一的映射关系。除某些明显不同之外，大多数 Unicode 区域标识符与 ISO 3166-1 代码是一样的。例如，英国的 ccTLD 为“uk”（对应于域名 .co.uk），但其区域标识符为“GB”。

例如，要将 Google Maps API 应用程序本地化到英国，可将 &region=GB 添加到 <script> 标记中，如下所示：

<script type="text/javascript" src="https://maps.google.com/maps/api/js?sensor=false&region=GB">

下例显示两幅地图，一幅根据默认区域（美国）将“托莱多”地址解析为“俄亥俄州托莱多”，另一幅根据设置为 ES（西班牙）的 region 将结果修正为“西班牙托莱多”。

V3 Maps API 中的库

Maps API 的 JavaScript 代码是通过表单 http://maps.google.com/maps/api/js 的引导程序网址加载的。该引导程序请求会加载所有的 JavaScript 主对象和符号，以便在 Maps API 中使用。某些独立的库中也会提供一些 Maps API 地图项，不过这些库只会在您专门提出请求时才会加载。将补充的组件分解为库可以提高主 API 的加载（和解析）速度；只有在您需要库时才会引起加载和解析库的额外负担。

要指定在引导程序请求内加载的其他库，您可以指定 libraries 参数，并向该参数传递相关库的名称。可将多个库指定为以英文逗号分隔的列表。加载后，系统会通过 google.maps.libraryName 命名空间访问各库。

当前可用的库有：

• geometry 包含实用工具函数，用于计算地球表面的标量几何值（例如距离和面积）。有关详情，请查看几何图形库文档。
• adsense 可让您的 Maps API 应用程序加入适合具体环境的文本广告，从而让您通过向用户显示广告来获取广告收益。有关详情，请查看 AdSense 库文档。
• panoramio 所包含的地图项可用于将 Panoramio 照片图层添加到 Maps API 应用程序中。有关详情，请查看 Panoramio 图层文档。

我们日后还会发布其他用户自选的地图项，因而会添加更多的库。

下面的引导程序请求说明了如何请求 Maps JavaScript API 的 google.maps.geometry 库：

<script type="text/javascript" src="https://maps.google.com/maps/api/js?libraries=geometry&sensor=true_or_false"></script>

通过 HTTPS 加载 API

您可以通过 HTTPS 访问 Google Maps JavaScript API，以便在自己的 HTTPS 安全应用程序中使用该 API。要通过 HTTPS 加载 Google Maps JavaScript API 第 3 版，请从以下网址进行加载：

<script src="https://maps-api-ssl.google.com/maps/api/js?v=3&sensor=true_or_false"
type="text/javascript"></script>

通过 HTTPS 加载 Google Maps JavaScript API V3 可让您的应用程序在借助 HTTPS 受到保护的页面内使用 Maps API：基于安全套接字层 (SSL) 的 HTTP 协议。在 SSL 应用程序中必须通过 HTTPS 加载 Maps API，这样可以避免在大部分浏览器中显示安全警告，而对于在请求中包含敏感用户数据（例如用户所处位置）的应用程序而言，这也是推荐做法。

异步加载 JavaScript API

一般来说，如果您是通过以下方法加载页面的话，那么 JavaScript Maps API 会在页面加载时立即加载：即使用 <script> 标记加入 API 并在脚本加载完毕后执行应用程序 JavaScript 代码。然而，当解析该 JavaScript 时，您的浏览器可能不会在页面上呈现其他内容。大部分情况下，这一延迟并不会引起注意，但是您可能会希望在页面加载完毕后再加载 Maps API JavaScript 代码，或者根据需要加载 Maps API JavaScript。

要在页面加载完毕后再加载 Maps JavaScript API，方法十分简单：您只需插入自己的 <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 myLatlng = new google.maps.LatLng(-34.397, 150.644);    var myOptions = {      zoom: 8,      center: myLatlng,      mapTypeId: google.maps.MapTypeId.ROADMAP    }    var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);  }      function loadScript() {    var script = document.createElement("script");    script.type = "text/javascript";    script.src = "http://maps.google.com/maps/api/js?sensor=false&callback=initialize";    document.body.appendChild(script);  }      window.onload = loadScript;

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

版本管理

Google Maps API 小组将根据新增地图项、错误修复和性能改进定期更新此 JavaScript API 版本。所有 API 更改均向后兼容，以确保您启动应用程序时使用的是当前记录的界面，且当 API 更新后应用程序可以无修改地继续运行。（注意：本保证中不包含试验性地图项。试验性地图项将在 API 文档中明确标出。）

版本类型

您可以指定在应用程序中载入哪个版本的 API，方法是使用 Google Maps JavaScript API 引导程序请求的 v 参数指定版本。系统目前支持以下两个选项：

• 夜间（开发）版本，可使用 v=3 或省略 v 参数来指定。该版本是以主干版本为基础的当前版本，包含公开发布的任何错误修复和新增地图项。
• 编号版本，用 v=3.number 表示，指定了 API 的地图项集。这些编号版本可以是发行版本，也可以是冻结版本。（如下所示。）

下面的引导程序请求演示了如何请求具体版本的 Google Maps JavaScript API：

http://maps.google.com/maps/api/js?v=3.3&sensor=true_or_false

每个季度，我们都会构建新的编号版本（“发行版本”）并公开发布。在整个季度期间，在确保地图项集保持稳定的同时，我们还会继续向此发行版本中添加错误修复，Google Maps JavaScript API 更改日志将会对此进行记录。

当我们发行新的编号版本时，将会“冻结”之前的发行版本，这表示我们不再对其进行任何代码更改更新（包括错误修复），以确保其充分的稳定性。每次我们以此方式推出新的冻结版本时，都会停用现有的冻结版本。也就是说，在任何指定的时间段内，我们只会提供一个冻结版本。请求已停用的编号版本的应用程序将会自动收到当前的冻结版本。

选择 API 版本

在为 Maps API V3 应用程序选择合适的 API 版本时，可参考以下指南：

• 生产应用程序应始终指定次要版本（如 3.6、3.7 等）。
• Maps API 专业版 SLA 不适用于当前的夜间（开发）版本。Maps API 专业版应用程序必须使用当前的发行版本或较早版本，这样才能涵盖在 SLA 内。
• 当开发新的 Maps API v3 应用程序时，我们建议您按照版本编号（如 3.5）选择使用最新的夜间版本，直到您需要添加更新的版本中所提供的其他地图项时再改用其他版本。这样，您使用的版本会随着应用程序的开发而日趋成熟，并会在一段时间后变为发行版本，最终成为冻结版本。
• 请求当前冻结版本或较早版本的生产应用程序应在每季度对最新的发行版本进行测试，以便在该版本冻结前识别有关向后兼容性方面的任何问题。

版本文档

文档将始终反映夜间（开发）版本。不过，我们会针对每个版本提供一份单独进行维护的参考。

• 夜间版本 (3.8) 参考（当前）
• 发行版本 (3.7) 参考（功能稳定）
• 发行版本 (3.6) 参考（冻结）
• 版本 3.0 - 3.5 已停用

问题排查

如果代码无法进行使用，以下一些方法可能会帮助您解决遇到的问题：

• 查找拼写错误。请注意，JavaScript 语言区分大小写。
• 使用 Javascript 调试器。在 Firefox 中，您可以使用 JavaScript 控制台、Venkman 调试器或 Firebug 插件。在 IE 中，您可以使用 Microsoft Script Debugger。该系列截屏视频演示了如何使用各种调试工具。
• 请将问题发布到 Google Maps API 第 3 版网上论坛中。