Функция jQuerys $.ajax()

В статье введение в jQuery укороченные методы Ajax были рассмотрены самые популярные короткие Ajax методы: $.get(), $.post(), и $.load(). Они удобны, когда запросы Ajax не больше пары строчек кода.

Иногда возникает необходимость в конкретизации совершаемых Ajax запросов. Например, нужно задать действие на тот случай, если Ajax запрос не будет выполнен; или когда нужно задать время, по истечении которого ответ на запрос становится ненужным. Для таких случаев существует jQuery функция $.ajax().

Функция $.ajax()

Функция $.ajax() применяется для совершения асинхронных запросов HTTP. В библиотеку эта функция была добавлена давно – она присутствует в ней начиная с версии 1.0. Именно эту функцию вызывают рассматриваемые в упомянутой выше статье (короткие Ajax методы: $.get(), $.post(), и $.load()) функции, используя предустановленную конфигурацию. Сигнатура этой функции показана ниже:

$.ajax(url[, options])
$.ajax([options])

Параметр url – строка, содержащая запрашиваемый URL; options – литерал объекта, содержащий конфигурацию запроса Ajax.

В первом варианте функция совершает Ajax запрос посредством параметра url и параметров, прописанных в options. Во втором варианте URL конкретизируется в параметре options; URL можно проигнорировать, тогда будет запрашиваться текущая страница.

Список свойств, используемых этой функцией, приведен ниже. Он весьма обширен. Поэтому здесь приведены их краткие описания. Более подробное описание можно найти в официальной документации по $.ajax().

Параметр ajax option

Есть много различных опций, с помощью которых вы можете настроить $.ajax() так, как вам необходимо.

• accepts: тип контента, посылаемый в заголовке запроса; этим вы сообщаете серверу, какого рода ответ вы будете обрабатывать
• async: задайте false, чтобы совершить синхронный запрос
• beforeSend: функция обратного вызова срабатывает перед отправкой запроса; с ее помощью можно модифицировать объект jqXHR перед его отправлением
• cache: задайте false, чтобы запрашиваемые страницы не были кэшированы браузером
• complete: функция, вызываемая по завершении запроса (сработает после выполнения функций обратного вызова success и error)
• contents: объект, который определяет, как библиотека разберет (будет парсить) ответ
• contentType: тип содержимого, посланное серверу (по умолчанию «application/x-www-form-urlencoded»)
• context: объект, используемый как контекст (this) для всех AJAX-функций обратного вызова (это может быть js-объект или jquery-элемент)
• converters: объект, позволяющий преобразовать одни значения dataType в другие значения dataType
• crossDomain: установите true, чтобы совершить сross-domain (междоменный) запрос (к примеру, JSONP) в ту же доменную зону
• data: данные, посылаемые на сервер при выполнении Ajax-запроса
• dataFilter: функция, используемая для предварительной обработки данных, присланных сервером
• dataType: тип данных, ожидаемый от сервера
• error: функция, вызываемая при неисполнении запроса
• global: использовать ли глобальные обработчики событий для данного Ajax-запроса
• headers: объект из дополнительных заголовков, которые будут посланы серверу
• ifModified: задайте true, тогда запрос будет успешным только в том случае, если ответ изменился по сравнению с ответом предыдущего запроса
• isLocal: задайте true, чтобы jQuery распознавала текущую среду как локальную
• jsonp: строка переопределяющая имя callback-функции в JSONP запросе
• jsonpCallback: задает имя функции для запроса JSONP (будет вызвана при ответе сервера на jsonp-запрос)
• mimeType: строка задает тип данных в mime-формате, замещает аналогичное поле в XHR объекте
• password: пароль, для аутентификации на сервере
• processData: задайте false, чтобы данные, передаваемые в параметре data (если не строка) не обрабатывались и не преобразовывались в строку-запроса
• scriptCharset: устанавливает кодировку для кроссдоменного запроса
• statusCode: объект, в котором кодам выполнения запроса назначаются функции. Функции вызываются в зависимости от кода ответа.
• success: функция будет вызвана с случае успешного запроса
• timeout: время ожидания ответа от сервера (в миллисекундах) для запроса
• traditional: установите true, если хотите использовать традиционный стиль для параметров преобразования (сериализации)
• type: тип совершаемого запроса: Post или Get
• url: строка, содержащая URL, на который посылается запрос
• username: Имя пользователя для аутентификации на сервере
• xhr: функция обратного вызова для создания XMLHttpRequest объекта
• xhrFields: объект для изменения/добавления значений у родных полей объекта XMLHttpRequest.

Практическое применение функции $.ajax

Первый пример использования $.ajax()

Для наглядной демонстрации $.ajax() воспользуемся кодом из предыдущей статьи. Он приведен ниже:

jQuery

$('#main-menu a').click(function(event) {
   event.preventDefault();

   $('#main').load(this.href + ' #main *', function(responseText, status) {
      if (status === 'success') {
         $('#notification-bar').text('The page has been successfully loaded');
      } else {
         $('#notification-bar').text('An error occurred');
      }
   });
});

Применим функцию $.ajax(). С ней предудущий код будет выглядеть следующим образом:

jQuery

$('#main-menu a').click(function(event) {
   event.preventDefault();

   $.ajax(this.href, {
      success: function(data) {
         $('#main').html($(data).find('#main *'));
         $('#notification-bar').text('The page has been successfully loaded');
      },
      error: function() {
         $('#notification-bar').text('An error occurred');
      }
   });
});

Как видите, я использовал первый синтаксис функции $.ajax(). URL, к которому посылается запрос, задан посредством первого параметра; объект с опциями задан посредством второго параметра. Последний использует пару свойств, описанных выше: success и error задают действия в случае успеха или неудачи запроса соответственно.

Сервис Joind.in с использованием $.ajax()

Во втором примере рассмотрим создание запроса JSONP с целью получения информации от сервиса Joind.in. Последний представляет из себя веб-сайт, на котором участники определенных мероприятий могут оставлять свои комментарии и отзывы. Создадим фрагмент кода, который, используя функцию $.ajax(), извлекает мое имя и часть разговора о разработке в PHP.

jQuery

$.ajax({
   url: 'http://api.joind.in/v2.1/talks/10889',
   data: {
      format: 'json'
   },
   error: function() {
      $('#info').html('<p>An error has occurred</p>');
   },
   dataType: 'jsonp',
   success: function(data) {
      var $title = $('<h1>').text(data.talks[0].talk_title);
      var $description = $('<p>').text(data.talks[0].talk_description);
      $('#info')
         .append($title)
         .append($description);
   },
   type: 'GET'
});

В коде выше я использовал несколько описанных мною свойств. Во-первых, применяется $.ajax(), где параметр url передается, как часть объекта options. API Joind.in допускает запрос(ы) JSNOP, поэтому для запроса я задам специфическое свойство dataType. Далее с помощью свойства data описывается тип формата, который я хочу получить от сервера, как того требует API. Так как эти данные должны быть представлены в виде части (query string) строка запроса GET, то я задаю свойству type значение GET. Наконец, были описаны функции обратного вызова: error - для показа сообщения при ошибке, и success – для показа имени и описания доклада в случае успеха.

Демо этого кода приведено ниже, а также доступно на JSFiddle:

Примечание: в случае, если потребуется библиотека для встраивания поговорите с Joind.in, я разработал библиотеку под названиемJoindln.js

Заключение

Была рассмотрена важнейшая Ajax функция jQuery - $.ajax(). Она дает широкие инструменты для контроля над тем, как запрос Ajax совершается, а ответ обрабатывается. Функция чрезвычайно полезна на тот случай, когда укороченные ajax-функции не дают желаемого результата.

Лучшему пониманию функции будет способствовать ее применение с разными модификациями свойств в разных фрагментах кода.

источник