返回值:jqXHRjQuery.getJSON(url, [data], [success(data, textStatus, jqXHR)])
通过 HTTP GET 方式从服务器载入 JSON 编码的数据。
-
1.0 新增jQuery.getJSON(url, [data], [success(data, textStatus, jqXHR)])
url (String) 将要被请求的 URL 字符串。data (Map) 可选参数,发送给服务器的字符串或者映射。success(data, textStatus, jqXHR) (Function) 可选参数,当请求成功后执行的回调函数。
这是一个 Ajax 函数的简写形式,它等价于:
$.ajax({
url: url,
dataType: 'json',
data: data,
success: callback
});
数据会被添加到 URL 中,以 URL 查询字符串的形式发送给服务器。如果 data 参数的值是一个对象(映射),它会自动被转换成 URL 编码的字符串后再被添加到 URL 中。
大多数情况下都会指定一个请求成功后的回调函数:
$.getJSON('ajax/test.json', function(data) {
var items = [];
$.each(data, function(key, val) {
items.push('<li id="' + key + '">' + val + '</li>');
});
$('<ul/>', {
'class': 'my-new-list',
html: items.join('')
}).appendTo('body');
});
当然,这个例子需要依赖下面的 JSON 文件结构:
{
"one": "Singular sensation",
"two": "Beady little eyes",
"three": "Little birds pitch by my doorstep"
}
使用这种结构,在上面的例中,循环读取返回结果时就创建了一个无序的列表,并将它追加到 body 中。
success 回调函数中传入了返回的数据,通常是 JavaScript 对象或是 JSON 格式的数组,使用
$.parseJSON()
方法进行解析。同时 success 回调函数中还传入了描述返回状态的文本。
从 jQuery 1.5 开始, success 回调函数还会传入一个 "jqXHR" 对象 (在 jQuery 1.4 中, success 回调函数传入一个 XMLHttpRequest 对象)。但是,由于 JSONP 和跨域的 GET 请求不使用 XHR,所以,在这种情况下,传入到 success 回调函数中的 (j)XHR 和 textStatus 参数是 undefine。
重要提示: 从 jQuery 1.4 起,如果 JSON 文件包含语法错误,这个请求会失败而不会返回任何提示信息。因此,请尽量避免频繁地手动编辑 JSON 数据。JSON 是一个数据交换格式,所以它的语法规则比普通的 JavaScript 对象字面量表示法还要严格。比如 JSON 中的所有字符串都必须用双引号包裹,不管它是属性还是值。更多信息请参考:http://json.org/。
JSONP
如果 URL 中包含字符串 "callback=?" (或者其它类似的参数,取决于服务器端 API 是如何定义的),这个请求就会被看做 JSONP 请求。更多关于 jsonp 数据类型的探讨,请参考 $.ajax()。
jqXHR 对象
从 jQuery 1.5 开始,所有 jQuery 的 Ajax 方法都返回一个 XMLHTTPRequest 对象的超集。由 $.getJSON() 方法返回的 jQuery XHR 对象(也可叫做 "jqXHR") 实现了 Promise 接口,使它拥有 Promise 的所有属性,方法和行为。(详见 延迟对象 来获得更多信息)。为了让回调函数的名字统一,便于在
$.ajax()
里使用, jQuery XHR 对象(也可叫做 "jqXHR")同样也提供了 .error(), .success() 和 .complete() 方法。这些方法都带有一个参数,该参数是一个函数,此函数在 $.ajax() 请求结束时被调用,并且这个函数接收的参数,与调用 $.ajax() 函数时的参数是一致。
Promise 接口在 jQuery 1.5 里,允许在 $.getJSON() 方法后直接注册 .success(), .complete() 和 .error() 回调函数,甚至允许你在请求已经结束后,注册回调函数。如果该请求已经完成,则回调函数会被立刻调用。
// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.getJSON("example.json", function() {
alert("success");
})
.success(function() { alert("second success"); })
.error(function() { alert("error"); })
.complete(function() { alert("complete"); });
// perform other work here ...
// Set another completion function for the request above
jqxhr.complete(function(){ alert("second complete"); });
补充说明:
- 由于浏览器的安全限制,大多数 "Ajax" 请求都服从 同源策略(same origin policy)。即无法从不同的域,子域或协议中正确接收数据。
- Script 和 JSONP 请求没有同源策略(same origin policy)的限制。
示例:
用 Flickr 的 JSONP API 载入最近的四张关于猫的图片。
<!DOCTYPE html>
<html>
<head>
<style>img{ height: 100px; float: left; }</style>
<script src="jquery.min.js"></script>
</head>
<body>
<div id="images">
</div>
<script>
$.getJSON("http://api.flickr.com/services/feeds/photos_public.gne?jsoncallback=?",
{
tags: "mount rainier",
tagmode: "any",
format: "json"
},
function(data) {
$.each(data.items, function(i,item){
$("<img/>").attr("src", item.media.m).appendTo("#images");
if ( i == 3 ) return false;
});
});
</script>
</body>
</html>演示:
示例:
从 test.js 中载入 JSON 数据,并且从返回的 JSON 数据中获得 name 的值。
jQuery 代码:
$.getJSON("test.js", function(json) {
alert("JSON Data: " + json.users[3].name);
});示例:
从 test.js 中载入 JSON 数据,传递一个附加的数据,并且从返回的 JSON 数据中获得 name 的值。
jQuery 代码:
$.getJSON("test.js", { name: "John", time: "2pm" }, function(json) {
alert("JSON Data: " + json.users[3].name);
});