Функция $.ajax() лежит в основе всех запросов Ajax, отправляемых jQuery. Часто нет необходимости вызывать эту функцию напрямую, так как доступны несколько альтернатив более высокого уровня, таких как $.get() и .load(), которые проще в использовании. Однако, если требуются менее распространенные варианты, $.ajax() можно использовать более гибко.
В простейшем случае функцию $.ajax() можно вызвать без аргументов:
$.ajax();
Примечание: Значения по умолчанию можно установить глобально с помощью функции $.ajaxSetup().
В этом примере, без опций, загружается содержимое текущей страницы, но с результатом ничего не делается. Чтобы использовать результат, можно реализовать одну из функций обратного вызова.
Объект jqXHR
Объект jQuery XMLHttpRequest (jqXHR), возвращаемый функцией $.ajax() с версии jQuery 1.5, является супермножеством родного объекта XMLHttpRequest браузера. Например, он содержит свойства responseText и responseXML, а также метод getResponseHeader(). Когда механизм передачи данных отличается от XMLHttpRequest (например, тег скрипта для запроса JSONP), объект jqXHR имитирует функциональность родного XHR по возможности.
С версии jQuery 1.5.1 объект jqXHR также содержит метод overrideMimeType() (он был доступен и в jQuery 1.4.x, но временно удалён в jQuery 1.5). Метод .overrideMimeType() может быть использован в функции обратного вызова beforeSend(), например, для изменения заголовка типа содержимого ответа:
$.ajax({
url: "https://fiddle.jshell.net/favicon.png",
beforeSend: function( xhr ) {
xhr.overrideMimeType( "text/plain; charset=x-user-defined" );
}
})
.done(function( data ) {
if ( console && console.log ) {
console.log( "Sample of data:", data.slice( 0, 100 ) );
}
}); Объекты jqXHR, возвращаемые функцией $.ajax() с версии jQuery 1.5, реализуют интерфейс Promise, предоставляя все свойства, методы и поведение Promise (см. Объект Deferred для получения дополнительной информации). Эти методы принимают один или несколько аргументов-функций, которые вызываются при завершении запроса $.ajax(). Это позволяет назначать несколько функций обратного вызова для одного запроса и даже после того, как запрос может быть выполнен. (Если запрос уже завершён, функция обратного вызова вызывается немедленно.) Доступные методы Promise объекта jqXHR включают:
- jqXHR.done(function( data, textStatus, jqXHR ) {});
Альтернативный конструкт к опции success callback, см. deferred.done() для деталей реализации.
- jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});
Альтернативный конструкт к опции error callback, метод .fail() заменяет устаревший метод .error(). См. deferred.fail() для деталей реализации.
- jqXHR.always(function( data|jqXHR, textStatus, jqXHR|errorThrown ) { }); (добавлено в jQuery 1.6)
Альтернативный конструкт к опции complete callback, метод .always() заменяет устаревший метод .complete().
В ответ на успешный запрос аргументами функции являются те же, что и у .done(): данные, статус, и объект jqXHR. Для неудачных запросов аргументами являются те же, что и у .fail(): объект jqXHR, статус и ошибка. См. deferred.always() для деталей реализации.
- jqXHR.then(function( data, textStatus, jqXHR ) {}, function( jqXHR, textStatus, errorThrown ) {});
Объединяет функциональность методов .done() и .fail(), позволяя (с jQuery 1.8) управлять базовым Promise. См. deferred.then() для деталей реализации.
Предупреждение об устаревании: Функции обратного вызова jqXHR.success(), jqXHR.error(), и jqXHR.complete() удалены с версии jQuery 3.0. Используйте jqXHR.done(), jqXHR.fail(), и jqXHR.always() вместо них.
// Assign handlers immediately after making the request,
// and remember the jqXHR object for this request
var jqxhr = $.ajax( "example.php" )
.done(function() {
alert( "success" );
})
.fail(function() {
alert( "error" );
})
.always(function() {
alert( "complete" );
});
// Perform other work here ...
// Set another completion function for the request above
jqxhr.always(function() {
alert( "second complete" );
}); Ссылка this во всех функциях обратного вызова — это объект в опции context переданной в $.ajax в настройках; если context не указано, this — ссылка на сами настройки Ajax.
Для обратной совместимости с XMLHttpRequest, объект jqXHR будет предоставлять следующие свойства и методы:
-
readyState -
responseXML и/или responseText когда базовый запрос ответил xml и/или текстом соответственно -
status -
statusText (может быть пустой строкой в HTTP/2) -
abort( [ statusText ] ) -
getAllResponseHeaders() как строка -
getResponseHeader( name ) -
overrideMimeType( mimeType ) -
setRequestHeader( name, value ) которая отклоняется от стандарта, заменяя старое значение новым, а не конкатенируя новое к старому -
statusCode( callbacksByStatusCode )
Однако механизм onreadystatechange не предусмотрен, так как done, fail, always, и statusCode покрывают все возможные требования.
Очереди функций обратного вызова
Опции beforeSend, error, dataFilter, success и complete все принимают функции обратного вызова, которые вызываются в соответствующее время.
С версии jQuery 1.5, функции обратного вызова fail и done, и с jQuery 1.6, always управляются в очередях FIFO, что позволяет иметь более одной функции обратного вызова для каждого хука. Смотрите методы объекта Deferred, которые реализуются внутри для этих $.ajax() хуков обратного вызова.
Функции обратного вызова, предоставляемые $.ajax() следующие:
- Опция обратного вызова
beforeSend вызывается; она получает объект jqXHR и объект settings в качестве параметров. - Опция обратного вызова
error вызывается, если запрос завершился неудачей. Она получает jqXHR, строку, указывающую тип ошибки, и объект исключения, если применимо. Некоторые встроенные ошибки будут содержать строку в качестве объекта исключения: "abort", "timeout", "No Transport". - Опция обратного вызова
dataFilter вызывается немедленно после успешного получения данных ответа. Она получает возвращённые данные и значение dataType, и должна вернуть (возможно изменённые) данные для передачи в success. - Опция обратного вызова
success вызывается, если запрос завершился успешно. Она получает возвращённые данные, строку, содержащую код успеха, и объект jqXHR. - Функции обратного вызова Promise —
.done(), .fail(), .always(), и .then() — вызываются в порядке их регистрации. - Опция обратного вызова
complete срабатывает, когда запрос завершается, независимо от того, успешен он или нет. Она получает объект jqXHR, а также строку, содержащую код успеха или ошибки.
Типы данных
Разные типы ответов на вызов $.ajax() подвергаются различным видам предварительной обработки перед передачей обработчику успеха. Тип предварительной обработки зависит по умолчанию от заголовка Content-Type ответа, но может быть явно задан с помощью опции dataType. Если указана опция dataType, заголовок Content-Type ответа будет проигнорирован.
Доступные типы данных: text, html, xml, json, jsonp, и script.
Если text или html указаны, предварительная обработка не выполняется. Данные просто передаются обработчику успеха и доступны через свойство responseText объекта jqXHR.
Если указан xml, ответ анализируется с помощью jQuery.parseXML перед передачей, как XMLDocument, обработчику успеха. XML-документ доступен через свойство responseXML объекта jqXHR.
Если указан json, ответ анализируется с помощью jQuery.parseJSON перед передачей, как объект, обработчику успеха. Анализированный объект JSON доступен через свойство responseJSON объекта jqXHR.
Если указан script, $.ajax() выполнит JavaScript, полученный с сервера, перед передачей его обработчику успеха в виде строки.
Если указан jsonp, $.ajax() автоматически добавит параметр запроса (по умолчанию) callback=? к URL. Свойства jsonp и jsonpCallback настроек, переданных в $.ajax(), могут быть использованы для указания имени параметра запроса и имени функции обратного вызова JSONP соответственно. Сервер должен вернуть корректный JavaScript, передающий JSON-ответ в функцию обратного вызова. $.ajax() выполнит возвращённый JavaScript, вызвав функцию обратного вызова JSONP, прежде чем передать JSON-объект, содержащийся в ответе, обработчику успеха $.ajax().
Для получения дополнительной информации о JSONP, см. оригинальную запись, описывающую его использование.
Отправка данных на сервер
По умолчанию запросы Ajax отправляются с помощью HTTP-метода GET. Если требуется метод POST, метод можно указать, задав значение для опции type. Эта опция влияет на то, как содержимое опции data отправляется на сервер. Данные POST всегда передаются на сервер с кодировкой UTF-8, в соответствии со стандартом W3C XMLHTTPRequest.
Опция data может содержать строку запроса в формате key1=value1&key2=value2, или объект в формате {key1: 'value1', key2: 'value2'}. Если используется последняя форма, данные преобразуются в строку запроса с помощью jQuery.param() перед отправкой. Эту обработку можно обойти, установив processData в false. Обработка может быть нежелательной, если вы хотите отправить объект XML на сервер; в этом случае измените опцию contentType с application/x-www-form-urlencoded на более подходящий тип MIME.
Дополнительные опции
