jQuery.getJSON()


jQuery.getJSON( url [, data ] [, success ] )Возвращает: jqXHR

Описание: Загружает JSON данные с сервера при помощи GET HTTP запроса.

  • version added: 1.0jQuery.getJSON( url [, data ] [, success ] )

    • url
      Тип: String
      Строка с URL адресом на который будет отправлен запрос.
    • data
      Тип: PlainObject или String
      Объект или строка, которые будут отправлены на сервер вместе с запросом.
    • success
      Тип: Function( PlainObject data, String textStatus, jqXHR jqXHR )
      Функция обратного вызова, которая выполняется если запрос успешно завершается.

Это сокращенная Ajax функция, которая эквивалентна следующему коду:

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

Данные отправляемые на сервере передаются в URL строке как GET параметры. Если значением параметра data является объект (не строка), то он конвертируется в строку (с предварительным url-encode кодированием значений) перед добвлением к URL адресу.

В большинстве случаев, обработчик success указывается:

1
2
3
4
5
6
7
8
9
10
11
$.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(). Также передается текстовый статус ответа.

Начиная с jQuery 1.5, функция success принимает объект "jqXHR" objectjQuery 1.4, она принимает объект XMLHttpRequest). Однако, так как JSONP и кросс-доменные запросы не используют XHR, то в этом случае параметры jqXHR и textStatus не будут переданы в функцию success.

Важно: начиная с jQuery 1.4, если JSON файл содержит синтаксические ошибки, для запроса просто вызовется обработчик ошибки (если он установлен). По этой причине, избегайте руного редактирования JSON данных. JSON представляет из себя формат обмена данных с правилами синтаксиса более жесткими чем правила определения для JavaScript объектов. Например, все строки представленные в JSON, являются ли они свойством или значением, должны быть заключены в двойные кавычки. Уточните информацию о формате JSON по ссылке http://json.org/.

JSONP

Если в URL адрес включена строка "callback=?" (или подобные, как это определяет серверное API), запрос обрабатывается как JSONP. Это более подробно описано на странице $.ajax() в описании параметра jsonp.

The jqXHR Object

Начиная с jQuery 1.5, все Ajax методы jQuery возвращают объект XMLHTTPRequest. Объект jQuery XHR или "jqXHR," возвращается $.get() реализацией интерфейса Promise и предоставляет все его свойства, меоды и повередени Promise в целом (смотрите Deferred object для справки). Методы jqXHR.done() (успех), jqXHR.fail() (ошибка), and jqXHR.always() (для гарантированного обработчика, не зависимо от успеха или ошибки ответа, добавлен в версии jQuery 1.6) принимают функцию, которая вызывается когда запрос завершается. Аргументы этих функция описаны на странице jqXHR Object в разделе $.ajax() справки.

Интерфейс Promise также разрешает Ajax методам, включая $.get(), вызывать неоднократно по цепочке методы .done(), .fail() и .always() для одного запроса и даже назначать его обработчики, даже после того как запрос был завершен. Если запрос уже выполнен, то функция обратного вызова выполняется немедленно.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.getJSON( "example.json", function() {
console.log( "success" );
})
.done(function() {
console.log( "second success" );
})
.fail(function() {
console.log( "error" );
})
.always(function() {
console.log( "complete" );
});
// Perform other work here ...
// Set another completion function for the request above
jqxhr.complete(function() {
console.log( "second complete" );
});

Уведомление об устаревании

Функции обратного вызова jqXHR.success(), jqXHR.error(), and jqXHR.complete() удалены в jQuery 3.0. Используйте методы jqXHR.done(), jqXHR.fail() и jqXHR.always() вместо них.

Дополнительные примечания:

  • Из-за ограничений безопасности браузера большинство "Ajax" запросов подпадают под действие политики того же происхождения, запросы не могут быть выполнены к другим доменам, поддоменам, порту или протоколу.
  • Запросы скриптов и JSONP запросы не подвергаются ограничениям политики того же происхождения (Same Origin Policy).

Примеры:

Загружает четыре последних фото Маунт-Рейнир при помощи 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
27
28
29
30
31
32
33
34
35
36
37
38
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.getJSON demo</title>
<style>
img {
height: 100px;
float: left;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="images"></div>
<script>
(function() {
var flickerAPI = "http://api.flickr.com/services/feeds/photos_public.gne?jsoncallback=?";
$.getJSON( flickerAPI, {
tags: "mount rainier",
tagmode: "any",
format: "json"
})
.done(function( data ) {
$.each( data.items, function( i, item ) {
$( "<img>" ).attr( "src", item.media.m ).appendTo( "#images" );
if ( i === 3 ) {
return false;
}
});
});
})();
</script>
</body>
</html>

Демонстрация:

Загружает JSON данные из test.js и получает доступ к полю name в полуенных JSON данных.

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

Загружает JSON данные из test.js, передает на сервер дополнительные данные и получает доступ к полю name в полученных JSON данных. Если произошла ошибка, то вместо описанного раннее, просто показываем сообщение об ошибке.

1
2
3
4
5
6
7
8
$.getJSON( "test.js", { name: "John", time: "2pm" } )
.done(function( json ) {
console.log( "JSON Data: " + json.users[ 3 ].name );
})
.fail(function( jqxhr, textStatus, error ) {
var err = textStatus + ", " + error;
console.log( "Request Failed: " + err );
});