jQuery.getJSON()


jQuery.getJSON( url [, data ] [, success(data, textStatus, jqXHR) ] )返回: jqXHR

描述: 使用一个HTTP GET请求从服务器加载JSON编码的数据。

  • 添加的版本: 1.0jQuery.getJSON( url [, data ] [, success(data, textStatus, jqXHR) ] )

    • url
      类型: String
      一个包含发送请求的URL字符串
    • data
      类型: PlainObject
      发送给服务器的字符串或Key/value键值对。
    • success(data, textStatus, jqXHR)
      类型: Function()
      当请求成功后执行的回调函数。

这是一个Ajax函数的缩写,这相当于:

1
2
3
4
5
6
$.ajax({
dataType: "json",
url: url,
data: data,
success: success
});

数据会被附加到一个查询字符串的URL中,发送到服务器。如果该值的data参数是一个普通的对象,它会转换为一个字符串并使用URL编码,然后才追加到URL中。

大多数情况下都会指定一个请求成功后的回调函数:

1
2
3
4
5
6
7
8
9
10
11
12
$.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文件的结构:

1
2
3
4
5
{
"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中 ,它收到的是XMLHttpRequest对象)。然而,由于JSONP形式和跨域的GET请求不使用XHR,在这些情况下, jqXHRtextStatus参数传递给success(成功)回调是 undefined 。

重要提示: 从jQuery 1.4开始,如果JSON文件包含一个语法错误,该请求通常会静静的失败。因此应该避免频繁手工编辑JSON数据。JSON语法规则比JavaScript对象字面量表示法更加严格。例如,所有在JSON中的字符串,无论是属性或值,必须用双引号括起来,更多JSON细节信息请参阅http://json.org/

JSONP

如果URL包含字符串“callback=?”(或类似的参数,取决于服务器端 API 是如何定义的),这个请求被视为JSONP形式请求。更多jsonp数据类型的细节讨论,请参阅$.ajax()

The jqXHR Object(jqXHR 对象)

愚人码头注:估计是jQuery官方没有及时的更新这条api,和jQuery.get() api中的jqXHR 对象描述上有差别。

从jQuery 1.5开始,所有jQuery的Ajax方法都返回一个XMLHTTPRequest对象的超集。这个通过$.get()方法返回的jQuery XHR对象,或“jqXHR,”实现了 Promise 接口,使它拥有 Promise 的所有属性,方法和行为(见Deferred object获取更多信息)。 为了便于在 $.ajax()里使用,jQuery XHR 对象$.ajax()同样也提供了.error() .success().complete()方法。这些方法接受一个函数参数,用来请求终止时被调用。这个函数接收与$.ajax()回调函数名中相同的参数。

Promise 接口也允许jQuery的Ajax方法, 包括 $.getJSON(), 在一个单独的请求中关联到 .success(), .complete(), 和 .error() 回调函数, 甚至允许你在请求已经结束后,指派回调函数。如果该请求已经完成,则回调函数会被立刻调用。

1
2
3
4
5
6
7
8
9
10
11
12
13
// 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"); });

Deprecation Notice(弃用通知)

jQuery 1.5中引进的 jqXHR.success(),jqXHR.error(),jqXHR.complete()回调方法在jQuery 1.8中废弃。你的代码因做好准备,他们最终将被移除,使用jqXHR.done(), jqXHR.fail(), 和 jqXHR.always()代替。

Additional Notes:(其他注意事项:)

  • 由于浏览器的安全限制,大多数“Ajax”的要求,均采用同一起源的政策 ;即无法从不同的域,子域或协议中正确接收数据。
  • Script和JSONP形式请求不受同源策略的限制。

例子:

Example: 从 Flickr JSONP API中加载最近的四张标签为猫的图片:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<!DOCTYPE html>
<html>
<head>
<style>img{ height: 100px; float: left; }</style>
<script src="http://code.jquery.com/jquery-latest.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>

Demo:

Example: 通过test.js加载这个JSON数据,并使用返回的JSON数据中的 name值:

1
2
3
$.getJSON("test.js", function(json) {
alert("JSON Data: " + json.users[3].name);
});

Example: 通过额外的Key/value参数从test.js加载这个JSON数据,并使用返回的JSON数据中的 name值:.

1
2
3
$.getJSON("test.js", { name: "John", time: "2pm" }, function(json) {
alert("JSON Data: " + json.users[3].name);
});