jQuery.ajax()

Returns: jqXHR

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

  • version added: 1.5jQuery.ajax( url [, settings] )

    url
    Тип: Строка
    URL адрес, на который будет отправлен Ajax запрос

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

  • version added: 1.0jQuery.ajax( settings )

    settings
    Тип: Объект
    Набор параметров вида ключ / значение, которые настраивают запрос Ajax. Все настройки опциональны. По умолчанию настройки берутся из $.ajaxSetup().

settings:

Настройка Тип данных
accepts

По умолчанию: зависит от типа данных

При выполнении ajax-запроса, в заголовках (header) указываются допустимые типы содержимого, ожидаемого от сервера. Значения этих типов будут взяты из параметра accepts. Если требуется его изменить, лучше сделать это с помощью метода $.ajaxSetup().

объект
async

По умолчанию: true

По умолчанию, все запросы отсылаются асинхронно (значение данного параметра true). Если же вам нужны синхронные запросы, то параметру async выставите значение false. Кроссдоменные запросы и dataType: "jsonp" не выполняются в синхронном режиме. Учтите, синхронные запросы могут на время выполнения запроса заблокировать браузер.

логический
beforeSend(jqXHR jqXHR, объект settings)

Функция, которая будет вызвана непосредственно перед отправкой ajax-запроса на сервер. Она может быть использована для модификации jqXHR-объекта (в ранних версиях, до jQuery 1.4.x использовался XMLHttpRequest). Так же может использоваться для изменения заголовков (headers) и т.д. Объект типа jqXHR и объект настроек, передаются в качестве аргументов. Возврат значения false в функции beforeSend вызовет отмену ajax-запроса. Начиная с jQuery 1.5, beforeSend сработает вне зависимости от типа запроса.

функция
cache

По умолчанию: true, false для типов данных 'script' and 'jsonp'

Если false, запрашиваемая страница не будет кэшироваться браузером.

логический
complete(jqXHR jqXHR, строка textStatus)

Функция, которая будет вызвана после завершения ajax запроса (срабатывает после функций-обработчиков success и error). Функция принимает два аргумента: объект типа jqXHR (в ранних версиях, до jQuery 1.4.x использовался XMLHttpRequest) и строку, характеризующую статус запроса ("success", "notmodified", "error", "timeout", "abort", или "parsererror"). Начиная с jQuery 1.5, complete может принимать массив функций.

функция или массив
contents

Параметр задается в формате {строка:регулярное выражение} и определяет, как jQuery будет разбирать ответ от сервера, в зависимости от его типа. (добалено в версии 1.5) 

объект
contentType

По умолчанию: 'application/x-www-form-urlencoded; charset=UTF-8'

При отправке Ajax запроса, данные передаются в том виде, в котором указаны в данном параметре. По умолчанию используется 'application/x-www-form-urlencoded; charset=UTF-8'. Если задать значение самим, то оно будет отправлено на сервер. Если кодировка не указана, то по умолчанию будет использоваться кодировка выставленная на сервере.

строка
context

Объект, который станет контекстом после выполнения запроса (передаваемое значение в переменную this). Например, если указать в качестве контекста DOM-элемент, то все обработчики ajax-запроса тоже будут выполняться в контексте данного DOM-элемента. В данном примере ключевое слово this будет содержать document.body:

$.ajax({
  url: "test.html",
  context: document.body,
  success: function(){
    $(this).addClass("done");
  }
});    
    
объект
converters

По умолчанию: {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML}

Определяет, с помощью каких функций будет производиться конвертация значений из одного типа, в другой. (добалено в версии 1.5)

объект
crossDomain

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

Если вы хотите, чтобы выполнить кросс-доменный запрос (например, JSONP) на том же домене, выставите true в настройке crossDomain. Это позволяет, например, сделать серверные перенаправление на другой домен. (добалено в версии 1.5)

логический
data

Данные, которые будут переданы на сервер. Если данные не являются строкой, то они конвертируются в строку запроса. Для запросов типа GET данные прикрепляются к URL. Объект должен состоять из пар ключ/значение. Если в значении массив, то jQuery упорядочивает значения в зависимости от настройки traditional. По умолчанию, например, {foo:["bar1", "bar2"]} превращается в &foo=bar1&foo=bar2.

объект или строка
dataFilter(строка data, строка type)

Функция, с помощью которой будут обрабатываться сырые данные типа XMLHttpRequest, полученные от сервера. Ваша функция должна играть роль фильтра и возвращать очищенную строку. В функцию передаются два параметра: полученные данные и значение параметра dataType.

функция
dataType

По умолчанию: автоматически определяемая строка (xml, json, script, или html)

Тип данных, ожидаемых от сервера. Если опция не определена, то jQuery попытается определить тип, основываясь на MIME-типе ответа. 

строка
error(jqXHR jqXHR, строка textStatus, строка errorThrown)

Функция, исполняемая в случае неудачного запроса. Принимает 3 аргумента: объект jqXHR (в прошлом XMLHttpRequest), строку с описанием ошибки, а так же строку исключения, если оно было выбрашено. Второй аргумент может содержать следующие значения: null, "timeout", "error", "abort", и "parsererror". В случае если происходит HTTP ошибка, то в третий аргумент будет записан её текстовой статус.  К примеру, "Not Found" или "Internal Server Error.". Начиная с jQuery 1.5, вместо одной функции, этот параметр может принимать массив функций. Событие error не происходит при dataType равному script или JSONP.

функция или массив
global

По умолчанию: true.

Вызывать или нет глобальные обработчики событий Ajax для этого запроса (например ajaxStart или ajaxStop).

логический
headers

По умолчанию: {}

Здесь можно указать дополнительные заголовки запроса (header). Значения этой настройки будут введены до вызова функции beforeSend, в которой могут быть внесены окончательные изменения в заголовки. (добалено в версии 1.5)

объект
ifModified

По умолчанию: false

Запрос будет считаться успешным только в случае, если данные ответа изменились со времени последнего запроса. Проверка осуществляется по заголовку Last-Modified. По умолчани, данная опция отключена. В jQuery 1.4 так же проверяется значение 'etag', для отслеживания факта изменения данных.

логический
isLocal

По умолчанию: в зависимости от текущей локации

Параметр определяет, запущена ли веб-страница локально (например по протоколу file, *-extension, и widget) или нет (например по протоколу http). Данную настройку лучше менять с помощью метода $.ajaxSetup()(добалено в версии 1.5)

логический
jsonp

Определяет имя параметра, который добавляется в url JSONP-запроса(по умолчанию, используется "callback"). К примеру настройка {jsonp:'onJSONPLoad'} преобразуется в часть url строки 'onJSONPLoad=?'. Начиная с версии 1.5, указание в этом параметре false предотвращает добавление в url дополнительного параметра. В этом случае, необходимо установить значение настройки jsonpCallback. Например так: {jsonp:false, jsonpCallback:"callbackName"}.

строка
jsonpCallback

Функция, которая будет вызвана при ответе сервера на запрос типа JSONP. По умолчанию, jQuery генерирует произвольное уникальное имя этой функции, что более предпочтительно. Если вы хотите использовать кэширование GET запросов, то вписывайте название функции сами. Начиная с версии 1.5 можно указать функцию, для того, чтобы обработать ответ сервера самостоятельно.

строка или функция
mimeType

Здесь можно указать тип данных,  в котором ожидается ответ от сервера вместо XHR. (добалено в версии 1.5.1)

строка
password

Пароль, который будет использоваться в ответ на запрос проверки подлинности доступа HTTP (если это требуется)

строка
username

Имя пользователя, которое будет использоваться в ответ на запрос проверки подлинности доступа HTTP (если это требуется)

строка
processData

По умолчанию: true;

По умолчанию передаваемые на сервер данные преобразуются из объекта в строку запроса и отправляются как "application/x-www-form-urlencoded". Если вам необходимо отправить DOM-документ или иные данные, которые нельзя подвергать конвертированию установите опцию processData в false.

логический
scriptCharset

Применяется только для Ajax GET-запросов типов 'JSONP' и 'script '. Если сервер на стороннем домене использует кодировку, отличную от вашей, необходимо указать кодировку стороннего сервера.

строка
statusCode

По умолчанию: {}

Набор пар, в котором кодам выполнения запроса сопоставляются функции, которые при этом будет вызваны. Например, для кода 404 (страницы не существуют) можно сделать вывод сообщения на экран:

$.ajax({
  statusCode:{
    404:function(){
      alert('Страница не найдена');
    }
  }
});    

Если запрос прошёл успешно, то в качестве параметра, анонимная функция будет принимать те же параметры, что и при success. При ошибке, будет принимать то же самое что и при функции-обработчике error. (добалено в версии 1.5)

объект
success(объект data, строка textStatus, объект jqXHR)

Функция, которая будет вызвана в случае успешного завершения запроса. Принимает 3 аргумента - данные (data), присланные сервером и прошедшие предварительную обработку; строка со статусом выполнения (textStatus); объект jqXHR (в версиях до 1.5 вместо jqXHR используетсяXMLHttpRequest). С версии jQuery 1.5, вместо одной функции, этот параметр может принимать массив функций.

функция или массив
timeout

Время ожидания ответа от сервера в миллисекундах. Переписывает глобальную настройку этого же параметра в $.ajaxSetup(). Если это время будет превышено, запрос будет завершен с ошибкой и произойдет событие error, которое будет иметь статус "timeout".

число
traditional

По умолчанию: false

Установите значение этого параметра в true, для того, чтобы использовать традиционный стиль сериализации.

логический
type

По умолчанию: GET

Определяет тип запроса GET или POST. Можно также использовать другие HTTP-запросы (такие как PUT или DELETE), но следует помнить, что они поддерживаются не всеми бразерами.

строка
url

По умолчанию: текущая страница.

Страница, накоторую будет отправлен запрос.

строка
xhr

По умолчанию ActiveXObject в IE, XMLHttpRequest в других браузерах.

Callback-функция, для создания объекта XMLHttpRequest. Создав свою функцию, вы берёте на себя всю ответственность за формирование объекта.

function
xhrFields

Объект вида {имя:значене} для изменения значений соответствующих полей объекта XMLHttpRequest.

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

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

map

 

Примеры

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

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

Получить последнюю версию HTML страницы

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

Передаём в качестве данных XML документ. Отключаем автоматическую конвертацию данных в обычную строку, задав настройке processData значение false:

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

Отправить на сервер значение ID. Сохранить данные, оповестить пользователя. Если запрос не прошёл, сообщить об этом пользователю.

var menuId = $("ul.nav").first().attr("id");
var request = $.ajax({
  url: "script.php",
  type: "POST",
  data: {id : menuId},
  dataType: "html"
});
 
request.done(function(msg) {
  $("#log").html( msg );
});
 
request.fail(function(jqXHR, textStatus) {
  alert( "Request failed: " + textStatus );
});

Загрузить и выполнить файл JavaScript:

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

Связанные уроки:

  • Создание простого AJAX сайта с помощью jQuery

    В сегодняшнем уроке мы создадим простой сайт с помощью jQuery.

  • Что нового в jQuery 1.5?

    Совсем недавно, как и было обещано, группа разработчиков библиотеки jQuery выпустила новую версию своего продукта. Я попытаюсь вам рассказать о фитчах, которые вошли в свежий релиз.

^ Наверх ^