Библиотека jQuery преобразует НТТР-ответ 304 в код состояния «notmodified». Код «notmodified» не считается ошибкой и передается функции обратного вызова success вместо обычного кода состояния «success». То есть если вы устанавливаете параметр
ifModified
, вы также должны проверять код состояния в своей функции обратного вызова - если будет получен код состояния «notmodified», то первый аргумент функции (данные из ответа) будет иметь значение undefined. Обратите внимание, что в версии jQuery ниже 1.4 НТТР-ответ 304 интерпретировался как ошибка, и код состояния «notmodified» передавался функции обратного вызова error, а не success. Подробнее о кодах состояния рассказывается во врезке в разделе 19.6.1.
global
Этот параметр
определяет, должна ли библиотека jQuery возбуждать события в ходе выполнения Ajax-запроса. По умолчанию имеет значение true. Присвойте этому параметру значение false, чтобы запретить все события, связанные с поддержкой архитектуры Ajax. (Полное описание событий приводится в разделе 19.6.4.) Имя этого параметра несколько обескураживает: он имеет имя «global», потому что обычно библиотека jQuery возбуждает события глобально, а не в конкретном объекте.
19.6.3.2. Функции обратного вызова
Следующие параметры определяют функции, вызываемые на разных стадиях в ходе выполнения Ajax-запроса. С параметром success вы уже знакомы: это функция обратного вызова, которая передается методам, таким как
jQuery.getJS0N.
Обратите внимание, что библиотека jQuery также посылает извещения в ходе выполнения Ajax-запроса в виде событий (если параметр global не был установлен в значение false).
context
Этот параметр определяет объект, используемый в качестве контекста - значения ссылки
this
– для различных функций обратного вызова. Данный параметр не имеет значения по умолчанию, и если его не устанавливать, функции обратного вызова будут вызываться в контексте объекта с параметрами, в котором они определяются. Значение параметра
context
также воздействует на порядок возбуждения событий механизмом поддержки Ajax (раздел 19.6.4). Значением этого параметра должен быть объект
Window
,
Document
или
Element
, в котором могут возбуждаться события.
beforeSend
Этот параметр определяет функцию, которая должна вызываться перед отправкой Ajax-запроса на сервер. Первым аргументом этой функции передается объект
XMLHttpRequest
, а вторым - объект с параметрами запроса. Функция
beforeSend
дает программе возможность установить собственные НТТР-заголовки в объекте
XMLHttpRequest
. Если эта функция вернет false, выполнение Ajax-запроса будет прервано. Обратите внимание, что для выполнения междоменных запросов типов «script* и «jsonp* объект
XMLHttpRequest
не используется и функция, определяемая параметром
befоreSend
, не вызывается.
success
Этот параметр определяет функцию, которая должна вызываться в случае успешного выполнения Ajax-запроса. В первом аргументе ей передаются данные, отправленные сервером. Во втором аргументе - код состояния, сгенерированный библиотекой jQuery, и в третьем - объект
XMLHttpRequest
, использовавшийся для выполнения запроса. Как описывалось в разделе 19.6.2.3, тип данных в первом аргументе зависит от значения параметра
dataType
или заголовка «Content-Type* в ответе сервера. Если данные имеют тип «xml», в первом аргументе передается объект
Document
. Если данные имеют тип «json* или «jsonp*, в первом аргументе передается объект, полученный в результате разбора ответа сервера в формате JSON. Если данные имеют тип «script», ответом является текст загруженного сценария (однако к моменту вызова функции сценарий уже будет выполнен, поэтому в данном случае ответ обычно игнорируется). Для других типов ответ интерпретируется как простой текст, содержащийся в запрошенном ресурсе.
Код состояния во втором аргументе обычно является строкой «success». Но, если был установлен параметр
ifModified
,
в этом аргументе может также передаваться строка «notmodified*. В этом случае сервер не отправляет данные в ответе, и в первом аргументе будет передано значение undefined. Для выполнения междоменных запросов на получение данных типов «script* и «jsonp» используется элемент <script>, а не объект
XMLHttpRequest
, поэтому для таких запросов в третьем аргументе вместо объекта
XMLHttpRequest
будет передаваться значение undefined.
error
Этот параметр определяет функцию, которая должна вызываться в случае неудачи Ajax-запроса. В первом аргументе этой функции передается объект
XMLHttpRequest
запроса (если таковой использовался). Во втором аргументе-код состояния, сгенерированный библиотекой jQuery. Это может быть строка «error» - в случае ошибки протокола HTTP, «timeout» - в случае превышения времени ожидания и «parsererror» - в случае ошибки, возникшей в ходе разбора ответа сервера. Например, если XML-документ или объект в формате JSON будет сформирован неправильно, функция получит код состояния «parser-error». В этом случае в третьем аргументе функции error будет передан объект Error, представляющий исключение. Обратите внимание, что запросы с параметром
dataType="script",
возвращающие недопустимый программный код JavaScript, не вызывают ошибки. Любые ошибки в сценарии просто игнорируются и вместо функции error вызывается функция success.
complete
Этот параметр определяет функцию, которая должна вызываться по завершении 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».