jQuery.ajax()

Варианты использования

jQuery.ajax(URL[, настройки]) => jqXHR

Выполняет ajax-запрос с переданными настройками и возвращает расширенный XMLHttpRequest-объект. URL-адрес запроса указывается первым аргументом. Параметры запроса (настройки) задаются в виде объекта. Все настройки запроса по умолчанию имеют определённые значения, поэтому их указывать необязательно. Кроме того, с помощью метода jQuery.ajaxSetup() можно изменить дефолтные значения настроек для всех ajax-запросов. Описание всех настроек приводится ниже.

jQuery.ajax(настройки) => jqXHR

Выполняет ajax-запрос с переданными настройками. Отличие данного варианта от предыдущего только в том, что URL-адрес указывается в настройках запроса.

Параметры ajax-запроса

jqXHR-объект

jQuery XMLHttpRequest-объект (jqXHR) является улучшенным (дополненным) вариантом браузерного XMLHttpRequest-объекта. Например, он содержит свойства responseText, responseXML и метод getResponseHeader(). Для запросов типа 'jsonp', где не предполагается использование XMLHttpRequest-объекта, jQuery создаёт jqXHR-объект с нуля, делая его максимально похожим на браузерный XMLHttpRequest-объект.

jqXHR-объект содержит метод overrideMimeType(). Он может использоваться в обработчике события beforeSend для редактирования заголовка, который определяет тип содержимого, ожидаемого с сервера:

$.ajax({
  beforeSend: function(xhr) {
    xhr.overrideMimeType('text/plain; charset=x-user-defined');
  }
})

jqXHR-объект является Deferred-объектом (точнее его Promise-версией) и обладает соответствующими свойствами и методами. Это позволяет установить несколько обработчиков на один запрос, и даже установить обработчик уже после завершения запроса (если запрос уже выполнен, тогда обработчик запустится немедленно). jqXHR-объект имеет методы:

jqXHR.done(обработчик)

Альтернативный способ установки обработчика ajax-события success.

jqXHR.fail(обработчик)

Альтернативный способ установки обработчика ajax-события error.

jqXHR.always(обработчик)

Альтернативный способ установки обработчика ajax-события complete. Для успешного запроса в обработчик будут переданы аргументы, как в методе success(). Для неуспешного запроса в обработчик передаются аргументы, как в методе error().

jqXHR.then(обработчик_1, обработчик_2)

Альтернативный способ установки обработчиков ajax-событий success и error. Первый обработчик устанавливается на событие success, второй - на событие error.

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

• readyState
• status
• statusText
• responseXML или responseText
• setRequestHeader(name, value)
• getAllResponseHeaders()
• getResponseHeader()
• statusCode()
• abort()

Механизм onreadystatechange не поддерживается, но его возможности можно заменить методами done(), fail() и always().

Обработчики событий

Параметры beforeSend, error, dataFilter, success и complete используются для установки обработчиков событий, которые запускаются в определённое время:

• beforeSend - перед отправкой запроса.
• error - в случае неуспешного запроса.
• dataFilter - при получении данных с сервера.
• success - в случае успешного запроса (после dataFilter).
• complete - после завершения запроса (после error или success).

Переменная this во всех обработчиках содержит ссылку на объект, указанный в параметре context при вызове $.ajax().

Получение данных с сервера

Данные, полученные с сервера доступны в обработчике события success. Они передаются в него первым аргументом:

$.ajax({
  url: 'http://webgent.ru',
  success: function(data) {
    alert('Полученные данные: ' + data);
  }
})
/* или */
$.ajax('http://webgent.ru')
  .done(function(data) {
    alert('Полученные данные: ' + data);
  }
})

Если тип полученных данных 'text' или 'xml', тогда они также будут доступны в свойствах responseText или responseXML jqXHR-объекта соответственно.

Типы данных

Данные, полученные с сервера, перед передачей в обработчик события success подвергаются предварительной обработке (параметр converters). Вид обработки зависит от типа полученных данных (параметр dataType). По умолчанию jQuery определяет значение параметра dataType на основе MIME-типа, взятого из заголовка Content-Type. Чтобы самостоятельно определить, как интерпретировать ответ с сервера, необходимо использовать одно из следующих значений:

• 'text' - ответ с сервера передаётся в обработчик success без предварительной обработки. Данные также доступны в свойстве responseText jqXHR-объекта.
• 'html' - ответ с сервера передаётся в обработчик success без предварительной обработки. Данные также доступны в свойстве responseText jqXHR-объекта.
• 'xml' - ответ с сервера преобразуется в XML-документ с помощью функции jQuery.parseXML() перед передачей в обработчик success. Данный XML-документ также доступен в свойстве responseXML jqXHR-объекта.
• 'json' - ответ с сервера преобразуется в JSON-объект с помощью функции JSON.parse() перед передачей в обработчик success.
• 'jsonp' - ответ с сервера выполняется в виде JavaScript-кода (см. описание параметров jsonp и jsonpCallback).
• 'script' - ответ с сервера выполняется в виде JavaScript-кода, после чего преобразуется в текст и передаётся в обработчик success.

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

По умолчанию ajax-запросы выполняются, используя HTTP-метод GET. Если требуется использовать другой метод (например, POST), тогда необходимо указать его в параметре method. В соответствии со стандартом W3C при отправке данных с помощью метода POST используется кодировка UTF-8.

Данные для отправки на сервер задаются в параметре data:

• строкой в формате 'имя_1=значение_1&имя_2=значение_2...';
• объектом вида {имя_1: значение_1, имя_2: значение_2, ...}. Данный объект перед отправкой на сервер преобразуется в строку запроса с помощью функции jQuery.param().

Если в параметре processData отменить преобразование данных в строку запроса, тогда на сервер можно отправить любой объект (например, XML-документ). В этом случае необходимо изменить значение параметра contentType на более подходящий MIME-тип.

Дополнительные настройки

Параметр global позволяет отменить выполнение обработчиков глобальных ajax-событий (ajaxSend, ajaxError и т.п.). Для кроссдоменных запросов ('script' или 'jsonp') они отключены по умолчанию.

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

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

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

Параметр scriptCharset позволяет указать для SCRIPT-запросов, в какой кодировке получен ответ с сервера. Актуально, если кодировка страницы отличается от серверной.

Ajax-запросы выполняются асинхронно, то есть параллельно с основным потоком скрипта. Чтобы сделать запрос синхронным, необходимо для параметра async установить значение false. В этом случае выполнение основного кода приостанавливается до полного завершения запроса.

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

Расширенный Ajax

Реализация AJAX в jQuery предоставляет широкие возможности при выполнении запросов:

• Использование предварительных фильтров позволяет редактировать параметры запроса непосредственно перед отправкой запроса.
• Параметр converters позволяет получать данные с сервера в любом формате.
• Функция jQuery.ajaxTransport() позволяет использовать собственную функцию для отправки запроса на сервер.

Примеры

/* Отправить данные на сервер (например, для сохранения) и сообщить после выполнения */
$.ajax({
  method: 'POST',
  url: 'http://your-server.ru',
  data: {name: userName, password: userPassword},
  success: function() {
    alert('Данные отправлены.');
  }
})

/* Отправить на сервер XML-документ без преобразования. */
/* При неуспешном запросе сообщить об ошибке. */
$.ajax({
  url: 'http://your-server.ru',
  processData: false,
  data: xmlDocument,
  error: function() {
    alert('Запрос не выполнен.');
  }
})

/* Загрузить и выполнить JavaScript-файл. */
$.ajax({
  url: 'http://your-server.ru/js/form_check.js',
  dataType: 'script'
})