Google 地图 API 概念

Google 地图 API 概念

欢迎阅读 Google 地图 API 的开发人员文档！Google 地图 JavaScript API 使您可以在网页中嵌入 Google 地图。要使用该 API，您需要先注册以获取 API 密钥。收到 API 密钥之后，即可以按照本文档中的说明开发地图应用程序。

新！Google 地图 API 支持反向地址解析！
目录

   1. 读者
   2. 创建 Google Mapplet
   3. 使用 Google AJAX API 加载程序
   4. Google 地图 API 的本地化
   5. 指定传感器参数 新！
   6. 编程说明
         1. 浏览器兼容性
         2. XHTML 和 VML
         3. API 更新
         4. 升级 Google 地图第 1 版应用程序
         5. 防止内存泄漏
   7. 疑难解答
   8. 其他资源

读者

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

本概念性文档并不完整详尽；其旨在使您可以快速开始使用 Google 地图 API 探索和开发很酷的应用程序。我们还发布了 Google 地图 API 参考，该文档相对完整。

我们最近重新组织了本文档，添加了更多概念性的信息，并将讨论内容划分为以下主要领域：

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

希望重新设计的文档更易于阅读，尤其是对 Google 地图 API 比较陌生的开发人员。同时欢迎对本文档提出反馈。确保加入 Google 地图 API 开发人员论坛提供反馈并讨论该 API。
创建 Google Mapplet

Google 地图 API 现在增加了对 Mapplet（地图和小工具的结合）的支持，使您可以在 Google 地图中嵌入外部托管的应用程序。这些 Mapplet 在自己的 iFrame 中运行，使您可以创建“嵌套的混搭”，例如可以混合使用两个网站的代码。这将在 Google 地图中创建一个全新的编码世界！编写 Mapplet 很容易，尽管有些操作与在标准 Google 地图 API 中的操作不同。有关详细信息，请参阅 Google 地图 Mapplet 文档和参考。
使用 Google AJAX API 加载程序

Google 地图 API 现在已与 Google AJAX API 完全集成。此框架使您可以为所有受支持的 Google AJAX API（包括 Google 地图）加载一个 API 密钥，还可以为每个 API 提供一个公共的命名空间，从而允许不同的 Google API 共同运行。请不必担心，如果决定不使用 Google AJAX API 框架，仍可继续使用现有命名空间。

使用 Google AJAX API 框架相对简单。将应用程序更改为使用该框架包括以下步骤：

    * 从 http://www.google.cn/jsapi 加载通用加载程序，而不是从 http://ditu.google.cn/apis 加载 API。可以将现有 Google 地图 API 密钥传递到下面的网址：

      <script type="text/javascript" src="http://www.google.cn/jsapi?key=ABCDEFG"></script>

    * 使用 google.load 方法加载所需的特定 API。google.load 方法以要加载的特定 API 和版本号为参数：

      <script type="text/javascript">
        google.load("maps", "2", {"base_domain": "ditu.google.cn"});
      </script>

    * 对 Google 地图 API 中当前使用的所有类、方法和属性使用 google.maps.* 命名空间，以使用此命名空间替换 G 前缀。使用 google.setOnLoadCallback() 初始化您的对象。例如，使用 Google AJAX API 加载程序时，GMap2 对象将被映射到 google.maps.Map2：

      <script type="text/javascript" src="http://www.google.cn/jsapi?key=ABCDEFG"></script>
      <script type="text/javascript">
        google.load("maps", "2.x", {base_domain: "ditu.google.cn", language: "zh-CN"});
        
        // Call this function when the page has been loaded
        function initialize() {
          var map = new google.maps.Map2(document.getElementById("map"));
          map.setCenter(new google.maps.LatLng(39.9493, 116.3975), 13);
        }
        google.setOnLoadCallback(initialize);
      </script>

有关使用 Google AJAX API 加载程序的完整文档，请访问 http://code.google.com/intl/zh-CN/apis/ajax/documentation/。
Google 地图 API 的本地化

在显示控件名称、版权声明和行车路线之类的文本信息时，Google 地图 API 会使用浏览器的偏好语言设置。如果您希望 Google 地图 API 忽略浏览器的语言设置，并强制其以特定语言显示信息，您可以在加入 Google 地图 API javascript 代码时，将可选 hl 参数添加到 <script> 标签，从而指定使用的语言。

例如，要以德文显示 Google 地图 API 应用程序，请将 &hl=de 添加到 <script> 标签，如下所示：

<script type="text/javascript" src="http://ditu.google.cn/maps?file=api&v=2&key=abcdefg&hl=de"

另请参阅支持的区域语言列表。请注意，我们会经常更新支持的语言，因此该列表可能并不详尽。
指定传感器参数

现在使用 Google 地图 API 会要求您指明您的应用程序是否正在使用传感器（如 GPS 定位器）确定用户的位置。这对移动设备尤为重要。在加入 Google 地图 API Javascript 代码时，应用程序必须向 sensor 标签传递一个必需的 <script> 参数，以指明您的应用程序是否正使用传感器设备。

当通过 http://ditu.google.cn/maps 或使用通用加载程序加载 Google 地图 API JavaScript 时，通过传感器确定用户位置的应用程序必须传递 &sensor=true。

#
# Example using sensor when loading the Maps JavaScript API
#
<script type="text/javascript" src="http://ditu.google.cn/maps?file=api&v=2&key=abcdefg&sensor=true"></script>
#
# Example using sensor when loading the Maps API via the common loader
#
<script type="text/javascript" src="http://www.google.cn/jsapi?key=abcdef"></script>
<script type="text/javascript">
  google.load("maps", "2",{"other_params":"sensor=true"});

  function initialize() {
    var map = new google.maps.Map2(document.getElementById("map"));
    map.setCenter(new google.maps.LatLng(39.9493, 116.3975), 13);
  }
  google.setOnLoadCallback(initialize);
</script>

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

开始研究 Google 地图 API 之前，应注意以下问题，以确保应用程序可以在目标平台上顺利运行。
浏览器兼容性

Google 地图 API 支持与 Google 地图网站相同的浏览器。脚本 http://ditu.google.cn/maps?file=api&v=2 几乎可以在所有浏览器中正确解析，因此检查兼容性之前可以安全地包含该脚本。

有时，不同的应用程序对使用互不兼容的浏览器的用户需要执行不同的操作。Google 地图 API 提供了一个全局方法 (GBrowserIsCompatible()) 来检查兼容性，但它检测到不兼容的浏览器时不会采取任何自动行为。本文档中的多数示例不检查浏览器兼容性，对早期版本的浏览器也不显示错误消息。很明显，真正的应用程序应该针对不兼容的浏览器设计更友好的行为，但我们忽略了此类检查以提高这些示例的可读性。

特殊应用程序将不可避免遇到浏览器和平台之间不一致的情况。这些问题没有简单的解决方法，但 Google 地图 API 开发人员论坛和 quirksmode.org 都是寻找解决方案的好资源。
XHTML 和 VML

我们建议在包含地图的页面上使用符合标准的 XHTML。当浏览器在页面顶部看到 XHTML DOCTYPE 时，它们会以“符合标准的模式”渲染页面，使其布局和行为在不同的浏览器中的可预测性更强。没有该定义的页面可能会以“Quirk 模式”渲染，这可能会导致不一致的布局。

如果要在地图上显示折线（类似于 Google 地图用于显示行车路线的线），您需要在 XHTML 文档中使用 VML 命名空间才能使所有内容在 Internet Explorer 中正常运行。XHTML 文档的开头应如下所示：

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">

API 更新

http://ditu.google.cn/maps?file=api&v=2 网址中的 v 参数表示 Google 地图 API 使用的版本号。使用此 API 的多数用户可能想通过在该网址中传递 v=2 参数来使用当前“第 2 版”的 API。也可以通过传递 v=2.x 获取最新版本（包含最新功能）。但是，请注意，最新版本可能不如 v=2 版本稳定。我们会经常更新 Google 地图 API（有时每周更新一次），因此当前 v=2.x 版本中的功能会移植到 v=2 版本（除非发现问题）。

此外，还可以通过传递 v=2.s 参数使用 API 的“稳定”版本。此版本更新频率较低，大约每几个月更新一次。由于 v=2 和 v=2.x 版本大约每两周更新一次，一些开发人员更喜欢使用稳定的 v=2.s。请注意，稳定版本可能比当前版本落后几个版本，因此也许不包含一些最新功能。

更新 API 时，它的每个版本都会注明（例如“第 2.76 版”）。当我们更新 API 时，基于先前版本的较旧代码可能偶尔会和声明的行为方式不同。如果一定需要将应用程序绑定在特定的 API 版本上，则可以通过在 v 参数（例如 v=2.75）中显式地包含该版本以实现此目的。但是不建议这么做。将您的产品基于最新代码始终是最佳选择。

将来对 API 进行重大更新时，我们将更改主版本号，并在 Google 代码和 Google 地图 API 开发人员论坛上发布声明。当发生这种情况时，我们预期同时支持这两个版本至少一个月，以使您可以移植代码。

地图团队还使用最新的错误修正程序和性能改进透明地更新 API。这些错误修正程序只应提高性能并修正错误，但是我们可能会无意中破坏某些 API 客户端。请使用 Google 地图 API 开发人员论坛报告此类问题。
升级第 1 版应用程序

本文档参考的是 2006 年 4 月 3 日发布的 Google 地图 API 的第 2 版。如果您的 API 使用 Google 地图 API 的第 1 版（即您的站点于 2006 年 4 月 3 日之前开发），则应尝试升级您的网站。有关详细信息，请参阅第 2 版升级指南。
Google 地图 API 中的示例

请注意，本文档中的多数示例仅显示相关 JavaScript 代码，而不显示完整的 HTML 文件。可以将 JavaScript 代码插入自己的结构 HTML 文件，也可以通过点击示例后的链接下载每个示例的完整 HTML 文件。
减少浏览器内存泄漏

Google 地图 API 建议使用函数闭包，API 事件处理系统 GEvent 将事件附加到 DOM 节点的方式几乎肯定会导致一些浏览器（尤其是 Internet Explorer）泄漏内存。Google 地图 API 的第 2 版引入了一种新方法 GUnload()，该方法将删除导致这些泄漏的多数循环引用。您应在页面的 onunload 事件中调用 GUnload()，以降低应用程序泄漏内存的可能性：

<body onunload="GUnload()">

使用此函数可以在 Google 地图中完全消除 Internet Explorer 内存泄漏，但是如果观察到内存消耗问题，则应使用诸如 Drip 等工具在您自己的站点上测试内存泄漏。
其他资源

下面是一些附加资源。请注意，这些站点不是 Google 拥有或支持的站点。

    * Google Mapki：Mapki
    * Google 地图 API 教程：http://econym.googlepages.com/index.htm
    * Esa 的 Google 地图 API 示例：http://koti.mbnet.fi/ojalesa/exam/index.html
    * USNaviguide 的 Google 地图 API 示例：http://maps.huge.info/examples.htm
    * Mark McClure 的编码折线示例：http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/
    * Marcelo 的 Google 地图 API 实验：http://maps.forum.nu/
    * Bill Chadwick 的 Google 地图 API 演示：http://www.bdcc.co.uk/Gmaps/BdccGmapBits.htm

疑难解答

如果您的代码不起作用，则下面一些途径可能会帮助您解决问题：

    * 请确保您的 API 密钥有效。
    * 查找错别字。请记住 JavaScript 语言区分大小写。
    * 使用 JavaScript 调试器。在 Firefox 中，可以使用 JavaScript 控制台、Venkman Debugger 或 Firebug 插件。在 IE 中，您可以使用 Microsoft 脚本调试器。该系列视频演示了怎样使用各种调试工具。
    * 搜索 Google 地图 API 开发人员论坛。如果找不到可以解答您问题的帖子，请将您的问题连同演示该问题的网页链接一起发布到该网上论坛。
    * 有关第三方开发人员资源，请参阅其他资源。