Урок - jQuery.getJSON()

Группа вКонтакте
Лицензия: Лицензия Creative Commons.

Метод jQuery.getJSON() загружает JSON-данные с сервера используя GET HTTP-запрос.

Синтаксиси метода jQuery.getJSON()

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

 где

  • url - строка, содержит URL запроса, для отправки данных.
  • data - строка или Plain-объект (ассоциативный массив), данных для отправки на сервер.
  • success(data, textStatus, jqXHR) - функция обратного вызова, вызывается если запрос успешен.

Пример ниже, эквивалент jQuery.getJSON() в исполнении jQuery.ajax():

$.ajax({
    dataType: "json",
    url: url,
    data: data,
    success: success
});

Данные, которые отправляются на сервер добавляются в URL, в виде строки запроса. Если значения параметра data указаны в виде простого объекта (ассоциативный массив), то данные преобразуются в строку и кодируются прежде чем будут добавлены к URL.

В большинстве реализаций обработчик success, указывается следующим образом:

$.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"
}

Используя эту структуру, в цикле создается ненумерованный список, который добавляется в тело страницы.

В функцию обратного вызова success передаются возвращаемые данные, которые, как правило, являются JavaScript-объектом в соответствии с переданной JSON-структурой, которая анализируется с помощью jQuery.parseJSON(). Также передается текст статуса ответа.

Начиная с версии jQuery 1.5 в функцию success передается jqXHR-объект. Однако в случае JSONP и кросс-доменных запросах параметры jqXHR и textStatus при передаче в success не определены.

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

JSONP

Если URL содержит строку "callback=" (или аналогичный, как это определено в серверных API), запрос обрабатывается как JSONP вместо этого. См. обсуждение типов данных JSON и JSONP в jQuery.ajax() для более подробной информацией.

jqXHR-объект.

С версии jQuery 1.5 все AJAX-методы возвращают расширенный объект XMLHttpRequest. Это XHR-объект jQuery или коротко jqXHR, возвращается jQuery.getJSON() реализуя Promise-интерфейс, предоставляя ему все свойства, методы и поведение Promise (смотрите Отложенный объект, для получения дополнительной информации). jqXHR.done() (вместо success), jqXHR.fail() (вместо error) и jqXHR.always() (вместо complete) принимают аргумент функции, которая вызывается, когда запрос завершается. Для получения информации об аргументах этой функции обратитесь в раздел документации jQuery.ajax().

Promise-интерфейс также позволяет AJAX-методам в jQuery, в том числе и JQuery.getJSON(), создать цепочку из jqXHR.done(), jqXHR.fail(), jqXHR.always(), т.е. из нескольких методов обратного вызова на один запрос, и даже назначить эти функции, после того как запрос был завершен. Если запрос уже завершен, назначенные вновь методы будут выполнены сразу же.

// Назначаем запросы сразу же после запроса
// и сохраняем jqXHR-объект этого запроса.
var jqxhr = $.getJSON("example.json", function() {
    console.log("success");
})
.done(function() { console.log("second success"); })
.fail(function() { console.log("error"); })
.always(function() { console.log("finished"); });

// выполняем какой-то код здесь ...

// Добавляем новый обработчик завершения запроса, для уже завершенного запроса
jqxhr.always(function(){console.log("second finished");});

Устаревшие обработчики.

Методы jqXHR.success(), jqXHR.error(), jqXHR.complete() являются устаревшими с версии jQuery 1.8. В будущем эти методы будут удалены. Используйте вместо них jqXHR.done(), jqXHR.fail(), jqXHR.always(), соответственно.

Дополнительное примечание.

  • Из-за ограничений безопасности браузеров, большинство AJAX-запросов ограничены той же политикой безопасности. AJAX-запросы не могут успешно извлекать информацию из других доменов, поддоменов или протоколов.
  • На тип данных Script и JSONP не распространяются те же ограничения безопасности.

Примеры:

Пример: Загружаем 4 изображения с тегом "Mount Rainier" используя Flickr JSONP API.

<!DOCTYPE html>
<html>
    <head>
        <style>img{ height: 100px; float: left; }</style>
        <script src="http://code.jquery.com/jquery-1.9.1.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 и отображаем частичную информацию из полученных JSON-данных.

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

Пример: Загружаем JSON-данные из файла test.js, отображаем частичную информацию из полученных JSON-данных. При возникновении ошибки, отображаем сообщение в log.

$.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);
});