jQuery.ajax()


jQuery.ajax( url [, settings ] )Возвращает: jqXHR

Описание: Выполняет асинхронный HTTP (Ajax) запрос.

  • Добавлен в версии: 1.5jQuery.ajax( url [, settings ] )

    • url
      Тип: String
      Строка, содержащая адрес URL, к которому направляется запрос.
    • settings
      Тип: PlainObject
      Ассоциативный массив для конфигурации Ajax запроса. Все настройки не обязательные к заполнению (опциональны). Значения по умолчанию могут быть установлены при помощи метод $.ajaxSetup(). Ниже приведен полный список всех настроек.
  • Добавлен в версии: 1.0jQuery.ajax( [settings ] )

    • settings
      Тип: PlainObject
      Ассоциативный массив для конфигурации Ajax запроса. Все настройки не обязательные к заполнению (опциональны). Значения по умолчанию могут быть установлены при помощи метод $.ajaxSetup().
      • accepts (значение по умолчанию: зависит от dataType)
        Тип: PlainObject
        Ассоциативный массив отображающий заданный dataType его типу MIME, который отправляется полем Accept в заголовке HTTP запроса. Этот заголовок сообщает серверу какой формат ответа будет принят. Например, следующий пользовательский тип данных mycustomtype будет отправлен в запросе:
        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        $.ajax({
        accepts: {
        mycustomtype: 'application/x-some-custom-type'
        },
        // Инструкции кк десериализовать тип данных `mycustomtype`
        converters: {
        'text mycustomtype': function(result) {
        // Как то преобразуем
        return newresult;
        }
        },
        // Ожидаем от сервера тип данных `mycustomtype`
        dataType: 'mycustomtype'
        });
        Важно: Вы должны дополнительно указать соотвествующие типу converters для корректной обработки Ajax ответа.
      • async (значение по умолчанию: true)
        Тип: Boolean
        По умолчанию, все зпросы отпрвляются асинхронно (т.е. это значение установленное в true по умолчанию). Если Вам нужен синхронный запрос, установите значение параметра false. Кросс-доменные и dataType: "jsonp" запросы не поддерживают синхронные операции. Обратите внимние, что синхронные запросы могут временно блокировать браузер или приостанавливать какие то активные операции в моменты выполнения запроса. Начиная с jQuery 1.8, использование async: false с jqXHR ($.Deferred) не рекомендуется; Вы должны использовать обработчики success / error / complete вместо соотвествующих методов объекта jqXHR, таких как jqXHR.done().
      • beforeSend
        Тип: Function( jqXHR jqXHR, PlainObject settings )
        Обработчик вызываемый перед совершения запроса, в котором Вы можете модицифировать объект jqXHR (В версиях jQuery 1.4.x и ниже, XMLHTTPRequest) перед тем как Ajax запрос будет отправлен. Использовать пользовательские заголовки и т.д. The jqXHR and settings objects are passed as arguments. This is an Ajax Event. Returning false in the beforeSend function will cancel the request. As of jQuery 1.5, the beforeSend option will be called regardless of the type of request.
      • cache (значение по умолчанию: true, false для dataType 'script' и 'jsonp')
        Тип: Boolean
        Если устновлено значение false, то принудительно запрошенные страницы не будут закешированы браузером. Важно: Значение false параметра cache будет корректно работать только с запросами HEAD и GET. Это работает путем добавления "_={timestamp}" к адресу GET запроса. Этот параметр не нужендля других типов запросов, исключая случай с IE8 когда POST запрос осуществляется к тому же адресу URL к которому уже выполнялся GET запрос.
      • complete
        Тип: Function( jqXHR jqXHR, String textStatus )
        Функция которая вызывается когда запрос завершается (после того как success или error обработчики будут вызваны). Функция принимает два аргумента: объект jqXHR (в версии jQuery 1.4.x и ниже, XMLHTTPRequest) и строка статуса запроса ("success", "notmodified", "nocontent", "error", "timeout", "abort" или "parsererror"). Начиная с jQuery 1.5, параметр complete может принимать массив функций. Каждая функция будет вызывана в свою очередь. Является Ajax событием.
      • contents
        Тип: PlainObject
        Ассоциативный массив с парами строки/регулярные выражения определяющие как jQuery будет парсить ответ, в зависимости от типа контента. (Добавлен в версии: 1.5)
      • contentType (значение по умолчанию: 'application/x-www-form-urlencoded; charset=UTF-8')
        Тип: Boolean or String
        Когда отправляются данные на сервер, используется этот тип контента Content-Type. Значение по умолчанию "application/x-www-form-urlencoded; charset=UTF-8", которое прекрасно подходит для большинства случаев. Если Вы явно передаете content-type в метод $.ajax(), то он всегда будет отправлен на сервер (даже если никакие данные не будут отправлены на сервер). Начиная с jQuery 1.6 Вы можете указать значени false чтобы jQuery не передавал в заголовке поле Content-Type совсем. Важно: Стандарт W3C XMLHttpRequest specification предписывает всегда использовать кодировку UTF-8; указание другой кодировки не вынудит браузер изменить кодировку. Важно: Для кросс-доменных запросов, установка тип контента в значение отличающегося от application/x-www-form-urlencoded, multipart/form-data или text/plain вынудит браузер отправить подготовительный OPTIONS запрос на сервер.
      • context
        Тип: PlainObject
        Это объект будет контекстом для всех обработчиков этого Ajax запроса. По умолчанию контекстом является объект представляющий Ajax настройки используемые при вызове ($.ajaxSettings объединеные с настройками переданными в $.ajax). Например, указав DOM элемент как контекст сделает его контекстом в обработчике запроса complete:
        1
        2
        3
        4
        5
        6
        $.ajax({
        url: "test.html",
        context: document.body
        }).done(function() {
        $( this ).addClass( "done" );
        });
      • converters (значение по умолчанию: {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML})
        Тип: PlainObject
        Объект содержащий dataType-to-dataType конверторы. Значение каждого конвертора является функцией которая возвращает трансформированное значение ответа. (Добавлено в версии: 1.5)
      • crossDomain (значение по умолчанию: false для запросов к тому же домену, true для кросс-доменных запросов)
        Тип: Boolean
        Если Вы хотите выполнить запрос к тому же домену вынужденно как кросс-доменный (например JSONP), установите значение в true. Это позволяет, например, вернуть от сервера редирект н другой домен. (Добавлено в версии: 1.5)
      • data
        Тип: PlainObject или String или Array
        Данные отправляемые на сервер. Они будут преобразованы в строку, если еще не являются строкой. Для GET запроса эта строка будет добавлена к URL адресу. Смотрите праметр processData для предотвращения этой автоматической обработки. Объект должен быть ассоциативным массивом (пары ключ/значение). Если значение является массивом, то jQuery сериализирует значения массива с тем же самым ключем на основе значения параметра traditional (описан ниже).
      • dataFilter
        Тип: Function( String data, String type ) => Anything
        Функция используемая для обработки исходных данных от XMLHttpRequest. Это предварительная функция для проверки и чистки данных ответа. Вы должны вернуть очищенные данные. Функция принимает два аргумента: исходные данные отданные сервером и значение параметра dataType.
      • dataType (значение по умолчанию: Общеиспользуемые типы (xml, json, script, или html))
        Тип: String
        Тип данных которые Вы ожидаете от сервера. Если не указан, то jQuery будет пытаться определить его на базе типа MIME ответа (тип xml MIME даст XML, в 1.4 json даст JavaScript объект, в 1.4 script будет выполнен как скрипт и все прочее будет возвращено как строка). Возможные типы (и результат передается в качестве первого аргумента в обработчик запроса success):
        • "xml": Возвращает XML документ, который может быть обработан при помощи jQuery.
        • "html": Возвращает HTML как простой текст; включенные тэги скриптов будет выполнены когда этот HTML будет вставлен в DOM.
        • "script": Вычисляет ответ как JavaScript и возвращает его как простой текст. Отключает кэширование запроса (путем добавление параметра _=[TIMESTAMP] к URL адресу) даже если значение параметра cache равно true. Важно: Это превратит POST в GET для for запросов к удаленным доменам.
        • "json": Вычисляет ответ как JSON и возвращает JavaScript объект. Кросс-доменный "json" запрос конвертируются в "jsonp" если в параметрах запроса не указано jsonp: false. Данные в формате JSON обрабатываются в строгом порядке; любой нарушения формата будет отклонено и будет выброшена ошибка синтаксического анализа. Начиная с jQuery 1.9, пустой запрос также будет отклонен; сервер должен вернуть ответ null или {}.
        • "jsonp": Загружает данные в JSON используя при помощи формата загрузки JSONP. Добавляет дополнительный параметр "?callback=?" в конец URL адреса для указания функция обработчика. Выключает кэширование путем добавления параметра "_=[TIMESTAMP]" к URL адресу, даже если значение параметра cache равно true.
        • "text": Строка с текстом.
        • несколько, разделенных пробелом значений: начиная с jQuery 1.5, jQuery может преобразовать dataType от того что получен в поле заголовка Content-Type в то что Вам нужно. Например, если Вы хотите использовать текст ответа как XML, используйте значение "text xml" для параметра dataType. Вы также можете сделать JSONP запрос, если он получен в виде текста и интерпретируется jQuery как XML: "jsonp text xml". Точно так же, сокращенная строка, такая как "jsonp xml" сначала попытается преобразовать из JSONP в XML и если это невозможно, то преобразует из JSONP в текст и затем из текст в xml.
      • error
        Тип: Function( jqXHR jqXHR, String textStatus, String errorThrown )
        Функция вызывается если запрос закончится ошибкой. Функция принимает три аргумента: объект jqXHR (в jQuery 1.4.x, XMLHttpRequest), строка описывающая тип произошедшей ошибки и необязательный объект исключения, если он был вызван. Возможные значения второго аргумента (кроме null): "timeout", "error", "abort" и "parsererror". При возникновении HTTP ошибки, аргумент errorThrown примет текстовую часть HTTP статуса, такие как "Not Found" или "Internal Server Error." Начиная с jQuery 1.5, параметр error может принять массив функций. Каждая функция будет вызвана в своем порядке. Важно: Этот обработчик не вызывается для кросс-доменных скриптовых и кросс-доменных JSONP запросов. Являетсяе Ajax событием.
      • global (значение по умолчанию: true)
        Тип: Boolean
        Параметр регулирует вызывать ли глобальные Ajax события для этого запроса. По умолчанию значение равно true. Установка значения в false предотвратит вызов таких глобальных обработчиков как ajaxStart или ajaxStop. Это можно использовать для управления различными Ajax событиями.
      • headers (значение по умолчанию: {})
        Тип: PlainObject
        Объект с дополнительными полями заголовка HTTP запроса для отправки через XMLHttpRequest. Заголовок X-Requested-With: XMLHttpRequest добавляется всегда, но его значение по умоланию XMLHttpRequest можно изменить через этот параметр. Значения в headers также может быть переписаны в функции beforeSend. (добавлен в версии: 1.5)
      • ifModified (значение по умолчанию: false)
        Тип: Boolean
        Разрешает запросу быть успешным только если ответ изменился с момента последнего запроса. Это делается путем проверки поля заголовка Last-Modified. Значение по умолчанию false, игнорирует поля заголовка HTTP запроса. В jQuery 1.4 и ниже этот алгоритм также проверяет поле заголовка ответа 'etag' указанное сервером, что найти неизменненные данные.
      • isLocal (значение по умолчанию: зависит от текущего локального протокола)
        Тип: Boolean
        Разрешает текущему окружение как "локальное" (например файловая система), даже если jQuery не распознает его таким по умоланию. Следующие протоколыв в настоящее время признаются как локальные: file, *-extension и widget. Если опция isLocal требует изменения, то рекомендуется сделать это один раз при помощи метода $.ajaxSetup(). (добавлен в версии: 1.5.1)
      • jsonp
        Тип: String или Boolean
        Переопределяет имя функции обратного вызова в JSONP запросе. Это значение используется вместо названия функциии 'callback' в URL-параметре 'callback=?'. Так {jsonp:'onJSONPLoad'} передастся на сервер в виде 'onJSONPLoad=?'. Начиная с jQuery 1.5, значение параметра jsonp равное false предотвращает jQuery от добавления строки "?callback" к URL-адресу или попытки использовать "=?" для преобразования ответа. В этом случае, Вы должны явно указать значение параметра jsonpCallback. Например, { jsonp: false, jsonpCallback: "callbackName" }. Если Вы не доверяете целям Ваших Ajax запросов, то рекомендуется по соображениям безопасности установить значение параметра jsonp в false.
      • jsonpCallback
        Тип: String or Function()
        Указывает имя функции обратного вызова для запроса JSONP. Это значение будет использоваться вместо случайного имени, автоматически генерируемого jQuery. Предпотительно, чтобы jQuery само генерировало уникальное имя, это позволяет легче управлять запросами и обрабатывать ошибки. Вы можете указать функцию обратного вызова, если хотите обеспечить лучшее кэширование чем браузерное кэширование GET запросов. Начиная с jQuery 1.5, Вы также можете использовать функцию для этого параметра, в этом случае, значение jsonpCallback устанавливается в качестве возвращаемого значения этой функции.
      • method (значение по умолчанию: 'GET')
        Тип: String
        HTTP метод используемый в запросе (например "POST", "GET", "PUT" и т.д.). (добавлен в версии: 1.9.0)
      • mimeType
        Тип: String
        MIME тип переопределяющий XHR MIME тип. (добавлен в версии: 1.5.1)
      • password
        Тип: String
        Пароль для использования с XMLHttpRequest в ответ на запрос basic http авторизации.
      • processData (значение по умолчанию: true)
        Тип: Boolean
        По умолчанию данные, передаваемые в параметр data в качестве объекта (технически, все кроме строки) будут обработаны и преобразованы в строку запроса, подходящую для типа данных по умолчанию "application/x-www-form-urlencoded". Если Вы хотите отправить DOM документ, или другие необрабатываемые данные, установите значение данного параметр в false.
      • scriptCharset
        Тип: String
        Применяется только при использовании "script" в качестве транспорта (например, кросс-доменные запросы с "jsonp" или "script" dataType и методом "GET"). Устанавливает аттрибут charset используемого тэга script в запросе. Используется, когда кодировка символов на текущей странице отличается от кодировки символов удаленного скрипта.
      • statusCode (значение по умолчанию: {})
        Тип: PlainObject

        Объект с числовыми кодами HTTP кодов статусов и функции которые будут вызваны когда статус ответа имеет соотвествующее значение. Например, следующий alert будет вызван когда статус ответа будет 404:

        1
        2
        3
        4
        5
        6
        7
        $.ajax({
        statusCode: {
        404: function() {
        alert( "страниц не найдена" );
        }
        }
        });

        Если запрос успешен, то соотвествующая функция будет принимать те же самые параметры что и success обработчик; если результат ошибка (включая редиректы 3xx), то эти функции примут те же параметры что и обработчик error.

        (добавлен в версии: 1.5)
      • success
        Тип: Function( Anything data, String textStatus, jqXHR jqXHR )
        Функция вызываемая если запрос успешен. Функция принимает три аргумента: data - данные возвращенные с сервера, отформатированные в соответствии с параметром dataType или dataFilter если они указаны; строка описывающая статус; и объект jqXHR (в версии jQuery 1.4.x и ниже XMLHttpRequest). Начиная с jQuery 1.5, Этот параметр может принимать массив функций. Каждая функция будет вызывана в свою очедерь. Является Ajax событием.
      • timeout
        Тип: Number
        Задает таймаут запроса (в милисекундах). Этот параметр переопределяет глобальный таймаут, устанавливаемый при помощи метода $.ajaxSetup(). Этот таймаут запускается в момент запуска метода $.ajax; если несколько других запросов в процессе работы и браузер не имеет сетевого подключения, то возможен запрос на таймаут, прежде чем он будет отправлен. В версии jQuery 1.4.x и ниже, объект XMLHttpRequest будет находиться в недопустимом состоянии если время ожидния будет превышено; обращение к любым методам объекта сгенерирует исключение. В Firefox 3.0+, script и JSONP запросы не могут быть отменены по таймауту; скрипт будет работать, даже если он прийдет после таймаута.
      • traditional
        Тип: Boolean
        Используйте значение true если Вы хотите использовать традиционный стиль сериализации параметров.
      • type (значение по умолчанию: 'GET')
        Тип: String
        Синоним для параметра method. Вы должны использовать type если Вы используете версию jQuery до 1.9.0.
      • url (значение по умолчанию: Текущий URL-адрес)
        Тип: String
        Строка содержащая URL-адрес на который будет отправлен запроса.
      • username
        Тип: String
        Имя пользователя используемое с XMLHttpRequest в ответ на запрос basic http авторизации.
      • xhr (значение по умолчанию: ActiveXObject когда доступен (IE), иначе XMLHttpRequest)
        Тип: Function()
        Функция обратного вызова для создания объекта XMLHttpRequest. По умолчанию используется ActiveXObject когда доступен (для IE), иначе используется XMLHttpRequest. У Вас есть возможность переопределить создание этого объекта и вернуть свою реализацию XMLHttpRequest или улучшить создание этого объекта.
      • xhrFields
        Тип: PlainObject

        Объект с парами fieldName-fieldValue для установки в нативный объект XHR. Например, Вы можете использовать значение withCredentials равное true для кросс-доменных запросов в случае необходимости.

        1
        2
        3
        4
        5
        6
        $.ajax({
        url: a_cross_domain_url,
        xhrFields: {
        withCredentials: true
        }
        });

        В jQuery 1.5, свойство withCredentials не будет распространено на нативный объект XHR и таким образом CORS запросы требуя его будет игнорировать этот флаг. По этой причине, мы рекомендуем использовать jQuery 1.5.1+.

        (добавлен в версии: 1.5.1)

Функция $.ajax() лежит в основе всех Ajax запросов отправляемых при помощи jQuery. Зачастую нет необходимости вызывать эту функцию, так как есть несколько альтернатив более высого уровня, такие как $.get() и .load(), которые более простые в использовании. Если требуется менее распространенные варианты , через, $.ajax() Вы можете более гибко скофигурировать запрос.

В простейшем виде, функция $.ajax() может быть вызвана без аргументов:

1
$.ajax();

Важно: настройки по умолчанию могут быть установлены при помощи функции $.ajaxSetup().

Этот пример, не используюя никаких параметров, загружает содержимое текущей страницы, но ничего не делает с результатом. Для использования результата, Вы можете реализовать одну из функция обратного вызова.

Объект jqXHR

Объект jQuery XMLHttpRequest (jqXHR) возвращается функцией $.ajax() начиная с jQuery 1.5 является надстройкой над нативным объектом XMLHttpRequest. Например, он содержит свойства responseText и responseXML, а также метод getResponseHeader(). Когда траспортом используемым для запрос является что то иное, а не XMLHttpRequest (например, тэг script tag для JSONP запроса) объект jqXHR эмулирует функционал нативного XHR там где это возможно.

Начиная с jQuery 1.5.1, объект jqXHR также содержит метод overrideMimeType() (он был доступен в jQuery 1.4.x, но был временно удален в версии jQuery 1.5). Метод .overrideMimeType() может быть использован в обработчике beforeSend(), например, для изменения поля заголовка content-type:

1
2
3
4
5
6
7
8
9
10
11
$.ajax({
url: "http://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. Эти методы принимают один или несколько аргументов, которые вызываются при завершении запроса инициированного при помощи $.ajax(). Это позволяет назначать несколько обработчиков на один запрос и даже назначать обработчики после того как запрос может быть завершен. (Если запрос уже выполнен, то обработчики вызовутся немедленно). Доступные методы Promise в объекте jqXHR:

  • jqXHR.done(function( data, textStatus, jqXHR ) {});

    Альтернатива создания обработчика success, подробнее смотрите на deferred.done().

  • jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});

    Альтернатива создания обработчика error, метод .fail() заменяет устаревший метод .error(). Смотрите подробнее deferred.fail().

  • jqXHR.always(function( data|jqXHR, textStatus, jqXHR|errorThrown ) { }); (добавлен в версии jQuery 1.6)

    Альтернатива создания обработчика complete, метод .always() заменяет устаревший метод .complete().

    В ответ на успешный запрос, аргументы функции те же самые что и у .done(): data, textStatus и объект jqXHR. Для ошибочных зпросов аргументы те же самые что и у .fail(): объект jqXHR, textStatus и errorThrown. Смотрите подробнее 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() соответственно.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Назначаем обработчики сразу после выполнения запроса
// и сохраняем объект jqXHR для этого запроса
var jqxhr = $.ajax( "example.php" )
.done(function() {
alert( "success" );
})
.fail(function() {
alert( "error" );
})
.always(function() {
alert( "complete" );
});
// Что то делаем ...
// Установим другой обработчик выполнения запроса
jqxhr.always(function() {
alert( "second complete" );
});

Ссылка this внутри всех обработчиков указывает на объект заданный в параметре context переданные в аргумент settings метода $.ajax; если context не указан, то this указывает на объект settings.

Для обеспечения обратной совместимости с кодом XMLHttpRequest, в объекте jqXHR предоставляет следующие свойства и методы:

  • readyState
  • status
  • statusText
  • responseXML и/или responseText когда запрос вернул xml и/или text, соответственно
  • setRequestHeader(name, value) те заголовки что отходят от стандарта, заменят старое значение на новое, а не конкатенируют старое и новые значения
  • getAllResponseHeaders()
  • getResponseHeader()
  • statusCode()
  • abort()

Механизма onreadystatechange не предусмотрено, так как done, fail, always и statusCode охватывает все возможные требования.

Очередность функций обратного вызова

Все параметры beforeSend, error, dataFilter, success и complete принимают в качестве значений функции обратного вызова, которые вызываются в соотвествующие моменты времени.

С версии jQuery 1.5 функции fail и done, и, начиная с jQuery 1.6, always вызовутся в первую очередь, первыми из упрвляемой очереди, что позволяет более чем один обработчик для каждого элемента очереди. Смотрите отложенные методы, которые реализуют внутренности обработчиков метода $.ajax().

Функции обратного вызова предоставленные методом $.ajax() следующие:

  1. beforeSend вызывается всегда; принимает jqXHR объект и объект settings как параметры.
  2. error вызывается, если запрос выполняется с ошибкой. Принимает объект jqXHR, строку со статусом ошибки и объект исключения если применимо. Некоторые встроенные ошибки обеспечивают строку качестве объекта исключения: "abort", "timeout", "No Transport".
  3. dataFilter вызывается немедленно при успешном получении данных ответа. Принимает в качестве параметров возвращенные данные и знчение параметра dataType и должен вернуть (возможно измененные данные) для передачи далее в обработчик success.
  4. success вызывается если запрос выполнен успешно. Принимает данные ответа, строку содержащую код успеха и объект jqXHR.
  5. Promise обработчик.done(), .fail(), .always() и .then() — выполняются, в том порядке в котором зарегистрированы.
  6. complete вызывается когда запрос закончен, независимо от успеха или неудачи выполнения запроса. Принимает объект jqXHR, отформатированную строку со статусом успеха или ошибки.

Типы данных

Различные типы ответа на вызов $.ajax() подвергаются различным видам предварительной обработки перед передачей обработчика success. Тип предварительной подготовки зависит от указанного в ответе поля заголовка Content-Type, но может быть явно указан при помощи опции dataType. Если параметр dataType задан, то поле заголовка Content-Type будет проигнорирован.

Возможны следующие типы данных: text, html, xml, json, jsonp и script.

Если указан text или html, никакой предварительной обработки не происходит. Данные просто передаются в обработчик success и доступны через свойство responseText объекта jqXHR.

Если указан xml, то ответ парсится при помощи jQuery.parseXML перед передачей в XMLDocument в обработчик success. XML документ доступен через свойство responseXML объекта jqXHR.

Если указан json, то ответ парсится при помощи jQuery.parseJSON перед передачей в объект для обработчика success. Полученный JSON объект доступен через свойство responseJSON объекта jqXHR.

Если указан script, то $.ajax() выполнит JavaScript код который будет принят от сервере перед передачей этого кода как строки в обработчик success.

Если указан jsonp, $.ajax() автоматически добавит в строку URL запроса параметр (по умолчанию) callback=?. Параметры jsonp и jsonpCallback из объекта settings переданных в метод $.ajax() могут быть использованы для указания имени URL-параметра и имени JSONP функции обратного вызова соответственно. Сервер должен вернуть корректный Javascript который будет переда в обработчик JSONP. $.ajax() выполнит возвращенный JavaScript код, вызвыв функцию JSONP по ее имени, перед передачей JSON объекта в обработчик success.

Отправка данных на сервер

По умолчанию, Ajax запросы отправляются при помощи GET HTTP метода. Если POST метод требуется, то метод следует указать в настройках при помощи параметра type. Этот параметр влияет на то как данные из параметра data будут отправлены на сервер. Данные POST запроса всегда будут переданы на сервере в UTF-8 кодировкепо стандарту W3C XMLHTTPRequest.

Параметр data может содержать строку произвольной формы, например сериализованная форма key1=value1&key2=value2 или Javascript объект {key1: 'value1', key2: 'value2'}. Если используется последний вариант, то данные будут преобразованы в строку при помощи метода jQuery.param() перед их отправкой. Эта обработка может быть отключена при помощи указания значения false в параметре processData. Обработка может быть нежелательной, если Вы хотите отправить на сервере XML документ, в этом случае измените параметр contentType с application/x-www-form-urlencoded на более подходящий MIME тип.

Расширенные настройки

Параметр global предотвращает выполнение обработчиков зарегистрированных при помощи методов .ajaxSend(), .ajaxError() и подобных методов. Это может быть полезно, например, для скрытия индикатора загрузки реализованного при помощи .ajaxSend() если запросы выполняются часто и быстро. С кросс-доменными и JSONP запросами, параметр global автоматически устанавливается в значение false.

Если сервер выполняет HTTP аутентификацию перед предоствлением ответа, то имя пользователя и пароль должны быть отправлены при помощи параметров username и password options.

Ajax запросы ограничены по времени, так что ошибки могут быть перехвачены и обработаны, чтобы обеспечить наилучшее взаимодействие с пользователем. Таймауты запроса обычно либо установлены по умолчанию, либо установлены глобально при помощи $.ajaxSetup() вместо того чтобы указывать параметр timeout для каждого отдельного запроса.

По умолчанию, запросы всегда совершаются, но браузер может предоставить ответ из своего кэша. Для запрета на использования кэшированных результатов установите значение параметра cache в false. Для того чтобы вызвать запрос с отчетом об изменении ресурса со времени последнего запроса установите значение параметра ifModified в true.

Параметр scriptCharset разрешает кодировку которая будет явно использована в запросах использующих тэг <script> (то есть тип данных script или jsonp). Это применимо в случае если удаленный скрипт и Ваша текущая страница используют разные кодировки.

Первая буква в слове Ajax означает "асинхронный", что означает что операция происходит параллельно и порядок ее выполнения не гарантируется. Параметр async метода $.ajax() по умолчанию равен true, что указывает что выполнение кода может быть продолжено после совершения запроса. Установка этого параметра в false (и следовательно, не делая Ваш вывод более асинхронным) настоятельно не рекомендуется, так как это может привести к тому что браузер перестанет отвечать на запросы.

Метод $.ajax() вернет объект XMLHttpRequest который и создает. Обычно jQuery обрабатывает создание этого объекта внутри, но можно указать при помощи параметра xhr функция которая переопределит поведение по умолчанию. Возвращаемый объект обычно может быть отброшен, но должен обеспечивать интерфейс низкого уровня для манипуляции и управления запросом. В частности, вызов .abort() на этом объекте должен будет остановить запрос до его завершения.

Расширение Ajax

Начиная с jQuery 1.5, реализация Ajax в jQuery включает предварительные фильтры, транспорты и преобразователи, которые позволят Вам очень гибко настроить Ajax запросы под любые нужды.

Использование преобразований

$.ajax() преобразователи поддерживают трансформацию одних типов данных другие. Однако, если Вы хотите трансформировать пользовательский тип данных в известный тип данных (например json), Вы должны добавить добавить соответствие между Content-Type ответа и фактическим типом данных, используя параметр contents:

1
2
3
4
5
6
7
8
9
10
11
$.ajaxSetup({
contents: {
mycustomtype: /mycustomtype/
},
converters: {
"mycustomtype json": function( result ) {
// Какие то действия
return newresult;
}
}
});

Этот дополнительный объект необходим, потому что Content-Types ответа и типы данных никогда не имеют однозначного соответствия между собой (отсюда и регулярное выражение).

Для преобразования из поддерживаемого типа (например text или json) в пользовательский тип данных и обратно, используйте другой сквозной преобразователь:

1
2
3
4
5
6
7
8
9
10
11
12
$.ajaxSetup({
contents: {
mycustomtype: /mycustomtype/
},
converters: {
"text mycustomtype": true,
"mycustomtype json": function( result ) {
// Какие то действия
return newresult;
}
}
});

Пример выше позволяет перейти из text в mycustomtype и затем из mycustomtype в json.

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

  • Из за ограничений безопасности браузера, большинство "Ajax" запросов подвергаются политике того же домена, которая не позволяет выполнять запросы к другим доменам, поддоменам, портам или протоколам.
  • Script и JSONP запросы не подвергаются ограничениям этой политики.

Примеры:

Сохраняет некоторые данные на сервере и уведомление пользователя об окончании.

1
2
3
4
5
6
7
8
$.ajax({
method: "POST",
url: "some.php",
data: { name: "John", location: "Boston" }
})
.done(function( msg ) {
alert( "Data Saved: " + msg );
});

Возврашает последнюю версиюю HTML страницы.

1
2
3
4
5
6
7
$.ajax({
url: "test.html",
cache: false
})
.done(function( html ) {
$( "#results" ).append( html );
});

Отправляет XML документ на сервер. При помощи установки значения параметра processData в false, автоматическое преобразование в строку отключено.

1
2
3
4
5
6
7
8
var xmlDocument = [create xml document];
var xmlRequest = $.ajax({
url: "page.php",
processData: false,
data: xmlDocument
});
xmlRequest.done( handleResponse );

Отправляет идентификатор элемента как данные на сервер, и уведомляет пользователя об окончании. Если запрос заканчивается ошибкой, то показывается alert с ошибкой.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var menuId = $( "ul.nav" ).first().attr( "id" );
var request = $.ajax({
url: "script.php",
method: "POST",
data: { id : menuId },
dataType: "html"
});
request.done(function( msg ) {
$( "#log" ).html( msg );
});
request.fail(function( jqXHR, textStatus ) {
alert( "Request failed: " + textStatus );
});

Загружает и выполняется JavaScript файл.

1
2
3
4
5
$.ajax({
method: "GET",
url: "test.js",
dataType: "script"
});