Синтаксис и описание:
Возвращаемое значение: Экземпляр объекта XHR (XMLHttpRequest).
Параметры:
async – (boolean - логическое значение) По умолчанию имеет значение true, и тогда все запросы выполняются асинхронно (На то он и Ajax, чтобы операции выполнялись параллельно). Если установить зхначение false, что крайне нежелательно, то запрос будет выполняеться как синхронный (Другие действия браузера могут блокироваться на время, пока выполняется синхронный запрос. Да и вообще браузер может перестать реагировать и отвечать).
beforeSend(XHR ) – (функция) Функция, вызываемая перед отправкой запроса. Она используетсядля установки дополнительных (пользовательских) заголовков или для выполнения других предварительных операций. В качестве единственного аргумента ей передается экземпляр объекта XHR (XMLHttpRequest). Если функция возвращает ложное значение (false), то происходит отмена запроса.
cache – (boolean - логическое значение) Если имеет значение false, то запрашиваемые страницы не кэшируются браузером. (Браузер может выдавать результаты из кэша. Например, когда данные в ответе сервера на Ajax запрос всегда новые, то кеширование мешает). По умолчанию имеет значение true для типов данных text, xml, html, json. Для типов данных "script" и "jsonp" имеет значение по умолчанию false.
complete(XHR, textStatus ) – (функция) Функция, вызываемая по окончании запроса независимо от его успеха или неудачи (а также после функций success и error, если они заданы). Функция получает два аргумента: экземпляр объекта XHR (XMLHttpRequest) и строку, сообщающую о состоянии "success" или "error" (в соответствии с кодом статуса в ответе на запрос).
contentType – (строка) Тип содержимого в запросе (при передаче данных на сервер). По умолчанию имеет значение "application/x-www-form-urlencoded" (подходит для большинства случаев и используется по умолчанию также при отправке форм).
context – (объект) Данный объект станет контекстом (this) для всех функций обратного вызова, связанных с данным Ajax-запросом (например, для функций success или error).
$.ajax({ url: "test.html",
context: document.body,
success: function(){
$(this).addClass("done");
}});data – (строка | объект) Данные, отправляемые c запросом на сервер. Они преобразовываются в строку запроса и по умолчанию обязательно кодируются в URL-подобный вид (За автоматическое кодирование в формат URL отвечает параметр processData).
Строка присоединяется к строке запроса URL, если запрос выполняется методом GET. Если же запрос выполняется методом POST, то данные передаются в теле запроса.
Если данный параметр является объектом в виде набора пар имя_свойства/значение, а значение является массивом, то jQuery сериализует объект в последовательность нескольких значений с одним и тем же ключом.
Например, {Foo: [ "bar1", "bar2"]} станет "&Foo=bar1&Foo=bar2" .
dataFilter(data, type ) – (функция) Функция, которая вызывается в случае успеха запроса и используется для обработки данных, полученных в ответе сервера на запрос. Она возвращает данные, обработанные в соответствии с параметром "dataType", и передает их функции success. Данные типа text и xml передаются без обработки сразу функции success через свойство responseText или responseHTML объекта XMLHttpRequest. Функция dataFilter получает два аргумента:
- data - полученные данные (тело ответа сервера),
- type - тип этих данных (параметр "dataType").
dataType – (строка) Строка, определяющая название типа даных, ожидаемых в ответе сервера. Если тип данных не задан, jQuery сама пытается его определить, ориентируясь на MIME-тип ответа сервера. Допустимые значения:"xml", "html", "script", "json", "jsonp", "text". (Это необходимо для того, чтобы определить метод обработки данных, полученных в ответе на запрос, функцией dataFilter перед тем, как они будут переданы функции обратного вызова success.)
error(XHR, textStatus, errorThrown ) – (функция) Функция , которая вызывается при неудачном запросе (если код статуса в ответе сервера сообщает об ошибке). Функции передаются три аргумента:
- XHR - экземпляр объекта XMLHttpRequest,
- textStatus - строка, описывающая тип ошибки, которая произошла ("timeout", "error", "notmodified" или "parsererror"),
- errorThrown - необязательный параметр – объект-исключение, если таковой имеется (возвращается экземпляром объекта XHR).
global – (boolean - логическое значение) По умолчанию имеет значение true (разрешен вызов глобальных обработчиков событий на различных этапах Ajax-запроса, например, функций ajaxStart или ajaxStop). Значение false устанавливается, чтобы предотвратить их срабатывание. (Используется для управления Ajax-событиями).
ifModified – (boolean - логическое значение) Если установлено значение true, то запрос считается успешным только в том случае, если данные в ответе изменились с момента последнего запроса (jQuery определяет, совпадает ли компонент в кэше браузера с тем, что находится на сервере, путем проверки заголовка "Last-Modified" с датой последней модификации содержимого, а в jQuery 1.4 также проверяется заголовок "Etag" – строка с версией компонента). По умолчанию имеет значение false, т.е. успешность запроса не зависит от заголовков и от изменений в ответе.
jsonp – (строка) Переопределяет имя функции обратного вызова для кроссдоменного запроса jsonp. Заменяет собой ключевое слово callback в части "callback=?" строки GET запроса (добавляемой к URL) или передаваемой в теле запроса при передаче методом POST. По умолчанию jQuery автоматически генерирует уникальное имя для функции обратного вызова.
jsonpCallback – (строка) Определяет имя функции обратного вызова для jsonp-запроса. Это значение будет использоваться вместо случайного имени, автоматически генерируемого библиотекой jQuery. Использование данного параметра позволяет избегать пропусков кэширования браузером GET запросов. Желательно разрешать jQuery генерировать новое имя для каждого нового кроссдоменного запроса на сервер для удобства управления запросами и ответами.
password – (строка) Пароль, который будет использоваться в ответ на требование HTTP авторизации на сервере.
processData – (boolean - логическое значение) По умолчанию имеет значение true, и данные, передаваемые на сервер в параметре data, преобразовываются в строку запроса с типом содержимого "Application / X-WWW-форм-urlencoded" и кодируются. Если такая обработка нежелательна (когда необходимо отправить на сервер другие данные, например DOMDocument или объект xml), то ее можно обойти, установив для данного параметра значение false.
scriptCharset – (строка) При выполнении запросов методом GET и запросов, ориентированных на получение данных типа "jsonp" или "script", указывает кодировку символов запроса (например "UTF-8" или "CP1251"). Полезно при различиях между кодировками на стороне клиента и на серверной стороне.
success(data, textStatus, XHR ) – (функция) Функция, которая вызывается при успешном запросе (если код статуса в ответе на запрос сообщает об успехе). Функции передаются три аргумента:
- data - данные, возвращаемые сервером в ответе, предварительно обработанные функцией dataFilter в соответствии со значением параметра dataType,
- textStatus - строку с кодом статуса, сообщающем об успехе,
- XHR - экземпляр объекта XMLHttpRequest.
timeout – (число) Устанавливает максимальное время ожидания ответа сервера в милисекундах. Имеет приоритет над глобальной установкой предельного времени ожидания через $.AjaxSetup. Если лимит времени ожидания превышен, то выполнение запроса прерывается и вызывается функция обработки ошибок error (если она установлена). Это можно использовать, например, для того, чтобы назначить определенному запросу более длительное время ожидания, чем время, установленное для всех запросов.
traditional – (boolean - логическое значение) Необходимо установить значение true, чтобы использовать традиционную (упрощенную) сериализацию (преобразование) данных при отправке (без рекурсивного преобразования в URL-подобную строку объектов или массивов, которые вложены в другие массивы или объекты).
type – (строка) HTTP-метод передачи данных при выполнении запроса. По умолчанию данные передаются методом GET. Обычно используются GET или POST. Также можно использовать методы PUT и DELETE, но это не рекомендуется, ввиду того, что они поддерживаются не всеми браузерами.
url – (строка) Строка, содержащая URL-адрес, по которому посылается запрос. По умолчанию это текущая страница.
username – (строка) Имя пользователя, которое будет использоваться для HTTP авторизации на сервере.
xhr – (функция) Функция, вызываемая для создания экземпляра объекта XMLHttpRequest. По умолчанию создание объекта XHR реализовано через ActiveXObject в браузере IE, либо через встроенный объект типа XMLHttpRequest в остальных случаях.
options – (объект) Объект в виде набора свойств (пар ключ:"значение"), которые задают параметры для Ajax запроса. Возможных параметров (свойств объекта options) очень много, и обычно в большинстве случаев они используются далеко не все, а только некоторые из них. К тому же, все эти параметры являются необязательными, т.к. значение любого из них может быть установлено по умолчанию с помощью метода $.ajaxSetup() .
Для настройки Ajax-запроса доступны следующие свойства объекта options:
HTTP-метод передачи данных при выполнении запроса. Обычно используются GET или POST . Также можно использовать методы PUT и DELETE , но это не рекомендуется, ввиду того, что они поддерживаются не всеми браузерами.
$.ajax({ //... type: "POST", //... });
$.ajax({ //... url: "/path/to/script", //... });
Данные, отправляемые c запросом на сервер. Они преобразовываются в строку запроса и по умолчанию обязательно кодируются в URL-подобный вид (За автоматическое кодирование в формат URL отвечает параметр ).
Строка присоединяется к строке запроса URL, если запрос выполняется методом GET. Если же запрос выполняется методом POST, то данные передаются в теле запроса.
$.ajax({ //... data: "value1=1&value2=2&value3=3", //... });
Если данный параметр является объектом в виде набора пар имя_свойства/значение, а значение является массивом, то jQuery сериализует объект в последовательность нескольких значений с одним и тем же ключом.
{Foo: [ "bar1", "bar2"]}
&Foo=bar1&Foo=bar2
Флаг выполнения асинхронных запросов.
$.ajax({ //... async: false, //... });
Флаг кэширования ответа.
По умолчанию имеет значение true для типов данных text , xml , html , json . Для типов данных script и jsonp имеет значение по умолчанию false .
Если установлено значение true , то запрос считается успешным только в том случае, если данные в ответе изменились с момента последнего запроса (jQuery определяет, совпадает ли компонент в кэше браузера с тем, что находится на сервере, путем проверки заголовка Last-Modified с датой последней модификации содержимого, а в jQuery 1.4 также проверяется заголовок Etag – строка с версией компонента). По умолчанию имеет значение false , т.е. успешность запроса не зависит от заголовков и от изменений в ответе.
Имя пользователя, которое будет использоваться для HTTP авторизации на сервере.
Данные, передаваемые на сервер в параметре , преобразовываются в строку запроса с типом содержимого Application / X-WWW-форм-urlencoded и кодируются. Если такая обработка нежелательна (когда необходимо отправить на сервер другие данные, например DOMDocument или объект xml), то ее можно обойти, установив для данного параметра значение false .
При выполнении запросов методом GET и запросов, ориентированных на получение данных типа jsonp или script , указывает кодировку символов запроса (например UTF-8 или CP1251). Полезно при различиях между кодировками на стороне клиента и на серверной стороне.
Устанавливает максимальное время ожидания ответа сервера в милисекундах. Имеет приоритет над глобальной установкой предельного времени ожидания через $.AjaxSetup . Если лимит времени ожидания превышен, то выполнение запроса прерывается и вызывается функция обработки ошибок error (если она установлена).
| error | XHR, textStatus, errorThrown | Срабатывает при неудачном запросе. Функции передаются три аргумента: textStatus - строка, описывающая тип ошибки, которая произошла (timeout , error , notmodified или parsererror) errorThrown - необязательный параметр, объект-исключение, если таковой имеется (возвращается экземпляром объекта XHR) $.ajax({ //... error: function() { alert("Ошибка!"); }, //... }); |
| success | data, textStatus, XHR | Срабатывает при успешном запросе. Функции передаются три аргумента: data - данные, возвращаемые сервером в ответе, предварительно обработанные функцией dataFilter в соответствии со значением параметра textStatus - строку с кодом статуса, сообщающем об успехе XHR - экземпляр объекта XMLHttpRequest $.ajax({ //... success: function() { alert("Успех!"); }, //... }); |
| beforeSend | XHR | Срабатывает перед отправкой запроса. В качестве единственного аргумента ей передается экземпляр объекта XHR (XMLHttpRequest). Если функция возвращает false , то происходит отмена запроса. $.ajax({ //... beforeSend: function() { alert("Сработал beforeSend!"); }, //... }); |
| complete | XHR, textStatus | Срабатывает по окончанию запроса независимо от его успеха или неудачи (а также после функций и , если они заданы). Функция получает два аргумента: экземпляр объекта XHR (XMLHttpRequest) и строку, сообщающую о состоянии success или error (в соответствии с кодом статуса в ответе на запрос) |
Подробный пример:
function testAjax(id, pid) {
$.ajax({
type: "POST",
data: "id=" + id + "&pid=" + pid,
url: "/path/to/script/test.php",
success: function(data) {
var obj = $.parseJSON(data); //Преобразование json ответа сервера
if (obj.error == 0) {
alert("Запрос прошел успешно");
} else {
alert(obj.error);
}
}
});
return true;
}
Успешный запрос
Запрос с ошибкой
PHP скрипт (test.php):
Еще один пример, отличается выводом ответа:
function testAjax(id, pid) {
$.ajax({
type: "POST",
data: "id=" + id + "&pid=" + pid,
url: "/path/to/script/test.php",
success: function(data) {
$("#content").html(data);
}
});
return true;
}
Успешный запрос
Запрос с ошибкой
Ответ:
PHP скрипт (test.php):
Больше информации можно посмотреть по адресу: http://api.jquery.com/jquery.ajax/
Последнее обновление: 1.11.2015
Рассмотренные ранее методы get, post, load очень просты в использовании и с лихвой покрывают большинство потребностей разработчиков. Однако иногда возникает необходимость иметь больший контроль над выполнением. И поэтому обращаются к методу ajax , который позволяет осуществлять запросы на более низком уровне. Другие же методы по сути используют метод ajax.
Например, используем метод ajax для загрузки разметки html в элемент на странице:
Загрузить $(function(){ $("button").click(function(){ $.ajax("ajax.php", {success: function(data){ $("#result").html(data); } }); }); });
Ресурс ajax.php на стороне сервера пусть возвращает некоторую разметку html в ответ.
В данном случае мы указываем два параметра: адрес запроса и параметр success , который принимает функцию, обрабатывающую ответ от сервера.
По сути то же самое мы могли бы сделать и с помощью метода load, и с помощью метода get. Но многообразие параметров метода ajax позволяет более детально настроить запрос.
На выходе метод ajax, как и другие методы возвращает объект jqXHR , связанный с текущем запросом.
Метод ajax может принимать следующие формы: ajax(url, options) и ajax(options) . Параметр options представляет объект javascript, в котором мы указываем необходимые нам опции запроса в виде пар ключ-значение. Так, в вышеприведенном примере мы использовали опцию success . Далее приведены некоторые из опций, которые мы можем использовать в методе ajax:
url: адрес ресурса, к которому идет запрос. Тип данных: строка
async: указывает, является ли запрос асинхронным. Тип данных: булевое значение. По умолчанию имеет значение true. Если же значение равно false, то запрос передается как синхронный
dataType: тип получаемых от сервера данных. Тип данных: строка.
Может принимать следующие значения: html , xml , json , jsonp , text , script
cache: указывает, будет ли ответ кэшироваться веб-браузером. Тип данных: булевое значение. По умолчанию true.
И false по умолчанию для запросов, у которых параметр dataType имеет значение "script" или "jsonp"
context: элемент, представляющий контекст данных для функций обратного вызова. Например:
$.ajax({ url: "ajax.php", context: document.body });
type: указывает тип запроса. Как правило, "GET" или "POST". Тип данных: строка. По умолчанию "GET"
data: данные, отправляемые вместе с запросом на сервер. Тип данных: строка или объект javascript
timeout: время в миллисекундах ожидания ответа на запрос
global: указывает, можно ли вызывать глобальные события ajax. Тип данных: булевое значение. По умолчанию true, то есть вызов глобальных событий разрешен
isModified: позволяет проверять заголовок ответа Last-Modified . Тип данных: булевое значение. По умолчанию false, то есть данный заголовок не проверяется. Если же имеет значение true, заголовок проверяется. А данные запрашиваются, если с момента последнего запроса данных они были изменены. Если же данные не были изменены, то в обработчике функции success параметр data будет иметь значение undefined
password: пароль, необходимый, если при запросе требуется аутентификация. Тип данных: строка
username: имя пользователя или логин, необходимый, если при запросе требуется аутентификация. Тип данных: строка
dataFilter: функция фильтрации "сырых" данных. Она принимает два параметра: function(data, type) . Параметр data представляет пришедшие от сервера данные, а type - тип данных. На выходе функция должна возвратить отфильтрованные данные
success: функция, вызываемая, если запрос завершится успехом. Она может принимать три параметра: function(data, textStatus, jqXHR) . Параметр data представляет пришедшие от сервера данные. Параметр textStatus передает код статуса. Третий параметр представляет связанный с запросом объект jqXHR
error: функция, которая вызывается, если код статуса сообщит об ошибке. Она может принимать три параметра: function(jqXHR, textStatus, errorThrown)
complete: функция, которая вызывается после завершения запроса. Она может принимать два параметра: function(jqXHR, textStatus) . Параметр textStatus сигнализирует нам о том, был ли успешным запрос или завершился с ошибкой.
beforeSend: функция, срабатывающая перед отправкой запроса. Она принимает два параметра: function(jqXHR, settings) . Параметр settings содержит объект, хранящий некоторые дополнительные настройки запроса. Если эта функция возвращает false , то запрос отменяется
xhr: функция для создания объекта XMLHttpRequest
Конечно, все параметры не обязательно употреблять, главное надо учитывать, что комбинируя наборы параметров, мы можем сделать ajax-запрос более отвечающим нашим требованиям.
Сериализация данных формы и запросы POSTВыше мы уже посмотрели на отправку запросов GET, теперь посмотрим, как с помощью метода ajax мы можем отправлять POST-запросы.
На строне сервера пусть у нас будет простейшая обработка авторизационных данных:
На веб-странице создадим форму и установим параметры для метода ajax:
$(function(){
$("#loginForm").submit(function(event) {
event.preventDefault();
$.ajax({
url: $("#loginForm").attr("action"),
data: $("#loginForm").serialize(),
type: "POST",
success: function(data){
$("#result").html(data);
}
});
});
});
Returns: jqXHR
Выполняет асинхронный HTTP (Ajax) запрос
- version added: 1.5
jQuery.ajax(url [, settings])
url
Тип : Строка
URL адрес, на который будет отправлен Ajax запросsettings
Тип : Объект
Набор параметров вида ключ / значение, которые настраивают запрос Ajax. Все настройки опциональны. По умолчанию настройки берутся из . Ниже приведен полный список всех настроек. - version added: 1.0
jQuery.ajax(settings)
settings
Тип : Объект
Набор параметров вида ключ / значение, которые настраивают запрос Ajax. Все настройки опциональны. По умолчанию настройки берутся из .
| Настройка | Тип данных |
|
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 = ; var xmlRequest = $.ajax({ url: "page.php", processData: false, data: xmlDocument }); xmlRequest.done(handleResponse);
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 описывается на уровне возможностей и примеров. Рассмотрены особенности асинхронного взаимодействия и примеры использования, но с минимумом технических деталей.
Надеюсь, она будет полезна для понимания, что такое AJAX и с чем его едят.
Что такое AJAX ? Пример реализации.AJAX, или, более длинно, A synchronous J avascript A nd X ml - технология для взаимодействия с сервером без перезагрузки страниц.
За счет этого уменьшается время отклика и веб-приложение по интерактивности больше напоминает десктоп.
Технология AJAX, как указывает первая буква A в ее названии - асинхронна, т.е браузер, отослав запрос, может делать что угодно, например, показать сообщение
об ожидании ответа, прокручивать страницу, и т.п.
Вот код кнопки в примере выше:
При нажатии она вызывает функцию vote , которая отправляет запрос на сервер, ждет ответа, а затем показывает сообщение об этом в div "е под кнопкой:
Здесь будет ответ сервера
Для обмена данными с сервером используется специальный объект XmlHttpRequest , который умеет отправлять запрос и получать ответ с сервера. Кроссбраузерно создать такой объект можно, например, так:
Function getXmlHttp(){ var xmlhttp; try { xmlhttp = new ActiveXObject("Msxml2.XMLHTTP"); } catch (e) { try { xmlhttp = new ActiveXObject("Microsoft.XMLHTTP"); } catch (E) { xmlhttp = false; } } if (!xmlhttp && typeof XMLHttpRequest!="undefined") { xmlhttp = new XMLHttpRequest(); } return xmlhttp; }
Более подробно о деталях реализации AJAX с использованием XmlHttpRequest и других транспортов можно почитать в разделе про общение с сервером .
Здесь мы не будем на этом останавливаться и перейдем сразу к функции vote:
// javascript-код голосования из примера function vote() { // (1) создать объект для запроса к серверу var req = getXmlHttp() // (2) // span рядом с кнопкой // в нем будем отображать ход выполнения var statusElem = document.getElementById("vote_status") req.onreadystatechange = function() { // onreadystatechange активируется при получении ответа сервера if (req.readyState == 4) { // если запрос закончил выполняться statusElem.innerHTML = req.statusText // показать статус (Not Found, ОК..) if(req.status == 200) { // если статус 200 (ОК) - выдать ответ пользователю alert("Ответ сервера: "+req.responseText); } // тут можно добавить else с обработкой ошибок запроса } } // (3) задать адрес подключения req.open("GET", "/ajax_intro/vote.php", true); // объект запроса подготовлен: указан адрес и создана функция onreadystatechange // для обработки ответа сервера // (4) req.send(null); // отослать запрос // (5) statusElem.innerHTML = "Ожидаю ответа сервера..." }
Поток выполнения, использованный vote, довольно типичен и выглядит так:
Серверный обработчик, к которому обращен AJAX-запрос (в примере это vote.php) по сути ничем не отличается от обычной страницы. AJAX-запрос, отправляемый XmlHttpRequest , ничем не отличается от обычного запроса.
Просто текст, который возвращает сервер, не показывается как HTML, а читается и обрабатывается функцией onreadystatechange .
Смысл AJAX - в интеграции технологийТехнология AJAX использует комбинацию:
- (X)HTML, CSS для подачи и стилизации информации
- DOM-модель, операции над которой производятся javascript на стороне клиента, чтобы обеспечить динамическое отображение и взаимодействие с информацией
- XMLHttpRequest для асинхронного обмена данными с веб-сервером. В некоторых AJAX-фреймворках и в некоторых ситуациях, вместо XMLHttpRequest используется IFrame, SCRIPT-тег или другой аналогичный транспорт.
- JSON часто используется для обмена данными, однако любой формат подойдет, включая форматированный HTML, текст, XML и даже какой-нибудь EBML
Типичное AJAX-приложение состоит как минимум из двух частей.
Первая выполняется в браузере и написана, как правило, на JavaScript, а вторая - находится на сервере и написана, например, на Ruby, Java или PHP .
Между этими двумя частями происходит обмен данными через XMLHttpRequest(или другой транспорт).
Что я могу сделать с помощью AJAX ?Смысл AJAX - в интерактивности и быстром времени отклика.
Небольшие элементы управленияВ первую очередь AJAX полезен для небольших элементов, связанных с элементарными действиями: добавить в корзину, подписаться, и т.п.
 |
 |
 |
Например, дерево, узлы которого подгружаются по мере раскрытия.
На момент его появления он явился единственным открытым почтовым сервисом, использующим AJAX для следующих фич.
- Проверка ошибок ввода формы ДО сабмита
На сервер передается имя пользователя, результат проверки возвращается на страницу.
- "Мгновенная" загрузка
Браузер обращается к серверу только за данными, а не обновляет весь громоздкий интерфейс
- Автоматическая "доставка" писем в открытую папку
Время от времени отправляется запрос на сервер и, если пришли новые письма, они появляются в браузере.
- Автодополнение
Достаточно ввести первые буквы имени адресата, и остальные дополняются автоматически, как в десктоп-приложениях.
Результат: обширная популярность, высокий спрос на account"ы с момента открытия.
Синхронная модель VS Асинхронная модельВ обычном программировании все операции носят синхронный характер, т.е выполняются одна за другой.
Условно говоря, мы действуем так:
При асинхронном подходе мы:
Т.е, в синхронном случае удочка постоянно приковывает наше внимание. Ловля рыбы - последовательный процесс.
В асинхронном варианте - мы сначала задали программу, что делать при клеве, а затем опустили удочку ловить и занялись другими делами.
Например, поставили еще 5 таких удочек.
Асинхронное программирование сложнее, чем синхронное, и поначалу непривычно, т.к в нем заранее
задается то, что сработает после
.
Т.е, программу "что делать, когда клюнет" нужно задать до того, как клюнуло, и вообще неизвестно, есть ли в водоеме рыба.
Существуют приемы, облегчающие асинхронное программирование, например, отложенный объект Deferred (Twisted,Dojo,Mochikit), но об этом - в отдельной статье.
Синхронная и асинхронная модель в AJAXВернемся к нашим баранам: браузеру, серверу и, скажем, базе данных.
В синхронной модели браузер отправляет запрос на сервер и висит, ждет, пока тот совершит всю необходимую работу. Сервер выполняет запросы к базе данных, заворачивает ответ в необходимый формат и выводит его. Браузер. получив ответ, вызывает функцию показа.
Все процессы выполняются последовательно, один за другим.
Сетевые задержки включены во время ожидания, обозначенное на схеме серым цветом.
Пользователь не может заниматься чем-то другим на этой же странице, пока происходит синхронный обмен данными.
В асинхронной модели запрос отсылается ("удочка поставлена"), и можно заняться чем-то другим. Когда запрос выполнился ("клюнуло") - запускается заранее
подготовленная программистом функция ("подтянуть спиннинг") показа сообщения сервера.
Здесь сервер сразу же уведомляет браузер о том, что запрос принят в обработку и освобождает его для дальнейшей работы. Когда ответ будет готов - сервер перешлет его, и на браузере будет вызвана соответствующая функция показа, но пока этот ответ формируется и пересылается - браузер свободен.
Пользователь может написать комментарии, заполнить и отослать форму и т.п: Могут производиться новые асинхронные запросы.
Асинхронная модель характеризуется почти мгновенной реакцией на действия пользователя, так что создается впечатление удобного и быстрого приложения.
Из-за такого разрыва между действием и реальным результатом приложение становится гораздо более чувствительно к ошибкам.
Особенно в случае нескольких одновременных асинхронных запросов, нужно заботиться об очередности выполнения и ответа (race-conditions) и, в случае ошибки, оставлять приложение в целостном (consistent) состоянии.
Особенности асинхронной модели- Сложность в реализации
- Недостаточные возможности браузера (javascript)
- Асинхронная модель сложнее для отладки
- Race conditions
- Неопределена последовательность выполнения
- Можно делать много одновременных задач ("удочек"), но задача, начатая первой, может окончиться последней.
- Реакция тут же, но неизвестно, какой будет результат. Усложнена обработка ошибок
- Ошибок коммуникации - разрыв связи, и т.п.
- Пользовательских ошибок - например, не хватило привилегий
- Контроль целостности (bugproof)
- Например, редактор отправил асинхронный запрос на удаление ветки дерева. Добавление в нее нужно отключить, пока не придет ответ сервера. Если вдруг не хватило привилегий, то операция не удалась.
- Интерактивность
- Быстрый интерфейс
Плюсов всего два, зато какие! Овчинка стоит выделки.
Асинхронный drag"n"drop.Иногда для асинхронных операций необходимо делать различные "финты ушами". Например, хочется сделать drag"n"drop в дереве, т.е перетаскивать статьи из одного раздела в другой мышкой, и чтобы они на сервере в базе данных меняли родителя.
Drag"n"drop - это "взял мышей объект - положил куда надо - готово". Но в асинхронной модели не может быть все прям сразу "готово".
Надо проверить привилегии на сервере, проверить, существует ли еще объект, вдруг его удалил другой пользователь.
Надо как-то показать, что процесс пошел, но результат "ща будет..". А как? В асинхронной модели указатель мыши не может просто так зависнуть над объектом, превратившись в часики.
В таком случае применяют либо синхронные запросы к серверу - и тогда все действительно подвисает, либо оригинальный выход - положить объект, как будто он перенесен, и проинформировать анимированной иконкой об ожидании ответа.
Если ответ отрицателен - обработчик ответа переносит объект обратно.
В примере с drag"n"drop также затронута проблема "stale context" - устаревшего контекста.
Веб - многопользовательская среда. Если для навигации используется,
скажем, дерево статей, то над ним работают много человек. Один из них может удалить ветку дерева, над которой работает другой: конфликт.
Как правило, для преодоления таких казусов используются следующие средства:
Политика редактированияЭто когда все знают кто чего делает и на уровне деления полномочий и личного общения такие удаления согласовывают. Вариант заведомо небезопасный, но обычно работающий.
Локинг и/или версионный контрольЛокинг - блокирование редактируемых документов.
Версионный контроль - каждый новый документ становится версией, так что изменения никогда не теряются. Версионность влечет за собой конфликты, когда Петя начал редактировать документ раньше Васи, а сохранил - позже. При этом в последней версии изменения Васи оказались потеряны, хотя предпоследняя (Васина) версия в системе обязательно есть.
Более подробно о локинге и версионности можно почитать, например, в документации к системе версионного контроля Subversion .
Автообновление контекстаПроблема устаревшего контента может быть на 99% решена при помощи мгновенного автообновления.
Браузер держит постоянное соединение с сервером (или делает время от времени корректирующие запросы) - и нужные изменения отсылаются по этому каналу.
Например, в раскрытую ветку дерева иногда подгружаются новые статьи, в открытый почтовый интерфейс - новые письма.
Вообще, проблема устаревшего контекста напрямую относится к задаче целостности данных. За конечную проверку целостности, как и при валидации форм, в любом случае несет ответственность сервер.
