jQuery функция $.ajaxTransport()

Определение и применение

jQuery функция $.ajaxTransport() позволяет создать транспортный объект, который обрабатывает фактическую передачу данных запроса AJAX. Данный объект предоставляет два метода send() и abort(), которые используются внутри функции $.ajax().

jQuery синтаксис:

Синтаксис 1.5:

JavaScript
// оба параметра являются обязательными
$.ajaxTransport( dataTypes, handler )

dataTypes - String

handler - Function( PlainObject options, PlainObject originalOptions, jqXHR jqXHR )

Создание транспортного объекта:

Код
$.ajaxTransport( dataTypes, handler ( PlainObject options, PlainObject originalOptions, jqXHR jqXHR ){
	if ( обработка запроса ) {
		return {
			send: function( PlainObject headers, Function completeCallback) {
			  // код метода send
			},
			abort: function() {
			  // код метода abort
			}
		}
	}
});

dataTypes - String

handler - Function( PlainObject options, PlainObject originalOptions, jqXHR jqXHR )

send - Function( PlainObject headers, Function completeCallback )

completeCallback - Function ( Integer status, String statusText, PlainObject responses, String headers )

abort - Function

Добавлен в версии jQuery

1.5

Значения параметров

Параметр Описание
dataTypes Строка, содержащая один, или несколько разделенных пробелами типов данных. Если параметр задан,фильтр будет осуществляться только на запросы с указанными типами данных. Обязательный параметр.
Основные типы:
  • "xml" - XML документ, который может быть обработан с помощью jQuery.
  • "html" - HTML как обычный текст.
  • "script" - данные в формате JavaScript.
  • "json" - данные в формате JSON.
  • "jsonp" - данные в формате JSON, используя при этом формат загрузки JSONP.
  • "text" - обычная текстовая строка.
  • несколько значений - значения разделяются пробелом.
handler Обработчик, предназначенный для возврата нового транспортного объекта, используется с типом данных, представленным в первом аргументе. Обязательный параметр.
Функция принимает следующие параметры:
  • options - объект, содержащий параметры текущего запроса AJAX.
  • originalOptions - объект, содержащий параметры запроса, предоставленные функцией $.ajax() без изменений и значений по умолчанию.
  • jqXHR - содержит объект XMLHTTPRequest
Метод send() Метод транспортного объекта, предназначенный для отправки AJAX запроса.
Метод имеет два параметра:
  • headers — объект, содержащий пары ключ: значение, определяющие заголовки запроса, которые транспортный объект может передать, если он поддерживает их.
  • completeCallback — функция обратного вызова, используемая для уведомления функции $.ajax() о завершении текущего запроса.
Функция обратного вызова принимает четыре параметра:
  • status — код состояния HTTP ответа (например, 200 - успешный запрос, или 404 - ресурс не найден).
  • statusText — строка соответствующая статусу ответа запроса ("success", "notmodified", "nocontent", "error", "timeout", "abort", или "parsererror"). Необязательный параметр.
  • responses — объект, содержащий пары dataType: value и определяет ответ в том формате, который может обеспечить транспортный объект. Например, собственный XMLHttpRequest объект будет установлен в {xml: XMLData, text: textData} для ответа, который содержит XML документ. Необязательный параметр.
  • headers — строка, содержащая все заголовки ответа, если транспортный объект имеет к ним доступ (прицип работы как у нативного метода XMLHttpRequest.getAllResponseHeaders()). Необязательный параметр.
Метод abort() Метод транспортного объекта, предназначенный для отмены AJAX запроса, он используется без параметров.

Пример использования

HTML
<!DOCTYPE html>
<html>
  <head>
    <title>Использование функции $.ajaxTransport()</title>
    <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
    <script>
      $(document).ready(function () {
        $.ajaxTransport("text", function (options, originalOptions, jqXHR) {
          // устанавливаем фильтр для AJAX запросов с типом данных "text"
          if (originalOptions.data.secretText === "Hello world") {
            // если объект data запроса содержит строку "Hello world"
            return {
              send: function (headers, completeCallback) {
                console.log("im trying to send");
                var value = false;
                if (value) {
                  // if ( true )
                  completeCallback(200, "success"); // функция обратного вызова
                } else {
                  jqXHR.abort(); // прерываем AJAX запрос
                }
              },
              abort: function () {
                console.log("aborted");
              },
            };
          }
        });
        $.ajax({
          url: "ya.ru", // url на который отправляется AJAX запрос
          dataType: "text", // тип данных
          data: { secretText: "Hello world" },
          success: function () {
            // если запрос успешен
            console.log("HTTP 200, все ок");
          },
          error: function () {
            // если запрос не был выполнен
            console.log("ops, i did it again");
          },
        });
      });
    </script>
  </head>
  <body> </body>
</html>

В этом примере с использованием jQuery функции $.ajaxTransport() мы создаем транспортный объект, который обрабатывает фактическую передачу данных запроса AJAX с типом данных "text". Внутри функции мы проверяем содержится ли в запросе объект, параметр data которого, содержит строку "Hello world".

После этого с использованием метода send() транспортного объекта, предназначенного для отправки AJAX запроса для демонстрации работы функции проверяем значение переменной, если оно истинно, ты вызывается функция обратного вызова, которая сообщает функции $.ajax() код состояния HTTP ответа (200) и строку соответствующую статусу ответа запроса ("success"). При этом условии функция $.ajax() вызывает функцию обратного вызова success, которая вызывается если AJAX запрос выполняется успешно.

Обратите внимание, что в этом примере внутри метода send() транспортного объекта условие будет ложно, в результате чего мы вызываем метод abort объекта jqXHR, который прерывает AJAX запрос, после этого вызывается метод abort() транспортного объекта, информация о прерывании AJAX запроса поступает функции $.ajax(), которая в свою очередь вызывает функцию обратного вызова error, она вызывается если AJAX запрос не был выполнен.

Результат нашего примера:

Пример использования jQuery функции $.ajaxTransport()
Пример использования jQuery функции $.ajaxTransport()