Google AJAX API

Google AJAX API
- 开发人员指南
- 代码园地^新增！

开发人员指南

使用 Google AJAX API

使用入门

Google 具有许多可以在不使用服务器端代码的情况下在网页中使用的 Google AJAX API，包括 Google 地图 API、Google AJAX 搜索 API 和 Google AJAX 供稿 API。要在网页中使用任意或所有 API，您只需在网页顶部添加一个 <script> 标签以及您的 Google API 密钥：

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

如果您还没有 Google API 密钥，则可以免费注册一个 API 密钥。

载入 Google AJAX API 脚本后，您便可以使用 google.load 指定要在网页上使用的模块：

<script type="text/javascript">
  google.load("maps", "2");
  google.load("search", "1");
</script>

上述实例将载入 2 版的地图 API 和 1 版的 AJAX 搜索 API。调用 google.load 后，可以在网页中使用所有已载入的模块。此外，可以使用 google.setOnLoadCallback 来记录文档载入后要被调用的指定处理程序函数。此处是包含所有代码的实例：

<html>
  <head>
    <script type="text/javascript"
src="http://www.google.com/jsapi?key=ABCDEFG"></script>
    <script type="text/javascript">
      google.load("maps", "2");
      google.load("search", "1");

      // 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(37.4419, -122.1419), 13);

        var searchControl = new google.search.SearchControl();
        searchControl.addSearcher(new google.search.WebSearch());
        searchControl.addSearcher(new google.search.NewsSearch());
        searchControl.draw(document.getElementById("searchcontrol"));
      }
      google.setOnLoadCallback(initialize);
    </script>

  </head>
  <body>
    <div id="map" style="width: 200px; height: 200px"></div>
    <div id="searchcontrol"></div>
  </body>

</html>

当载入文档时，google.setOnLoadCallback 被用作 window.onload 的帮助程序，这种情况只发生一次。因此，对于 API 的动态载入（例如进行了用户交互后），应当使用带有回调选项的 google.load（如下所示）。

详细文档

`google.load`

Google AJAX API <script> 标签将载入单个方法 google.load，该方法可以载入各个 AJAX API。其原型如下所示：

google.load(moduleName, moduleVersion, optionalSettings)

moduleName 是 API 的名称（例如"maps"或"search"）。该模块名称也被用作 API 被载入后的名称空间。

version 可指定 API 模块的版本，如下所述。其是一个必选参数；必须始终指定要使用的 API 的版本。如果您不确定要使用哪个版本，则应使用您要使用的 API 的文档和实例中所用的版本。

optionalSettings 可为您作为 JavaScript 对象常量载入的 API 指定所有可选配置选项。例如，您可以使用以下代码指定日语的地图 API 用户界面：

google.load("maps", "2", {"language" : "ja_JP"});

您也可以指定不为要载入的 API 载入默认 CSS，如下所示：

google.load("feeds", "1", {"nocss" : true});

以下是一些可能的选项：

callback：载入脚本后要调用的函数。
language：本地化 API 或 API 的 UI 控件所使用的语言。语言代码指定为 ISO639。
nocss：用于告知 API 是否载入通常与其控件相关联的样式表的布尔值。如果开发人员已完全覆盖了所有已载入的 CSS 并且想避免不必要的载入，则可将此项设置为 true。
packages：用于指定核心 API 附带的可读取相关包的字符串数组。例如，您可以随可视化 API 一起载入“饼状图”和“表格”。
base_domain：用于从中载入 API 的基本域。例如，您可以使用“地图”模块从“ditu.google.cn”中进行载入以获取中文版的 Google 地图 API。
other_params：这是包含通常只受特定 API 支持（并且通常只特定于该 API）的选项的对象。如果您通常是通过 API 的脚本标签来提交某个参数，那么，您可以改为将其提交到 other_params 中。

有关每个 API 都分别支持哪些选项的信息，请参见以下小节。

API 名称空间

API 的模块名称也是其名称空间。因此，当载入 "maps" 模块时，该模块中的符号在名称空间 google.maps 下可用。现有的 Google AJAX API（如地图 API）为所有输出的类和常量使用一个 G 前缀。由于使用此新的命名约定，类名称将不再具有 G 前缀，例如 GMap2 变为 google.maps.Map2。

当前使用 G 前缀的 API 将继续支持新旧两种命名约定。以后的 API 将仅能使用 google.moduleName 名称空间。

API 版本管理

google.load 的第二个参数是 API 的版本，仿效 Google 地图 API 最初使用的版本管理系统。每个 AJAX API 均有一个主版本和版本号，形式为 VERSION.REVISION。AJAX API 每次引入新的 JavaScript 时，版本号便会增加。因此，如果 Google AJAX 搜索 API 为 2.23 版，并且团队进行了一次更新，则新的 JavaScript 将为 2.24 版。

我们的 AJAX API 会经常更新，因此为了确保稳定性，所有 AJAX API 都有一个激活的稳定版和测试版。团队每次引入一个新的 API 版本（例如 2.24）时，先前版本 2.23 将变为该 API 的稳定版。2.24 版是测试版。如果需要 2 版的 API 但没有指定版本，您将自动获得稳定版 (2.23) 的 API。要获得该 API 的测试版，可以明确请求 2.24 版，也可以使用特殊通配符 2.x（其始终表示该 API 的测试版）。2.24 版将一直作为测试版，直到下一次版本推送为止。

我们建议的使用模型为：

在产品 HTML 中使用所有 API 的稳定版（例如 2）。
在开发计算机上使用所有 API 的测试版（例如 2.x），并且在开发人员论坛中报告使用该 API 时遇到的所有问题。如果许多用户在使用某一 API 版本时都遇到了严重的问题，Google 将恢复至先前版本或不再提供该版本。

虽然您可以随时专业请求某个 API 的任何早期版本，但是对于早期版本的 API，官方不再提供支持。在多数情况下，服务器端的更改将要求您停止使用早期版本的 API。但是，我们会设法在服务器上将所有 API 的早期版本长期保留，以便依赖旧版本 API 的开发人员有充足的时间进行升级。

动态载入新增！

您的网站上可以动态包括 AJAX API 载入程序。如果您不需要在页面载入时可用的 API，这将很有用，例如当用户执行搜索和某些其他操作时。

可通过在第三个参数中传递 callback 选项来实现此目的，如下所示：

function mapsLoaded() {
  var map = new google.maps.Map2(document.getElementById("map"));
  map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}

function loadMaps() {
  google.load("maps", "2", {"callback" : mapsLoaded});
}

当您调用 loadMaps() 时，它将在该 API 准备就绪时载入地图 API 并执行 mapsLoaded 回调。当使用 callback 选项调用 google.load 时，请确保 DOM 准备就绪，因为它将尝试向该 DOM 附加一个元素。用于载入地图 API 的后续调用将立即执行提供的回调，因此您无需担心多次载入同一 API。

可以通过创建一个 script 元素并使用附加查询 callback 参数将其源设置为相同的 "http://www.google.com/jsapi?..." 网址，来动态载入 Google AJAX API 载入程序。当载入程序准备就绪时，将执行回调。请参考以下代码段：

function mapsLoaded() {
  var map = new google.maps.Map2(document.getElementById("map"));
  map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}

function loadMaps() {
  google.load("maps", "2", {"callback" : mapsLoaded});
}

function initLoader() {
  var script = document.createElement("script");
  script.src = "http://www.google.com/jsapi?key=ABCDEFG&callback=loadMaps";
  script.type = "text/javascript";
  document.getElementsByTagName("head")[0].appendChild(script);
}

google.loader.ClientLocation新增！

当应用程序使用 Google AJAX API 载入程序时，该载入程序会尝试根据客户端的 IP 地址来地理定位该客户端。如果此定位过程成功，那么将能够在 google.loader.ClientLocation 属性中使用该客户端的位置（范围已限定到都市级别）。如果定位过程中未找到匹配的位置，那么此属性会被设置为空。

填充过程中，会将以下都市级别的最小单位属性填充到 google.loader.ClientLocation 对象中：

ClientLocation.latitude - 提供了与客户端的 IP 地址相关联的低分辨率纬度
ClientLocation.longitude - 提供了与客户端的 IP 地址相关联的低分辨率经度
ClientLocation.address.city - 提供了与客户端的 IP 地址相关联的城市名称
ClientLocation.address.country - 提供了与客户端的 IP 地址相关联的国家/地区名称
ClientLocation.address.country_code - 提供了与客户端的 IP 地址相关联的 ISO 3166-1 国家/地区代码名称
ClientLocation.address.region - 提供了与客户端的 IP 地址相关联的国家/地区的特定区域名称

使用此属性时，应用程序必须在某种程度上具有防御性。通过将 IP 地址与位置进行匹配来填充 google.loader.ClientLocation。不一定总是存在此类映射，因此，也会存在属性为 null 的情况。此外，当应用程序将地址属性用作其数据结构中的标记时，应用程序应当大范围地检查结果是否正确。

以下代码段展示了 API 的一种使用情况。

/**
 * Set the currentState_ and currentCountry_ properties based on the client's
 * current location (when available and in the US), or to the defaults.
 */
InTheNews.prototype.setDefaultLocation_ = function() {
  this.currentState_ = this.options_.startingState;
  if (google.loader.ClientLocation &&
      google.loader.ClientLocation.address.country_code == "US" &&
      google.loader.ClientLocation.address.region) {

    // geo locate was successful and user is in the United States. range
    // check the region so that we can safely use it when selecting a
    // state level polygon overlay
    var state = google.loader.ClientLocation.address.region.toUpperCase();
    if (InTheNews.stateNames[state]) {
      this.currentState_ = state;
    }
  }
  this.currentCountry_ = "US";
}

可用的 AJAX API

可用的 Google AJAX API 如下所示：

Google 地图 API: 名称：地图; 版本：2、2.x; 载入请求：google.load("maps", "2");; 支持的选项：callback, base_domain, language, other_params; 请注意：也可指定版本号介于 2.92 和最新版本 (2.x) 之间的版本。有关详细信息，请参见 Google 地图 API 文档和 API 修改日志。

Google AJAX 搜索 API: 名称：搜索; 版本：1; 载入请求：google.load("search", "1");; 支持的选项：callback, language, nocss

Google AJAX 供稿 API: 名称：供稿; 版本：1; 载入请求：google.load("feeds", "1");; 支持的选项：callback, language, nocss

Google AJAX 语言 API: 名称：语言; 版本：1; 载入请求：google.load("language", "1");; 支持的选项：callback, language, nocss

Google 数据 API: 名称：GData; 版本：1、1.x; 载入请求：google.load("gdata", "1");; 支持的选项：无

Google 地球 API: 名称：地球; 版本：1; 载入请求：google.load("earth", "1");; 支持的选项：无

Google 可视化 API: 名称：可视化; 版本：1; 载入请求：google.load("visualization", "1");; 支持的选项：packages


例如，“ajax api”或“开源”

Google AJAX API

Google AJAX API

开发人员指南

使用 Google AJAX API

目录

使用入门

详细文档

google.load

API 名称空间

API 版本管理

动态载入新增！

google.loader.ClientLocation新增！

可用的 AJAX API

`google.load`