google.load
google.loader.ClientLocation
新增!
Google 具有许多可以在不使用服务器端代码的情况下在网页中使用的 Google AJAX API,包括 Google 地图 API、Google AJAX 搜索 API 和 Google AJAX 供稿 API。要在网页中使用任意或所有 API,您只需在网页顶部添加一个 标签以及您的 Google API 密钥:
如果您还没有 Google API 密钥,则可以免费注册一个 API 密钥。
载入 Google AJAX API 脚本后,您便可以使用 google.load
指定要在网页上使用的模块:
上述实例将载入 2 版的地图 API 和 1 版的 AJAX 搜索 API。调用 google.load
后,可以在网页中使用所有已载入的模块。此外,可以使用 google.setOnLoadCallback
来记录文档载入后要被调用的指定处理程序函数。此处是包含所有代码的实例:
id="map" style="width: 200px; height: 200px">
id="searchcontrol">
当载入文档时,google.setOnLoadCallback
被用作 window.onload
的帮助程序,这种情况只发生一次。因此,对于 API 的动态载入(例如进行了用户交互后),应当使用带有回调选项的 google.load(如下所示)。
google.load
Google AJAX API 标签将载入单个方法
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 的模块名称也是其名称空间。因此,当载入 "maps"
模块时,该模块中的符号在名称空间 google.maps
下可用。现有的 Google AJAX API(如地图 API)为所有输出的类和常量使用一个 G 前缀。由于使用此新的命名约定,类名称将不再具有 G 前缀,例如 GMap2
变为 google.maps.Map2
。
当前使用 G 前缀的 API 将继续支持新旧两种命名约定。以后的 API 将仅能使用 google.moduleName
名称空间。
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 版将一直作为测试版,直到下一次版本推送为止。
我们建议的使用模型为:
虽然您可以随时专业请求某个 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 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";
}
可用的 Google AJAX API 如下所示:
google.load("maps", "2");
callback, base_domain, language, other_params
google.load("search", "1");
callback, language, nocss
google.load("feeds", "1");
callback, language, nocss
google.load("language", "1");
callback, language, nocss
google.load("gdata", "1");
google.load("earth", "1");
google.load("visualization", "1");
packages