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

通过 HTTP GET 方式从服务器载入 JSON 编码的数据。

这是一个 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)XHRtextStatus 参数是 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);
    });