使用 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
327
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
