jQuery.ajaxTransport()


jQuery.ajaxTransport( dataType, handler )Возвращает: undefined

Описание: Создает объект, который обрабатывает фактическую передачу данных Ajax

  • Добавлен в версии: 1.5jQuery.ajaxTransport( dataType, handler )

    • dataType
      Тип: String
      Строка задающая тип данных
    • handler
      Тип: Function( PlainObject options, PlainObject originalOptions, jqXHR jqXHR )
      Обработчик, который вернет новый объект-транспорт, который будет использоваться для указанного в первом аргументе типа данных.

Транспорт это объект который предоставляет два метода: send и abort, который используется внутри метода $.ajax(). Транспорт является самым продвинутым способом настройки $.ajax() и должен быть использован в последнюю очередь, если пре-фильтры и преобразователи уже не эффективны.

Так как каждый запрос требует свой собственный экземпляр объекта транспорта, то транспорты не могут быть зарегистрированы напрямую. Вы должны предоставить функцию, которая будет создавать такой объект каждый раз при ее вызове.

Фабрика транспортов регистрируется при помощи $.ajaxTransport(). Обычно регистрция выглядит так:

1
2
3
4
5
6
7
8
9
10
11
12
$.ajaxTransport( dataType, function( options, originalOptions, jqXHR ) {
if( /* transportCanHandleRequest */ ) {
return {
send: function( headers, completeCallback ) {
// Send code
},
abort: function() {
// Abort code
}
};
}
});

где:

  • options параметры запроса
  • originalOptions оригинальные параметры предоставленные методом $.ajax(), без изменений и без значений по умолчанию из ajaxSettings
  • jqXHR объект jqXHR этого запроса
  • headers ассоциативный массив с заголовками запроса, которые транспорт должен передать (если он поддерживает такую передачу)
  • completeCallback обработчик используемый для уведомления об окончании Ajax запроса

completeCallback имеет следующую сигнатуру:

1
function( status, statusText, responses, headers ) {}

где:

  • status код HTTP статуса ответа, обычно 200 код успешного ответа или 404 когда ресурс не найден.
  • statusText строка statusText ответа сервера.
  • responses (необязательный) объект содержащий типы данных/значения, которые содержат отклик во всех форматах которые транспорт может обеспечить (например, нативный объект XMLHttpRequest может установить ответ для { xml: XMLData, text: textData } для ответа в виде XML документа)
  • headers (необязательно) строка содержащая все заголовки ответа, если транспорт имеет к ним доступ (сродни тому, что может предоставить XMLHttpRequest.getAllResponseHeaders()).

Также как и префильтры, транспорт может быть указан для специфичного типа данных:

1
2
3
$.ajaxTransport( "script", function( options, originalOptions, jqXHR ) {
// Will only be called for script requests
});

Следующий пример показывает как может быть минимально применен транспорт изображение:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
$.ajaxTransport( "image", function( s ) {
if ( s.type === "GET" && s.async ) {
var image;
return {
send: function( _ , callback ) {
image = new Image();
function done( status ) {
if ( image ) {
var statusText = ( status === 200 ) ? "success" : "error",
tmp = image;
image = image.onreadystatechange = image.onerror = image.onload = null;
callback( status, statusText, { image: tmp } );
}
}
image.onreadystatechange = image.onload = function() {
done( 200 );
};
image.onerror = function() {
done( 404 );
};
image.src = s.url;
},
abort: function() {
if ( image ) {
image = image.onreadystatechange = image.onerror = image.onload = null;
}
}
};
}
});

Обработка пользовательских типов данных

Реализация jQuery Ajax предоставляет следующие типы данных: text, json, xml и html.

Используйте параметр converters в методе $.ajaxSetup() для преобразования типов данных используемых в $.ajax().

Unminified исходный код jQuery включает список преобразователей по умолчанию, которые эффективно иллюстрируют как они могут быть использованы:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// List of data converters
// 1) Key format is "source_type destination_type"
// (a single space in-between)
// 2) The catchall symbol "*" can be used for source_type
converters: {
// Convert anything to text
"* text": window.String,
// Text to html (true = no transformation)
"text html": true,
// Evaluate text as a json expression
"text json": jQuery.parseJSON,
// Parse text as xml
"text xml": jQuery.parseXML
}

Когда вы указываете параметр converters глобально в $.ajaxSetup() или при каждом вызове метода $.ajax(), объект будет использовтель преобразователи по умолчанию, перезаписав те что Вы определите самостоятельно.

Например, исходник jQuery $.ajaxSetup() показывает добавление преобразователя для "text script":

1
2
3
4
5
6
7
8
9
10
11
jQuery.ajaxSetup({
accepts: {
script: "text/javascript, application/javascript"
},
contents: {
script: /javascript/
},
converters: {
"text script": jQuery.globalEval
}
});