Этот параметр определяет функцию, которая должна вызываться по завершении Ajax-запроса. Каждый Ajax-запрос завершается либо успехом и вызывает функцию success, либо неудачей и вызывает функцию error. Библиотека jQuery вызывает функцию complete после вызова функции success или error. В первом аргументе функции complete передается объект
XMLHttpRequest
, а во втором -код состояния.
19.6.3.3. Редко используемые параметры и обработчики
Следующие параметры используются довольно редко. Некоторые из них являются параметрами, которые вам едва ли придется
устанавливать, а другие определяют обработчики для тех, кому потребуется изменить порядок обработки Ajax-запросов, используемый в библиотеке jQuery по умолчанию.
async
Запросы HTTP по своей природе являются асинхронными. Однако объект
XMLHttpRequest
дает возможность заблокировать выполнение сценария до получения ответа. Если присвоить этому параметру значение false, библиотека jQuery будет блокировать работу сценария. Данный параметр не влияет на значение, возвращаемое функцией
jQuery.ajax:
она всегда возвращает объект
XMLHttpRequest
, если он используется. При выполнении синхронных запросов вы можете самостоятельно извлекать ответ сервера и код состояния HTTP из объекта
XMLHttpRequest
или определить функцию обратного вызова complete (как в случае асинхронных запросов), чтобы получить разобранный ответ и код состояния jQuery.
dataFilter
Этот параметр определяет функцию фильтрации или предварительной обработки данных, возвращаемых сервером. В первом аргументе ей будут передаваться необработанные данные, полученные от сервера (либо в виде строки, либо в виде объекта
Document
, при запросе XML-документа), а во втором аргументе - значение параметра
dataType
. Эта функция должна возвращать значение, которое будет использоваться вместо ответа сервера. Обратите внимание, что функция
dataFilter
вызывается перед разбором данных в формате JSON или перед выполнением сценария. Кроме того, отметьте, что
dataFilter
не вызывается при выполнении междоменных запросов данных типов «script» и «jsonp».
jsonp
Когда параметр
dataType
имеет значение «jsonp», значение параметра
url
или
data
обычно включает параметр строки запроса вида «jsonp=?». Если библиотека jQuery не обнаружит этот параметр в URL-адресе или в данных, она вставит его, используя значение параметра jsonp в качестве имени параметра в строке запроса. По умолчанию параметр
jsonp
имеет значение «callback». Присвойте ему другое значение, если сервер, поддерживающий обмен данными в формате JSONP, ожидает получить другое имя параметра в строке запроса и вы явно не указываете это имя в строке URL или в данных. Подробнее о формате JSONP рассказывается в разделе 18.2.
jsonpCallback
Для запросов с параметром
dataType
, имеющим значение «jsonp» (или «json», когда URL-адрес включает параметр строки запроса, такой как «jsonp=?»), библиотека jQuery будет изменять строку URL, подставляя вместо знака вопроса имя функции-обертки, которой сервер будет передавать данные. Обычно библиотека jQuery синтезирует уникальное имя функции, опираясь на текущее время. Присвойте этому параметру свое значение, если вам потребуется явно указать собственную функцию. Но имейте в виду, что в этом случае библиотека jQuery
не будет вызывать функции обратного вызова success и complete и не будет возбуждать обычные события.
processData
Когда значением параметра
data
является объект (или объект передается во втором аргументе функции
jQuery.get
и родственным ей функциям), библиотека jQuery обычно преобразует этот объект в строку в формате «application/x-www-form-urlencoded» (как описывается во врезке в разделе 19.6.2.2). Если потребуется предотвратить это преобразование (например, чтобы передать объект
Document
в теле POST-запроса), присвойте этому параметру значение false.
scriptCharset
Для междоменных запросов данных типов «script» и «jsonp», при выполнения которых используется элемент
<script>,
этот параметр определяет значение атрибута
charset
элемента. Он никак не влияет на обычные запросы, выполняемые с помощью объекта
XMLHttpRequest
.
traditional
В библиотеке jQuery версии 1.4 несколько изменился способ сериализации объектов с данными в строки формата «application/х-www-form-urlencoded» (подробности приводятся во врезке в разделе 19.6.2.2). Присвойте этому параметру значение true, если необходимо, чтобы библиотека jQuery использовала прежний порядок.
username, password
Если для выполнения запроса необходимо выполнить процедуру аутентификации пользователя, укажите имя пользователя и пароль в этих двух параметрах.
xhr
Этот параметр определяет фабричную функцию, создающую объект
XMLHttpRequest
. Она вызывается без аргументов и должна возвращать объект, реализующий прикладной программный интерфейс объекта
XMLHttpRequest
. Этот весьма низкоуровневый обработчик позволяет создавать собственные обертки вокруг объекта
XMLHttpRequest
и добавлять новые особенности или расширять его методы.
19.6.4. События в архитектуре Ajax
В разделе 19.6.3.2 говорилось, что функция
jQuery.ajax
имеет четыре параметра, определяющие функции обратного вызова:
befоreSend
,
success
,
error
и
complete
. Помимо вызова этих функций, функции поддержки архитектуры Ajax в библиотеке jQuery также возбуждают собственные события на каждой стадии выполнения запроса. В следующей таблице перечислены параметры, определяющие функции обратного вызова, и соответствующие им события:
Зарегистрировать обработчики этих событий можно с помощью метода
bind
(раздел 19.4.4), используя строку с типом события из второй колонки, или с помощью методов из третьей колонки. Метод
ajaxSuccess
и другие действуют точцо так же, как
click, mouseover
и другие простые методы регистрации событий, о которых рассказывалось в разделе 19.4.1.