www.jQueryBook.ru - jQuery документация

 

Сегодня: 06 декабря 2016 года, Вторник
Раздел API на стадии наполнения...

 

 

 

  • Категории: AjaxLow-Level Interface

    jQuery.ajax()

    Выполняет Ajax-запрос к серверу, используя множество необязательных параметров для его настройки.

Синтаксис и описание:

  • Добавлено в jQuery 1.0jQuery.ajax( [options] )

  • Функция jQuery.ajax() выполняет асинхронный HTTP запрос (Ajax). Этот универсальный метод обеспечивает полное управление запросом Ajax. Все параметры, полученные в виде свойств объекта options, являются необязательными.

Возвращаемое значение: Экземпляр объекта XHR (XMLHttpRequest).

Параметры:

  • options – (объект) Объект в виде набора свойств (пар ключ:'значение'), которые задают параметры для Ajax запроса. Возможных параметров (свойств объекта options) очень много, и обычно в большинстве случаев они используются далеко не все, а только некоторые из них. К тому же, все эти параметры являются необязательными, т.к. значение любого из них может быть установлено по умолчанию с помощью метода $.ajaxSetup().

         Для настройки Ajax-запроса доступны следующие свойства объекта options:

    • async – (boolean - логическое значение) По умолчанию имеет значение true, и тогда все запросы выполняются асинхронно (На то он и Ajax, чтобы операции выполнялись параллельно). Если установить зхначение false, что крайне нежелательно, то запрос будет выполняеться как синхронный (Другие действия браузера могут блокироваться на время, пока выполняется синхронный запрос. Да и вообще браузер может перестать реагировать и отвечать).

    • beforeSend( XHR ) – (функция) Функция, вызываемая перед отправкой запроса. Она используетсядля установки дополнительных (пользовательских) заголовков или для выполнения других предварительных операций. В качестве единственного аргумента ей передается экземпляр объекта XHR (XMLHttpRequest). Если функция возвращает ложное значение (false), то происходит отмена запроса. (см. модель событий Ajax)

    • cache – (boolean - логическое значение) Если имеет значение false, то запрашиваемые страницы не кэшируются браузером. (Браузер может выдавать результаты из кэша. Например, когда данные в ответе сервера на Ajax запрос всегда новые, то кеширование мешает). По умолчанию имеет значение true для типов данных text, xml, html, json. Для типов данных 'script' и 'jsonp' имеет значение по умолчанию false.

    • complete( XHR, textStatus ) – (функция) Функция, вызываемая по окончании запроса независимо от его успеха или неудачи (а также после функций success и error, если они заданы). Функция получает два аргумента: экземпляр объекта XHR (XMLHttpRequest) и строку, сообщающую о состоянии 'success' или 'error' (в соответствии с кодом статуса в ответе на запрос). (см. модель событий Ajax)

    • 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 получает два аргумента:

      1. data - полученные данные (тело ответа сервера),
      2. type - тип этих данных (параметр 'dataType').
    • dataType – (строка) Строка, определяющая название типа даных, ожидаемых в ответе сервера. Если тип данных не задан, jQuery сама пытается его определить, ориентируясь на MIME-тип ответа сервера. Допустимые значения:"xml", "html", "script", "json", "jsonp", "text". (Это необходимо для того, чтобы определить метод обработки данных, полученных в ответе на запрос, функцией dataFilter перед тем, как они будут переданы функции обратного вызова success.)

    • error( XHR, textStatus, errorThrown ) – (функция) Функция (см. модель событий Ajax), которая вызывается при неудачном запросе (если код статуса в ответе сервера сообщает об ошибке). Функции передаются три аргумента:

      1. XHR - экземпляр объекта XMLHttpRequest,
      2. textStatus - строка, описывающая тип ошибки, которая произошла ("timeout", "error", "notmodified" или "parsererror"),
      3. 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 ) – (функция) Функция, которая вызывается при успешном запросе (если код статуса в ответе на запрос сообщает об успехе). (см. модель событий Ajax) Функции передаются три аргумента:

      1. data - данные, возвращаемые сервером в ответе, предварительно обработанные функцией dataFilter в соответствии со значением параметра dataType,
      2. textStatus - строку с кодом статуса, сообщающем об успехе,
      3. 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 в остальных случаях.

Примеры:

  1.  

    // Выполнить асинхронный Ajax-запрос с помощью метода POST.
    // Отправить данные на сервер и в случае успеха вывести 
    // ответ сервера в диалоговом окне.
    
    $.ajax({
       type: "POST",
       url: "test.php",
       data: "name=John&location=Boston",
       success: function(msg){
         alert( "Data Saved: " + msg );
       }
     });

[ наверх ]










 




Справочник по jQuery JavaScript API на русском языке