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

jQuery AJAX

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

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


Обращаю Ваше внимание на то, что создание транспортного объекта является наиболее продвинутым способом обработки запроса AJAX и должен использоваться только в качестве крайней меры, когда использование префильтров (функция $.ajaxPrefilter()) и конверторов (параметр converters в функциях .ajaxSetup() и $.ajax()) недостаточно для достижения поставленной задачи.


jQuery синтаксис:

Синтаксис 1.5:
// оба параметра являются обязательными
$.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 запроса, он используется без параметров.

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

<!DOCTYPE html>
<html>
	<head>
		<title>Использование функции $.ajaxTransport()</title>
		<script src = "https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.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()
jQuery AJAX