返回值: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);
});