jQuery.ajax()

Аргументы

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

$.ajax({
   url: a_cross_domain_url,
   xhrFields: {
      withCredentials: true
   }
});

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

Проще всего, функция $.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: 'http://fiddle.jshell.net/favicon.png',
  beforeSend: function( xhr ) {
    xhr.overrideMimeType( 'text/plain; charset=x-user-defined' );
  },
  success: function( data ) {
    if (console && console.log){
      console.log( 'Sample of data:', data.slice(0,100) );
    }
  }
});

Объект jqXHR, возвращенный с помощью $.ajax() реализовывает интерфейс Promise, давая им все свойства, методы и поведение Promise (смотрите Отсроченный объект для подробной информации). Для удобства и соответствия имен функций обратного вызова, используемых в $.ajax(), jqXHR также представляет методы .error(), .success(), и .complete(). Эти методы принимают аргумент функции, которая вызывается при завершении запроса $.ajax(), и функция получает те же аргументы, соответственно названию функции обратного вызова $.ajax(). В jQuery 1.5 это позволяет назначать несколько обратных вызовов на один запрос, и даже назначить функции обратного вызова после завершения запроса. (Если запрос уже завершен, функция обратного вызова будет немедленно вызвана.)

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.ajax({ url: "example.php" })
    .success(function() { alert("success"); })
    .error(function() { alert("error"); })
    .complete(function() { alert("complete"); });

// perform other work here ...

// Set another completion function for the request above
jqxhr.complete(function(){ alert("second complete"); });

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

• readyState
• status
• statusText
• responseXML и/или responseText, когда основной запрос получен с XML и/или текстом, соответственно
• setRequestHeader(имя, значение), которая отличается от стандартных заменяя старое значение на новое, а не объединением нового и старого значения
• getAllResponseHeaders()
• getResponseHeader()
• abort()

Не предоставляется механизм onreadystatechange, тем не менее, success, error, complete и statusCode охватывают все мыслимые требования.

Примечание: jqXHR.success() и jqXHR.error() будут устаревшими в jQuery 1.8 в пользу использования jqXHR.done() и jqXHR.fail(). Это позволит избежать путаницы в отношении имен функций обратного вызова, которые в идеале должны быть использованы.

Функции обратного вызова

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

1. beforeSend вызвается до того как запрос отправлен, и посылается объект XMLHttpRequest как параметр.
2. error вызывается если запрос не удался. Он посылает объект XMLHttpRequest, строку указывающую на тип ошибки, и надлежащий объект исключения.
3. dataFilter вызывается при успешном выполнении. Он передает полученные данные и значение dataType, и должен вернуть (возможно изменить) данные для передачи в success.
4. success вызывается, если запрос успешно выполнен. Он передает полученные данные, строку включающую удачный код, и объект XMLHttpRequest.
5. complete вызывается когда запрос закончен, будь то провал или успех. Он передает объект XMLHttpRequest, а также строку, содержащую success или код ошибки.

Типы данных

Функция $.ajax() опирается на сервер, чтобы предоставить информацию о полученных данных. Если сервер возвращает данные как XML, результат может быть прочитан с помощью нормальных методов XML или селекторов jQuery. Если зафиксирован другой тип, как HTML в примере выше, данные будут предоставленны как текст.

Различные обработки данных могут быть достигнуты с использованием опции dataType. Кроме простого xml, dataType может быть html, json, jsonp, script, или text.

Типы text и xml возвращают данные без обработки. Данные просто передаются обработчику success, либо через responseText или свойство responseHTML объекта XMLHttpRequest, соответственно.

Примечание: Мы должны быть уверенны, что тип MIME сообщенный веб-сервером, совпадает с нашим выбором dataType. В частности, XML должен быть объявлен сервером как text/xml или application/xml для устойчивых результатов.

Если html назначен, любой встроенный JavaScript внутрь источника данных будет выполнен до того как HTML будет возвращен как строка. Подобным образом, script выполнит JavaScript, который возвращен с сервера, затем возвращается сам сценарий как текстовые данные.

Тип json обрабатывает полученные данные файла как объект JavaScript и возвращает созданный объект как результат данных. Чтобы зделать это, он использует JSON.parse() когда браузер поддерживает ее; в противном случае он использует Function constructor. Данные JSON удобны для передачи структурированных данных таким образом, который краток и легок для обработки JavaScript. Если полученные данные файла существуют на удаленном сервере, тип jsonp может быть использован вместо этого. Этот тип вызовет параметр строки запроса callback=?, который приложен к URL; сервер должен предварить данные JSON с именем функции обратного вызова для формирования корректного запроса JSONP. Если указанное имя параметра необходимо вместо callback, оно может быть указанно с опцией jsonp для $.ajax().

Примечание: JSONP это расширение формата JSON, требуется некоторый код сервера для определения и обработки запроса строки парaметра. Полную информацию об этом можно найти в оригиналах использования.

Когда данные поступают с удаленного сервера ( который дает возможность использовать типы данных script или jsonp), операция выполняется используя тег <script> вместо объекта XMLHttpRequest. В этом случае, ни один объект XMLHttpRequest не будет возвращен из $.ajax(), также не один не будет послан обработчику функций, такому как beforeSend.

Посылка данных на сервер

По умолчанию, запросы Ajax посылаются используя метод GET HTTP. Если необходим метод POST, этот метод может быть определен с помощью установки значения для опции type. Эта опция влияет на то как содержимое data будет отправленно на сервер.

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

Дополнительные опции

Опция global пердотвращает использование .ajaxSend() зарегистрированными обработчиками, .ajaxError(), и аналргичные методы от запуска, когда эта просьба вызывает их. Это может быть полезно, например, подавить погрузку показателя, , который был реализован с .ajaxSend() если запросы являются частыми и краткими. Смотри описания этих методов ниже для более подробной информации.

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

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

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

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

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

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

Примеры

Пример 1

$.ajax({
   type: "GET",
   url: "test.js",
   dataType: "script"
 });

Пример 2

$.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });

Пример 3

$.ajax({
  url: "test.html",
  cache: false,
  success: function(html){
    $("#results").append(html);
  }
});

Пример 4

var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;

Пример 5

var xmlDocument = [create xml document];
 $.ajax({
   url: "page.php",
   processData: false,
   data: xmlDocument,
   success: handleResponse
 });

Пример 6

bodyContent = $.ajax({
      url: "script.php",
      global: false,
      type: "POST",
      data: ({id : this.getAttribute('id')}),
      dataType: "html",
      success: function(msg){
         alert(msg);
      }
   }
).responseText;