Функция jQuery.ajax()

Детальное описание основной функции jQuery, реализующей AJAX запросы. Приведены примеры использования.

jQuery.ajax(параметры) является основной функцией в jQuery, реализующей динамическую загрузку данных на клиент по AJAX технологии. Функция представляет собой универсальную низкоуровневую реализацию технологии и обеспечивает полное управление запросом.
Входные параметры — задаются объектом в виде пар ключ:’значение'[,ключ:’значение’], где ключ — это наименование параметра, а через двоеточие — его значение. Все параметры являются необязательными и могут быть установлены по умолчанию с помощью метода $.ajaxSetup().
Начиная с версии 1.5 в jQuery был добавлен еще один вариант вызова функции — jQuery.ajax(url,параметры), в котором адрес запроса url задается самостоятельно, а не в составе параметров запроса. Данные запроса передаются на сервер в кодировке UTF-8.

Описание входных параметров функции jQuery.ajax(параметры):

• async(boolean) — по умолчанию true, при этом все запросы загружаются асинхронно, в противном случае запрос будет синхронный, т.е. с ожиданием ответа сервера. На время ожидания происходит блокировка страницы, т.е. теряются преимущества динамической загрузки данных, чем и ценен AJAX. Кроме того, кроссдоменные запросы не могут быть выполнены синхронно;
• beforeSend( XHR )(функция)(см. примечание) — определяет функцию, которая будет выполнена непосредственно перед отправкой AJAX запроса. Покольку данная функция является обработчиком определенного события при запросах(об этом речь еще пойдет), то при возвращении ею false, запрос отменяется. Начиная с jQuery v.1.5, beforeSend вызывается независимо от типа запроса;
• cache(boolean) — если равно false, то браузер не кеширует запрос, кроме того в url запроса будет добавлена строка «_=[TIMESTAMP]»;
• complete(функция) — определяет функцию вида somefunction(jqXHR, textStatus), которая будет вызвана после после завершения AJAX запроса. Эта функция вызывается после вызова функции, обрабатывающей успешное или аварийное завершение запроса. Функции передаются два параметра — объект jqXHR и строка выполнения запроса(«success», «notmodified», «error», «timeout», «abort», или «parsererror»). Начиная с вервии 1.5, в этот параметр можно передать массив функций, которые будут выполнены в той очередности, в которой заданы в массиве.
• contentType(строка) — определяет формат данных в запросе. В большинстве случаев подходит используемый по умолчанию ‘application/x-www-form-urlencoded’, но параметр позволяет задавать и другие форматы;
• context(объект) — передаваемый в параметре объект становится контекстом для всех функций обратного вызова текущего AJAX запроса;
• data(строка, объект) — данные, отправляемые на сервер с запросом. Формат отправляемых данных зависит от значения параметра processData(см. ниже). Если передача происходит методом GET, строка параметра присоединяется к строке запроса URL, если методом POST, то данные передаются в теле запроса;
• dataFilter(data,type)(функция) — назначает функцию предварительной обработки данных, пришедших с сервера. Входные параметры — сами данные и их тип, указанный в параметре dataType;
• dataType(строка) — определяет тип данных, в формате которого ожидается ответ сервера, допустимые значения:»xml», «html», «script», «json», «jsonp», «text». Если тип не задан, то он определяется автоматически по MIME-типу ответа сервера;
• error(XHR,textStatus,errorThrown)(функция) — функция, вызываемая при неудачном завершении запроса. Назначаемой функции передаются 3 параметра, объект jqXHR, строка описания ошибки и объект исключения. Начиная с версии 1.5 в этом параметре можно передавать массив функций;
• global(boolean) — определяет обработку событий AJAX запроса, по умолчанию true, при этом вызываются обработчики событий запроса, например, обработчики событий ajaxStart или ajaxStop, при значении false обработчики событий не вызываюься;
• ifModified(boolean) — по умолчанию false, при этом пришедшие данные не анализируется на предмет изменений с прошлого раза, если true, то запрос будет считаться успешным, если пришедшие данные отличаются от данных предыдущего запроса;
• jsonp(строка) — переопределяет имя функции обратного вызова для кроссдоменного запроса jsonp;
• jsonpCallback(строка) — определяет имя функции, которая будет вызвана при ответе сервера на jsonp-запрос. Указываемая функция будет использоваться вместо имени генерируемого библиотекой jQuery. Использование данного параметра позволяет избегать пропусков кэширования браузером GET запросов;
• password(строка) — пароль, который необходим для аутентификаци на сервере, если есть подобная необходимость;
• processData(boolean) — по умолчанию true, при этом данные, отправленные на сервер в параметре data, преобразуются в строку запроса вида (name1=value1&name2=value2&…), соответствующую «application/x-www-form-urlencoded». При величине параметра false данные не преобразовываются;
• scriptCharset(строка) — используется для кроссдоменных AJAX запросов методом GET, dataType при этом может быть или «jsonp», или «script». Параметр определяет кодировку, в которой будет выполнен кроссдоменный запрос и необходим для согласования кодировок на разных серверах при кроссдоменных запросах;
• success(data,textStatus,XHR)(функция) — функция, вызываемая при удачном завершении запроса, ей на вход поступают 3 параметра — сами данные, уже прошедшие предварительную обработку, строка со статусом выполнения и объект запроса jqXHR. С версии 1.5 параметр может принимать массив функций;
• timeout(число) — задает максимальное время ожидания ответа от сервера в миллисекундах, после которого запрос завершается с ошибкой. Отсчет начинается с момента вызова функции $.ajax;
• traditional(boolean) — при значении true будет производиться традиционная(упрощенная) сериализация при отправке данных;
• type(строка) — устанавливает тип запроса GET или POST. Доступны и другие типы запроса, но их поддерживают не все браузеры;
• url(строка) — устанавливает адрес, по которому отправляется запрос;
• username(строка) — если необходима аутентификация, то в параметре указывается имя пользователя;
• xhr(функция) — устанавливает функцию, с помощью которой можно определить свой объект XMLHttpRequest, т.к. в браузеры IE по умолчанию создают объект ActiveXObject, остальные — XMLHttpReques.

Возвращаемое значение — экземпляр объекта XMLHttpRequest. Строго говоря, функция ajax() библиотеки, начиная с версии 1.5, возвращает объект-надстройку над базовым объектом XMLHttpRequest, она возвращает jQuery XMLHttpRequest (jqXHR). Предлагаю самым дотошным самостоятельно разобраться, чем они отличаются, в помощь могу предложить почитать, например, здесь(eng) а мы пойдем дальше, т.к. создатели jQuery постарались чтобы надстройка была очень похожей на предка и не преподносила сюрпризов при реализации и контроле AJAX запросов.

  Примеры AJAX запросов

Пример1     AJAX запрос текстовой строки методом GET.

Ниже приведена текстовая строка синего цвета. По клику левой кнопки мыши на этом тексте будет произведен асинхронный AJAX запрос текстовой строки, которая заменит текущую, в запросе используется метод GET.

Описание примера1

Ниже приведен элемент разметки, который замещается данными AJAX запроса.

<div id="sample1" class="sample1" style="cursor:pointer;color:blue;"
onclick="getData()>
<em>
 Текст, который по клику мыши будет заменен данными AJAX запроса.
</em>
</div>

А вот сам javascript AJAX запроса.

<script type="text/javascript">
  function getData() {
    jQuery.ajax({
      url: 'адрес_скрипта_на_сервере',
      data: 'sample=1',
      type: 'GET',
      success: function(data) { jQuery('.sample1').html(data); }
    });
  }
</script>

Пример2     AJAX запрос текстовой строки методом POST.

В примере по клику кнопки мыши на тексте синего цвета производится AJAX запрос строки, которая заменит текст примера, единственное отличие — запрос производится методом POST.

Описание примера2

Элемент разметки, который замещается данными AJAX запроса.

<div id="sample2" class="sample2" style="cursor:pointer;color:blue;"onclick="getDataPost()">
  <em>
    Текст, который по клику левой кнопки мыши будет заменен данными AJAX запроса, тип запроса POST.
  </em>
</div>

Текст скрипта AJAX

<script type="text/javascript">
function getDataPost() {
    jQuery.ajax({
      url: 'адрес_скрипта_на_сервере',
      data: 'sample=2',
      type: 'POST',
      success: function(data) { jQuery('.sample2').html(data); }
    });
}
</script>

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

Текст скрипта весьма прост.

function sendData() {
  jQuery.ajax({
    url: 'адрес_скрипта_на_сервере',
    type: 'POST',
    data: 'sample=3&location=webdesignstudio1',
    success: function(data) {
      if (data === "successfully") {
        alert('Данные доставлены на сервер!'); 
      } else {
        alert(data); 
      }
    }
  });
};