jQuery.ajax()

Описание: Выполняет асинхронный HTTP (Ajax) запрос.

• Добавлен в версии: 1.5jQuery.ajax( url [, settings ] )

  • url
    Тип: String
    Строка, содержащая адрес URL, к которому направляется запрос.
  • settings
    Тип: PlainObject
    Ассоциативный массив для конфигурации Ajax запроса. Все настройки не обязательные к заполнению (опциональны). Значения по умолчанию могут быть установлены при помощи метод $.ajaxSetup(). Ниже приведен полный список всех настроек.

• Добавлен в версии: 1.0jQuery.ajax( [settings ] )

  • settings
    Тип: PlainObject
    Ассоциативный массив для конфигурации Ajax запроса. Все настройки не обязательные к заполнению (опциональны). Значения по умолчанию могут быть установлены при помощи метод $.ajaxSetup().
    • accepts (значение по умолчанию: зависит от dataType)
      Тип: PlainObject
      Ассоциативный массив отображающий заданный dataType его типу MIME, который отправляется полем Accept в заголовке HTTP запроса. Этот заголовок сообщает серверу какой формат ответа будет принят. Например, следующий пользовательский тип данных mycustomtype будет отправлен в запросе:

      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

      $.ajax({ accepts: { mycustomtype: 'application/x-some-custom-type' }, // Инструкции кк десериализовать тип данных `mycustomtype` converters: { 'text mycustomtype': function(result) { // Как то преобразуем return newresult; } }, // Ожидаем от сервера тип данных `mycustomtype` dataType: 'mycustomtype' });

      Важно: Вы должны дополнительно указать соотвествующие типу converters для корректной обработки Ajax ответа.
    • async (значение по умолчанию: true)
      Тип: Boolean
      По умолчанию, все зпросы отпрвляются асинхронно (т.е. это значение установленное в true по умолчанию). Если Вам нужен синхронный запрос, установите значение параметра false. Кросс-доменные и dataType: "jsonp" запросы не поддерживают синхронные операции. Обратите внимние, что синхронные запросы могут временно блокировать браузер или приостанавливать какие то активные операции в моменты выполнения запроса. Начиная с jQuery 1.8, использование async: false с jqXHR ($.Deferred) не рекомендуется; Вы должны использовать обработчики success / error / complete вместо соотвествующих методов объекта jqXHR, таких как jqXHR.done().
    • beforeSend
      Тип: Function( jqXHR jqXHR, PlainObject settings )
      Обработчик вызываемый перед совершения запроса, в котором Вы можете модицифировать объект jqXHR (В версиях jQuery 1.4.x и ниже, XMLHTTPRequest) перед тем как Ajax запрос будет отправлен. Использовать пользовательские заголовки и т.д. The jqXHR and settings objects are passed as arguments. This is an Ajax Event. Returning false in the beforeSend function will cancel the request. As of jQuery 1.5, the beforeSend option will be called regardless of the type of request.
    • cache (значение по умолчанию: true, false для dataType 'script' и 'jsonp')
      Тип: Boolean
      Если устновлено значение false, то принудительно запрошенные страницы не будут закешированы браузером. Важно: Значение false параметра cache будет корректно работать только с запросами HEAD и GET. Это работает путем добавления "_={timestamp}" к адресу GET запроса. Этот параметр не нужендля других типов запросов, исключая случай с IE8 когда POST запрос осуществляется к тому же адресу URL к которому уже выполнялся GET запрос.
    • complete
      Тип: Function( jqXHR jqXHR, String textStatus )
      Функция которая вызывается когда запрос завершается (после того как success или error обработчики будут вызваны). Функция принимает два аргумента: объект jqXHR (в версии jQuery 1.4.x и ниже, XMLHTTPRequest) и строка статуса запроса ("success", "notmodified", "nocontent", "error", "timeout", "abort" или "parsererror"). Начиная с jQuery 1.5, параметр complete может принимать массив функций. Каждая функция будет вызывана в свою очередь. Является Ajax событием.
    • contents
      Тип: PlainObject
      Ассоциативный массив с парами строки/регулярные выражения определяющие как jQuery будет парсить ответ, в зависимости от типа контента. (Добавлен в версии: 1.5)
    • contentType (значение по умолчанию: 'application/x-www-form-urlencoded; charset=UTF-8')
      Тип: Boolean or String
      Когда отправляются данные на сервер, используется этот тип контента Content-Type. Значение по умолчанию "application/x-www-form-urlencoded; charset=UTF-8", которое прекрасно подходит для большинства случаев. Если Вы явно передаете content-type в метод $.ajax(), то он всегда будет отправлен на сервер (даже если никакие данные не будут отправлены на сервер). Начиная с jQuery 1.6 Вы можете указать значени false чтобы jQuery не передавал в заголовке поле Content-Type совсем. Важно: Стандарт W3C XMLHttpRequest specification предписывает всегда использовать кодировку UTF-8; указание другой кодировки не вынудит браузер изменить кодировку. Важно: Для кросс-доменных запросов, установка тип контента в значение отличающегося от application/x-www-form-urlencoded, multipart/form-data или text/plain вынудит браузер отправить подготовительный OPTIONS запрос на сервер.
    • context
      Тип: PlainObject
      Это объект будет контекстом для всех обработчиков этого Ajax запроса. По умолчанию контекстом является объект представляющий Ajax настройки используемые при вызове ($.ajaxSettings объединеные с настройками переданными в $.ajax). Например, указав DOM элемент как контекст сделает его контекстом в обработчике запроса complete:

      1 2 3 4 5 6

      $.ajax({ url: "test.html", context: document.body }).done(function() { $( this ).addClass( "done" ); });

    • converters (значение по умолчанию: {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML})
      Тип: PlainObject
      Объект содержащий dataType-to-dataType конверторы. Значение каждого конвертора является функцией которая возвращает трансформированное значение ответа. (Добавлено в версии: 1.5)
    • crossDomain (значение по умолчанию: false для запросов к тому же домену, true для кросс-доменных запросов)
      Тип: Boolean
      Если Вы хотите выполнить запрос к тому же домену вынужденно как кросс-доменный (например JSONP), установите значение в true. Это позволяет, например, вернуть от сервера редирект н другой домен. (Добавлено в версии: 1.5)
    • data
      Тип: PlainObject или String или Array
      Данные отправляемые на сервер. Они будут преобразованы в строку, если еще не являются строкой. Для GET запроса эта строка будет добавлена к URL адресу. Смотрите праметр processData для предотвращения этой автоматической обработки. Объект должен быть ассоциативным массивом (пары ключ/значение). Если значение является массивом, то jQuery сериализирует значения массива с тем же самым ключем на основе значения параметра traditional (описан ниже).
    • dataFilter
      Тип: Function( String data, String type ) => Anything
      Функция используемая для обработки исходных данных от XMLHttpRequest. Это предварительная функция для проверки и чистки данных ответа. Вы должны вернуть очищенные данные. Функция принимает два аргумента: исходные данные отданные сервером и значение параметра dataType.
    • dataType (значение по умолчанию: Общеиспользуемые типы (xml, json, script, или html))
      Тип: String
      Тип данных которые Вы ожидаете от сервера. Если не указан, то jQuery будет пытаться определить его на базе типа MIME ответа (тип xml MIME даст XML, в 1.4 json даст JavaScript объект, в 1.4 script будет выполнен как скрипт и все прочее будет возвращено как строка). Возможные типы (и результат передается в качестве первого аргумента в обработчик запроса success):

      • "xml": Возвращает XML документ, который может быть обработан при помощи jQuery.
      • "html": Возвращает HTML как простой текст; включенные тэги скриптов будет выполнены когда этот HTML будет вставлен в DOM.
      • "script": Вычисляет ответ как JavaScript и возвращает его как простой текст. Отключает кэширование запроса (путем добавление параметра _=[TIMESTAMP] к URL адресу) даже если значение параметра cache равно true. Важно: Это превратит POST в GET для for запросов к удаленным доменам.
      • "json": Вычисляет ответ как JSON и возвращает JavaScript объект. Кросс-доменный "json" запрос конвертируются в "jsonp" если в параметрах запроса не указано jsonp: false. Данные в формате JSON обрабатываются в строгом порядке; любой нарушения формата будет отклонено и будет выброшена ошибка синтаксического анализа. Начиная с jQuery 1.9, пустой запрос также будет отклонен; сервер должен вернуть ответ null или {}.
      • "jsonp": Загружает данные в JSON используя при помощи формата загрузки JSONP. Добавляет дополнительный параметр "?callback=?" в конец URL адреса для указания функция обработчика. Выключает кэширование путем добавления параметра "_=[TIMESTAMP]" к URL адресу, даже если значение параметра cache равно true.
      • "text": Строка с текстом.
      • несколько, разделенных пробелом значений: начиная с jQuery 1.5, jQuery может преобразовать dataType от того что получен в поле заголовка Content-Type в то что Вам нужно. Например, если Вы хотите использовать текст ответа как XML, используйте значение "text xml" для параметра dataType. Вы также можете сделать JSONP запрос, если он получен в виде текста и интерпретируется jQuery как XML: "jsonp text xml". Точно так же, сокращенная строка, такая как "jsonp xml" сначала попытается преобразовать из JSONP в XML и если это невозможно, то преобразует из JSONP в текст и затем из текст в xml.
    • error
      Тип: Function( jqXHR jqXHR, String textStatus, String errorThrown )
      Функция вызывается если запрос закончится ошибкой. Функция принимает три аргумента: объект jqXHR (в jQuery 1.4.x, XMLHttpRequest), строка описывающая тип произошедшей ошибки и необязательный объект исключения, если он был вызван. Возможные значения второго аргумента (кроме null): "timeout", "error", "abort" и "parsererror". При возникновении HTTP ошибки, аргумент errorThrown примет текстовую часть HTTP статуса, такие как "Not Found" или "Internal Server Error." Начиная с jQuery 1.5, параметр error может принять массив функций. Каждая функция будет вызвана в своем порядке. Важно: Этот обработчик не вызывается для кросс-доменных скриптовых и кросс-доменных JSONP запросов. Являетсяе Ajax событием.
    • global (значение по умолчанию: true)
      Тип: Boolean
      Параметр регулирует вызывать ли глобальные Ajax события для этого запроса. По умолчанию значение равно true. Установка значения в false предотвратит вызов таких глобальных обработчиков как ajaxStart или ajaxStop. Это можно использовать для управления различными Ajax событиями.
    • headers (значение по умолчанию: {})
      Тип: PlainObject
      Объект с дополнительными полями заголовка HTTP запроса для отправки через XMLHttpRequest. Заголовок X-Requested-With: XMLHttpRequest добавляется всегда, но его значение по умоланию XMLHttpRequest можно изменить через этот параметр. Значения в headers также может быть переписаны в функции beforeSend. (добавлен в версии: 1.5)
    • ifModified (значение по умолчанию: false)
      Тип: Boolean
      Разрешает запросу быть успешным только если ответ изменился с момента последнего запроса. Это делается путем проверки поля заголовка Last-Modified. Значение по умолчанию false, игнорирует поля заголовка HTTP запроса. В jQuery 1.4 и ниже этот алгоритм также проверяет поле заголовка ответа 'etag' указанное сервером, что найти неизменненные данные.
    • isLocal (значение по умолчанию: зависит от текущего локального протокола)
      Тип: Boolean
      Разрешает текущему окружение как "локальное" (например файловая система), даже если jQuery не распознает его таким по умоланию. Следующие протоколыв в настоящее время признаются как локальные: file, *-extension и widget. Если опция isLocal требует изменения, то рекомендуется сделать это один раз при помощи метода $.ajaxSetup(). (добавлен в версии: 1.5.1)
    • jsonp
      Тип: String или Boolean
      Переопределяет имя функции обратного вызова в JSONP запросе. Это значение используется вместо названия функциии 'callback' в URL-параметре 'callback=?'. Так {jsonp:'onJSONPLoad'} передастся на сервер в виде 'onJSONPLoad=?'. Начиная с jQuery 1.5, значение параметра jsonp равное false предотвращает jQuery от добавления строки "?callback" к URL-адресу или попытки использовать "=?" для преобразования ответа. В этом случае, Вы должны явно указать значение параметра jsonpCallback. Например, { jsonp: false, jsonpCallback: "callbackName" }. Если Вы не доверяете целям Ваших Ajax запросов, то рекомендуется по соображениям безопасности установить значение параметра jsonp в false.
    • jsonpCallback
      Тип: String or Function()
      Указывает имя функции обратного вызова для запроса JSONP. Это значение будет использоваться вместо случайного имени, автоматически генерируемого jQuery. Предпотительно, чтобы jQuery само генерировало уникальное имя, это позволяет легче управлять запросами и обрабатывать ошибки. Вы можете указать функцию обратного вызова, если хотите обеспечить лучшее кэширование чем браузерное кэширование GET запросов. Начиная с jQuery 1.5, Вы также можете использовать функцию для этого параметра, в этом случае, значение jsonpCallback устанавливается в качестве возвращаемого значения этой функции.
    • method (значение по умолчанию: 'GET')
      Тип: String
      HTTP метод используемый в запросе (например "POST", "GET", "PUT" и т.д.). (добавлен в версии: 1.9.0)
    • mimeType
      Тип: String
      MIME тип переопределяющий XHR MIME тип. (добавлен в версии: 1.5.1)
    • password
      Тип: String
      Пароль для использования с XMLHttpRequest в ответ на запрос basic http авторизации.
    • processData (значение по умолчанию: true)
      Тип: Boolean
      По умолчанию данные, передаваемые в параметр data в качестве объекта (технически, все кроме строки) будут обработаны и преобразованы в строку запроса, подходящую для типа данных по умолчанию "application/x-www-form-urlencoded". Если Вы хотите отправить DOM документ, или другие необрабатываемые данные, установите значение данного параметр в false.
    • scriptCharset
      Тип: String
      Применяется только при использовании "script" в качестве транспорта (например, кросс-доменные запросы с "jsonp" или "script" dataType и методом "GET"). Устанавливает аттрибут charset используемого тэга script в запросе. Используется, когда кодировка символов на текущей странице отличается от кодировки символов удаленного скрипта.
    • statusCode (значение по умолчанию: {})
      Тип: PlainObject

      Объект с числовыми кодами HTTP кодов статусов и функции которые будут вызваны когда статус ответа имеет соотвествующее значение. Например, следующий alert будет вызван когда статус ответа будет 404:

      1 2 3 4 5 6 7

      $.ajax({ statusCode: { 404: function() { alert( "страниц не найдена" ); } } });

      Если запрос успешен, то соотвествующая функция будет принимать те же самые параметры что и success обработчик; если результат ошибка (включая редиректы 3xx), то эти функции примут те же параметры что и обработчик error.

      (добавлен в версии: 1.5)
    • success
      Тип: Function( Anything data, String textStatus, jqXHR jqXHR )
      Функция вызываемая если запрос успешен. Функция принимает три аргумента: data - данные возвращенные с сервера, отформатированные в соответствии с параметром dataType или dataFilter если они указаны; строка описывающая статус; и объект jqXHR (в версии jQuery 1.4.x и ниже XMLHttpRequest). Начиная с jQuery 1.5, Этот параметр может принимать массив функций. Каждая функция будет вызывана в свою очедерь. Является Ajax событием.
    • timeout
      Тип: Number
      Задает таймаут запроса (в милисекундах). Этот параметр переопределяет глобальный таймаут, устанавливаемый при помощи метода $.ajaxSetup(). Этот таймаут запускается в момент запуска метода $.ajax; если несколько других запросов в процессе работы и браузер не имеет сетевого подключения, то возможен запрос на таймаут, прежде чем он будет отправлен. В версии jQuery 1.4.x и ниже, объект XMLHttpRequest будет находиться в недопустимом состоянии если время ожидния будет превышено; обращение к любым методам объекта сгенерирует исключение. В Firefox 3.0+, script и JSONP запросы не могут быть отменены по таймауту; скрипт будет работать, даже если он прийдет после таймаута.
    • traditional
      Тип: Boolean
      Используйте значение true если Вы хотите использовать традиционный стиль сериализации параметров.
    • type (значение по умолчанию: 'GET')
      Тип: String
      Синоним для параметра method. Вы должны использовать type если Вы используете версию jQuery до 1.9.0.
    • url (значение по умолчанию: Текущий URL-адрес)
      Тип: String
      Строка содержащая URL-адрес на который будет отправлен запроса.
    • username
      Тип: String
      Имя пользователя используемое с XMLHttpRequest в ответ на запрос basic http авторизации.
    • xhr (значение по умолчанию: ActiveXObject когда доступен (IE), иначе XMLHttpRequest)
      Тип: Function()
      Функция обратного вызова для создания объекта XMLHttpRequest. По умолчанию используется ActiveXObject когда доступен (для IE), иначе используется XMLHttpRequest. У Вас есть возможность переопределить создание этого объекта и вернуть свою реализацию XMLHttpRequest или улучшить создание этого объекта.
    • xhrFields
      Тип: PlainObject

      Объект с парами fieldName-fieldValue для установки в нативный объект XHR. Например, Вы можете использовать значение withCredentials равное true для кросс-доменных запросов в случае необходимости.

      1 2 3 4 5 6

      $.ajax({ url: a_cross_domain_url, xhrFields: { withCredentials: true } });

      В jQuery 1.5, свойство withCredentials не будет распространено на нативный объект XHR и таким образом CORS запросы требуя его будет игнорировать этот флаг. По этой причине, мы рекомендуем использовать jQuery 1.5.1+.

      (добавлен в версии: 1.5.1)

$.ajax();

$.ajax({
  url: "http://fiddle.jshell.net/favicon.png",
  beforeSend: function( xhr ) {
    xhr.overrideMimeType( "text/plain; charset=x-user-defined" );
  }
})
  .done(function( data ) {
    if ( console && console.log ) {
      console.log( "Sample of data:", data.slice( 0, 100 ) );
    }
  });

// Назначаем обработчики сразу после выполнения запроса
// и сохраняем объект jqXHR для этого запроса
var jqxhr = $.ajax( "example.php" )
  .done(function() {
    alert( "success" );
  })
  .fail(function() {
    alert( "error" );
  })
  .always(function() {
    alert( "complete" );
  });
 
// Что то делаем ...
 
// Установим другой обработчик выполнения запроса
jqxhr.always(function() {
  alert( "second complete" );
});

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "mycustomtype json": function( result ) {
      // Какие то действия
      return newresult;
    }
  }
});

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "text mycustomtype": true,
    "mycustomtype json": function( result ) {
      // Какие то действия
      return newresult;
    }
  }
});

Дополнительные замечания: