jQuery.ajax

« Обратно к странице функций Ajax

[редактировать]

jQuery.ajax( опции )

Загружает удаленную страницу используя HTTP запрос.
Это низкоуровневая реализация AJAX в jQuery. Для функций более высокого уровня абстракции обратитесь к $.get, $.post и т.д., которые, зачастую, легче понять и использовать, но которые все же предоставляют ограниченную функциональность по сравнению с данным методом.

$.ajax() возвращает объект XMLHttpRequest. В большинстве случаев Вам не понадобится работать непосредственно с этим объектом, но он все же доступен, в случае, если Вам необходимо прервать запрос вручную.

В качестве аргумента функции $.ajax() передается объект, состоящий из пар ключ/значение, которые используются для инициализации и управления запросом.

Примечание: если Вы указываете опцию dataType, которая описывается в разделе «Опции» на этой странице, то убедитесь, что сервер отсылает корректный тип MIME в своем ответе (например, xml как «text/xml»). Некорректный тип MIME может стать причиной непредвиденных проблем в работе Вашего скрипта. Для более детальной информации обратитесь к разделу Указание типа данных для запросов AJAX.

Примечание: если параметр dataType установлен в ’script’ или ‘jsonp’, то все удаленные (не в пределах одного домена) запросы должны быть указаны как запросы типа GET (поскольку скрипт загружается используя тег script модели DOM). Опции AJAX, которые требуют объект XMLHttpRequest, недоступны для таких запросов. Функции complete и success вызываются по завершению запроса; они не получают объект XHR. Функции beforeSend и dataFilter не вызываются.

Начиная с jQuery версии 1.2 у Вас есть возможность загружать данные JSON расположенные на другом домене. Для этого нужно использовать функцию JSONP в качестве функции callback (обратного вызова), например, «myurl?callback=?». jQuery автоматически заменяет знаки «?»  на соответствующее имя метода, который необходимо использовать, вызывая функцию, которую вы указали в callback. Если Вы устанавливаете параметр dataType в ‘jsonp’, то Ваша функция автоматически будет прикреплена к запросу AJAX.

Аргумента:

опции Опции
Набор пар ключ/значение для конфигурирования запроса AJAX. Все опции опциональны, обязательных нету. Значение по умолчанию можно выставить для любой опции используя метод $.ajaxSetup().
Опции:

Имя Тип
async Логическое значение По умолчанию: true
По умолчанию, все запросы отсылаются асинхронно (т.е. значение true). Если Вам необходимо посылать запросы синхронно, установите данную опцию в false. Обратите внимание, что синхронные запросы могут на время выполнения запроса заблокировать браузер.
beforeSend Функция
Функция для модификации объекта XMLHttpRequest перед отправкой. Используйте её для установки пользовательских заголовков и т.д. В качестве аргумента передается XMLHttpRequest. Это событие Ajax. Для отмены запроса следует возвратить false в данной функции.

function (XMLHttpRequest) {
  this; // the options for this ajax request
}
cache Логическое значение По умолчаниюt: true, false для значений dataType «script» и «jsonp»
Добавлено в jQuery 1.2, чтобы отключить кеширование браузером запрашиваемых Вами страниц, установите значение этой опции в false.
complete Функция
Функция, которая исполняется всякий раз после завершения запроса AJAX (после того, как выполнились success и error). В качестве аргументов функция принимает объект XMLHttpRequest и строку, описывающую тип запроса. Это событие Ajax.

function (XMLHttpRequest, textStatus) {
  this; // the options for this ajax request
}
contentType Строка По умолчанию: «application/x-www-form-urlencoded»
При отсылке данных на сервер, указывайте тип данных. По умолчанию: «application/x-www-form-urlencoded», что подходит для большинства случаев.
data Объект, Строка
Данные, которые отсылаются на сервер. Если данные не являются строкой, то они конвертируются в строку запроса. Для запросов типа GET данные прикрепляются к URL. Для предотвращения этого, используйте опцию processData. Объект должен состоять из пар ключ/значение. Если значение представляет собой массив, то jQuery упорядочивает значения, принадлежащие одному ключу, например, {foo:["bar1", "bar2"]} превращается в ‘&foo=bar1&foo=bar2′.
dataFilter Функция
Функция, используемая для обработки «сырых» данных ответа XMLHttpRequest. Эта функция предназначена для предварительной обработки ответа. Вам следует возвращать именно обработанные данные. В качестве аргументов функция получает «сырые» данные от сервера и параметр ‘dataType’.

function (data, type) {
  // do something
  // return the sanitized data
  return data;
}
dataType Строка По умолчанию: Intelligent Guess (xml или html)
Тип данных, который Вы ожидаете от сервера. Если не указано никакого типа, то jQuery укажет его самостоятельно (либо responseXML либо responseText), отталкиваясь от типа MIME ответа. Доступные типы (результат, передающийся в качестве первого аргумента Вашей функции success):

  • «xml»: Возвращает документ XML, который может обрабатываться посредством jQuery.
  • «html»: Возвращает текст HTML как plain text; включая теги script.
  • «script»: Расценивает ответ как JavaScript и возвращает его как plain text. Отключает кеширование, если не используется опция «cache». Примечание: удаленные (не в пределах одного домена)  запросы POST будут изменены в GET.
  • «json»: Расценивает ответ как JSON и возвращает как объект JavaScript.
  • «jsonp»: Загружает данные в JSON используя JSONP. При этом добавляется «?callback=?» в конец ссылки для указания функции. (Добавлено в jQuery 1.2)
  • «text»: Строка простого текста (plain text).
error Функция
Функция, которая исполняется всякий раз после неудачного запроса AJAX. Функция принимает три аргумента: объект XMLHttpRequest, строку, описывающую тип случившейся ошибки и необязательный объект «исключения». Возможные значения для второго аргумента (вместе с null):  «timeout», «error», «notmodified» и «parsererror». Это событие Ajax.

function (XMLHttpRequest, textStatus, errorThrown) {
  // typically only one of textStatus or errorThrown
  // will have info
  this; // the options for this ajax request
}
global Логическое значение По умолчанию: true
Определяет, нужно-ли вызывать глобальные обработчики событий AJAX для данного запроса. По умолчанию true. Для предотвращения запуска глобальных обработчиков таких, как ajaxStart или ajaxStop, установите значение данной опции в false. Это может пригодиться для управления различными событиями Ajax.
ifModified Логическое значение По умолчанию: false
Определяет, что запрос является успешным только тогда, когда ответ изменился с момента последнего запроса. Принцип действия основан на проверке заголовка Last-Modified. По умолчанию false, заголовок игнорируется.
jsonp Строка
Переопределяет имя функциив в запросе jsonp. Данное значение подставляется вместо ‘callback’ в строке запроса (например, «myurl?callback=?») в URL, для запросов типа GET, и в данных, для запросов типа POST. Таким образом, {jsonp:’onJsonPLoad’} трансформируется в ‘onJsonPLoad=?’ при передаче на сервер.
password Строка
Пароль, который будет использован для HTTP запроса авторизации.
processData Логическое значение По умолчанию: true
По умолчанию, данные, переданные в параметр data в качестве объекта (с технической точки зрения, что-либо кроме строки), будут обработаны и преобразованы в строку запроса, для соответствия типу данных по умолчанию — «application/x-www-form-urlencoded». Если необходимо отослать документ DOM или другие специфические данные, то установите данную опцию в false.
scriptCharset Строка
Только для запросов типа GET со значениями  jsonp’ или ’script’ в качестве dataType. Заставляет интерпретировать запрос как конкретную кодировку. Необходимо для нахождения различий в локальных и удаленных данных.
success Функция
Функция, которая исполняется всякий раз после удачного завершения запроса AJAX. Функция принимает два аргумента: данные от сервера, отформатированные в соответствие с параметром ‘dataType’, и строку, описывающую текущий статус. Это событие Ajax.

function (data, textStatus) {
  // data could be xmlDoc, jsonObj, html, text, etc...
  this; // the options for this ajax request
}
timeout Число
Устанавливает локальное время ожидания для запроса (в миллисекундах). Данная опция переназначает глобальное время ожидания, установленное при помощи $.ajaxSetup. Например, можно пользоваться этим методом для того, чтобы назначить определенному запросу более длительное время ожидания.
type Строка По умолчанию: «GET»
Тип запроса (»POST» или «GET»), по умолчанию «GET». Примечание: другие методы такие, как PUT и DELETE, также можно указывать здесь, но они поддерживаются не всеми браузерами.
url Строка По умолчанию: текущая страница
URL к запросу. Это ДОЛЖНА быть строка (например, document.location.href) а не локальный объект (например, document.location).
username Строка
Имя пользователя, которое будет использовано для HTTP запроса авторизации.
xhr Функция
Функция для создания объекта XMLHttpRequest. Если доступно, то создается ActiveXObject (IE), в ином случае XMLHttpRequest. Можно создать свою собственную усовершенствованную реализацию объекта XMLHttpRequest. Это недоступно в jQuery версии 1.2.6 и более ранних.
Примеры:

Загружает и исполняет скрипт JavaScript.
$.ajax({
  type: "GET",
  url: "test.js",
  dataType: "script"
});
Загружает некоторые данные на сервер и оповещает пользователя по окончанию операции.
 $.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });
Получает последнюю версию страницы HTML.
$.ajax({
  url: "test.html",
  cache: false,
  success: function(html){
    $("#results").append(html);
  }
});
Синхронно загружает данные. Блокирует браузер на время выполнения запроса.
 var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;
Отсылает документ XML в качестве данных на сервер. Автоматическое преобразование данных запрещено путем установки опции processData в false.
 var xmlDocument = [create xml document];
 $.ajax({
   url: "page.php",
   processData: false,
   data: xmlDocument,
   success: handleResponse
 });
Посылает идентификатор в качестве данных на сервер, сохраняет данные и оповещает пользователя по окончанию операции.
 bodyContent = $.ajax({
      url: "script.php",
      global: false,
      type: "POST",
      data: ({id : this.getAttribute('id')}),
      dataType: "html",
      success: function(msg){
         alert(msg);
      }
   }
).responseText;
Name Type