Объект jqXHR

Функция $.ajax() и другие функции, рассмотренные в этом разделе, возвращают объект jqXHR (jQuery XHR), который имитирует объект XMLHttpRequest. Кроме того, объект jqXHR доступен через параметр в обработчиках событий.

Объект jqXHR содержит следующие свойства:

• status — содержит код возврата. Свойство доступно в обработчиках событий;
• statusText — содержит статус возврата в виде строки, например, "OK" для кода 200. Свойство доступно в обработчиках событий;
• responseText — ответ в виде текста. Свойство доступно в обработчиках событий;
• responseJSON — ответ в виде объекта JSON. Свойство доступно в обработчиках событий успешного получения ответа, если опция dataType имеет значение json;
• responseXML — ответ в виде XML-документа. Свойство доступно в обработчиках событий успешного получения ответа, если опция dataType имеет значение xml;
• readyState — содержит текущий статус обработки запроса. Может принимать следующие значения:

• 0 — объект запроса создан;
• 1 — запрос подготовлен;
• 2 — запрос отправлен и получены заголовки ответа сервера;
• 3 — ответ доступен, но загружен не полностью;
• 4 — ответ полностью загружен с сервера и доступен для обработки или что-то пошло не так.

Методы объекта jqXHR (полный список см. в документации):

• setRequestHeader(<Заголовок>, <Значение>) — позволяет добавить заголовок запроса (если заголовок существует, то старое значение заменяется новым). В качестве примера изменим значение заголовка User-Agent:

beforeSend: function(xhr, settings) {
   xhr.setRequestHeader('User-Agent', 'MyRobot');
}

• overrideMimeType(<MIME-тип>) — позволяет указать MIME-тип ответа, если сервер его не передал или передал неправильно:

beforeSend: function(xhr, settings) {
   xhr.overrideMimeType('text/xml');
}

• getAllResponseHeaders() — возвращает строку со всеми заголовками ответа сервера (кроме заголовка Set-Cookie) или пустую строку в случае ошибки:

success: function(json, status, xhr) {
   console.log( xhr.getAllResponseHeaders() );
}

Заголовки разделяются двумя символами: \r\n. Название заголовка от его значения отделяется двоеточием и пробелом:

Date: Mon, 01 Jun 2020 15:08:41 GMT
Expires: Tue, 12 May 2020 01:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Length: 23
Content-Type: application/json; charset=utf-8

• getResponseHeader(<Заголовок>) — возвращает значение указанного заголовка ответа сервера или значение null, если заголовок не найден или в случае ошибки:

success: function(json, status, xhr) {
   console.log( xhr.getResponseHeader('Content-Type') );
   // application/json; charset=utf-8
}

• abort([<Описание>]) — отменяет текущий запрос. Текст, указанный в качестве параметра, доступен через второй и третий параметры в обработчике, назначенном в опции error:

var xhr = $.ajax({
   url: '/ajax.php',
   data: { txt1: '1', txt2: '2' },
   error: function(xhr, status, error) {
      console.log(status);      // Истек тайм-аут
      console.log(error);       // Истек тайм-аут
   }
});
setTimeout( function() {
   xhr.abort('Истек тайм-аут');
}, 500);

• always(<Функция>) — принимает в качестве параметра ссылку на функцию, которая будет вызвана по окончании запроса, независимо от успешности его выполнения. Форматы функции:

function <Название функции>(<Данные>, <Статус>, <Объект jqXHR>) {
   // Для успешного запроса
}
function <Название функции>(<Объект jqXHR>,
                            <Статус>, <Исключение>) {
   // При ошибке
}

Пример:

$.ajax({
   url: '/ajax.php',
   data: { txt1: '1', txt2: '2' },
   dataType: 'json'
}).always( function(dataOrXhr, status, xhrOrError) {
   console.log(dataOrXhr);
   console.log(status);
   console.log(xhrOrError);
});

• done(<Функция>) — принимает в качестве параметра ссылку на функцию, которая будет вызвана в случае успешного выполнения запроса. Формат функции:

function <Название функции>(<Данные>, <Статус>, <Объект jqXHR>) {
   // ...
}

Через параметр <Данные> доступны данные, обработанные с учетом значения опции dataType;

• fail(<Функция>) — принимает в качестве параметра ссылку на функцию, которая будет вызвана при ошибке. Формат функции:

function <Название функции>(<Объект jqXHR>,
                            <Статус>, <Исключение>) {
   // ...
}

Пример (обратите внимание на цепочку вызовов методов):

$.ajax({
   url: '/ajax.php',
   data: { txt1: '1', txt2: '2' },
   dataType: 'json'
}).done( function(data, status, xhr) {
   console.log('done()');
   console.log(data);
   console.log(status);
   console.log(xhr);
}).fail( function(xhr, status, error) {
   console.log('fail()');
   console.log(xhr);
   console.log(status);
   console.log(error);
});

• then(<Функция1>[, <Функция2>]) — в первом параметре указывается ссылка на функцию, которая будет вызвана при успешном запросе. Формат функции:

function <Название функции>(<Данные>, <Статус>, <Объект jqXHR>) {
   // Для успешного запроса
}

Во втором параметре указывается ссылка на функцию, которая будет вызвана при ошибке. Формат функции:

function <Название функции>(<Объект jqXHR>,
                            <Статус>, <Исключение>) {
   // При ошибке
}

Пример:

$.ajax({
   url: '/ajax.php',
   data: { txt1: '1', txt2: '2' },
   dataType: 'json'
}).then(
   function(data, status, xhr) {
      console.log(data);
      console.log(status);
      console.log(xhr);
   },
   function(xhr, status, error) {
      console.log(xhr);
      console.log(status);
      console.log(error);
});

• catch(<Функция>) — принимает в качестве параметра ссылку на функцию, которая будет вызвана при ошибке. Формат функции:

function <Название функции>(<Объект jqXHR>,
                            <Статус>, <Исключение>) {
   // ...
}

Пример (обратите внимание на цепочку вызовов методов):

$.ajax({
   url: '/ajax.php',
   data: { txt1: '1', txt2: '2' },
   dataType: 'json'
}).then( function(data, status, xhr) {
   console.log('then()');
   console.log(data);
   console.log(status);
   console.log(xhr);
}).catch( function(xhr, status, error) {
   console.log('catch()');
   console.log(xhr);
   console.log(status);
   console.log(error);
});

• statusCode(<Объект>) — позволяет назначить обработчики для различных HTTP-кодов ответа сервера. Значение указывается в виде объекта:

$.ajax({
   url: '/ajax.php',
   data: { txt1: '1', txt2: '2' },
   dataType: 'json'
}).statusCode({
   404: function() {
      console.log('Страница не найдена');
   },
   200: function(data) {
      console.log(data);
   }
});

Объект jqXHR содержит все основные методы объекта Deferred (см. разд. 1.8.10), поэтому мы можем указывать его везде, где ожидается объект Deferred. Передадим объект jqXHR функции $.when() и дождемся готовности документа, передав во втором параметре $.ready:

var jqXHR = $.get('/ajax.php', {txt1: '1', txt2: '2'}, null, 'json');
$.when(jqXHR, $.ready).done( function(v1) {
   console.log(v1[0].txt1 + ' ' + v1[0].txt2); // 1 2
}).fail( function(xhr, status, error) {
   console.log('Ошибка: ' + error);
});

Учебник по jQuery и AJAX в формате PDF