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

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

<jqXHR> = $.ajax([[<URL>, ]<Объект с опциями>])

Функция возвращает ссылку на объект, имитирующий объект XMLHttpRequest. Параметр <Объект с опциями> представляет собой объект, состоящий из пар «опция/значение». Могут быть указаны следующие опции:

  • url — URL-адрес обработчика на сервере. Значение можно также указать в параметре <URL>;
  • method и type — метод передачи данных (GET (значение по умолчанию), POST или др.);
  • data — данные, которые будут переданы на сервер. Параметры и значения должны быть указаны следующим образом:
{
   Параметр1: "Значение1",
   Параметр2: "Значение2",
   ...
   ПараметрN: "ЗначениеN"
}

В случае если параметры или значения содержат запрещенные символы, то они будут автоматически перекодированы:

data: { txt1: 'Текст' }

В качестве значения опции data можно также указать сформированную строку запроса. В этом случае заботиться о допустимости символов необходимо самим:

data: 'txt1=' + encodeURIComponent('Текст')
  • traditional — задает логическое значение для второго параметра функции $.param(<Объект>, traditional) (см. разд. 1.7.6), используемой для преобразования объекта в строку, предназначенную к отправке на сервер. Пример:
url: '/ajax.php',
method: 'GET',
data: { a: [1, 2, 3] },
traditional: false

Результат:

http://localhost/ajax.php?a%5B%5D=1&a%5B%5D=2&a%5B%5D=3

Если в опции traditional указать значение true, то результат будет другим:

http://localhost/ajax.php?a=1&a=2&a=3
  • processData — если указано значение false, то данные, указанные в опции data, не будут преобразовываться в строку запроса (при этом специальные символы закодированы не будут);
  • dataType — ожидаемый тип данных в ответе сервера. Если опция не указана, то тип будет определяться автоматически по MIME-типу в заголовках ответа сервера. Можно указать следующие типы данных:
  • text — простой текст;
  • html — HTML-документ;
  • xml — XML-документ. XML-документ должен быть иметь правильную структуру и соответствовать спецификации DOM;
  • script — JavaScript-код. После получения код исполняется в глобальном контексте. Если данные были получены с того же домена, то внутри функции, указанной в опции success, будут доступны данные в виде обычного текста. Данные также могут быть получены с другого домена. В случае получения данных с другого домена, внутри функции, указанной в опции success, данные будут иметь значение undefined. Запрос всегда делается методом GET;
  • json — ответ в формате JSON; после получения JSON-объект становится доступным внутри функции, указанной в опции success;
  • jsonp — ответ в формате JSONP; данные могут быть получены с другого домена. Чтобы отправить данные в этом формате, необходимо после параметров в URL-адресе указать конструкцию: <Параметр>=?. Название параметра может быть произвольным. Если в конце запроса указан вопросительный знак, то данные будут отправлены не с помощью технологии AJAX, а путем создания тега <script> с указанием URL-адреса в параметре src. Вместо вопросительного знака будет вставлено произвольное значение. Значение из конструкции <Параметр> необходимо указать перед данными в формате JSON в скрипте на сервере. Сами данные указываются внутри круглых скобок;
  • несколько значений через пробел — данные будут получены с учетом первого значения, а затем будут преобразованы в другие форматы с учетом второго и последующих значений. Например, при значении "text json" данные будут получены в текстовом формате, а затем преобразованы в объект JSON;
  • jsonp — позволяет указать название параметра для JSONP-запроса. При указании этой опции нет необходимости в конструкции <Параметр>=?:
$.ajax({
   url: 'http://site1/ajax.php',
   method: 'GET',
   data: { txt1: '1', txt2: '2' },
   dataType: 'jsonp',
   jsonp: 'callback',
   success: function(obj, status, xhr) {
      $('#div_ajax').html(obj.txt1 + '<br>' + obj.txt2);
   }
});

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

http://site1/ajax.php?callback=jQuery341042766313031207415_1590764482106&txt1=1&txt2=2&_=1590764482107

Опция может также иметь значение false, если указано значение в опции jsonpCallback. Параметр с названием функции добавляться не будет. В этом случае на сервере название функции должно быть заранее известно;

  • jsonpCallback — позволяет указать название пользовательской функции, которая будет использоваться для JSONP-запроса вместо названия генерируемого библиотекой jQuery. Можно указать строку или функцию, возвращающую строку с названием функции:
$.ajax({
   url: 'http://site1/ajax.php',
   method: 'GET',
   data: { txt1: '1', txt2: '2' },
   dataType: 'jsonp',
   jsonp: 'callback',
   jsonpCallback: 'myFunc',
   success: function(obj, status, xhr) {
      $('#div_ajax').html(obj.txt1 + '<br>' + obj.txt2);
   }
});

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

http://site1/ajax.php?callback=myFunc&txt1=1&txt2=2&_=1590769296378

Если в опции jsonp указать значение false, то строка запроса будет выглядеть так:

http://site1/ajax.php?txt1=1&txt2=2&_=1590769428782

На сервере в этом случае должно быть известно название функции myFunc():

<?php
header('Content-Type: text/javascript; charset=utf-8');
$txt1 = addslashes($_GET['txt1']);
$txt2 = addslashes($_GET['txt2']); ?>
myFunc({
   txt1: "<?=$txt1?>",
   txt2: "<?=$txt2?>"
});
  • cache — управление кешированием. Опция имеет смысл только при запросах методом GET. Могут быть заданы следующие значения:
  • true — ответ может быть помещен в кеш Web-браузера. Если в заголовках ответа сервера указан запрет кеширования, то данные не будут помещены в кеш;
  • false — запрет кеширования. Если указано это значение, то к строке запроса будет добавлен параметр _=<Метка времени>:
http://site1/ajax.php?txt1=1&txt2=2&_=1590769428782
  • async — тип запроса. Могут быть заданы следующие значения:
  • true — асинхронный запрос (выполнение текущего скрипта не приостанавливается до получения ответа); значение по умолчанию;
  • false — синхронный запрос (выполнение текущего скрипта будет продолжено только после получения ответа сервера);
  • timeout — максимальное время выполнения запроса в миллисекундах;
  • contentType — позволяет указать значение заголовка Content-Type. По умолчанию при запросах методом POST имеет значение application/x-www-form-urlencoded;
  • headers — позволяет добавить заголовок запроса или изменить его значение (например, можно изменить значение заголовка X-Requested-With). Значение указывается в виде объекта. В качестве примера изменим значение заголовка User-Agent:
headers: { 'User-Agent': 'MyRobot' }
  • mimeType — задает MIME-тип ответа сервера;
  • ifModified — если указать значение true, то запрос будет успешным только в том случае, если данные изменились. Для этого проверяется значения заголовков Last-Modified и ETag. При их наличии в последующих запросах добавляются заголовки If-Modified-Since и If-None-Match. Если сервер вернет код статуса 304 (документ без изменений), то функция, указанная в опции success, вызвана не будет. По умолчанию опция имеет значение false;
  • scriptCharset — позволяет указать кодировку данных при значениях опции dataType, равных "jsonp" или "script";
  • username — логин для HTTP-авторизации;
  • password — пароль для HTTP-авторизации;
  • crossDomain — по умолчанию для кроссдоменных запросов опция имеет значение true, а для обычных запросов — false. Если вы хотите выполнить запрос на тот же домен, но с него на сервере перенаправить запрос на другой домен, то следует указать значение true вручную;
  • beforeSend — ссылка на функцию, которая будет вызвана до передачи запроса на сервер. С помощью этой функции можно, например, добавить или изменить заголовки запроса. Если внутри функции вернуть значение false, то запрос будет отменен. Формат функции:
function <Название функции>(<Объект jqXHR>, <Объект с опциями>) {
   // ...
}

В качестве примера изменим значение заголовка User-Agent:

beforeSend: function(xhr, settings) {
   xhr.setRequestHeader('User-Agent', 'MyRobot');
}
  • dataFilter — ссылка на функцию, которая будет вызвана сразу после получения ответа с сервера, но до обработки данных с помощью jQuery. Внутри функции необходимо вернуть обработанные данные. Формат функции:
function <Название функции>(<Данные>, <Тип данных>) {
   // Обрабатываем данные
   return <Данные>; // Возвращаем обработанные данные
}
  • complete — ссылка на функцию, которая будет вызвана по окончании запроса, независимо от успешности его выполнения. Формат функции:
function <Название функции>(<Объект jqXHR>, <Статус>) {
   // ...
}

Через второй параметр доступен статус выполнения запроса в виде строки ("success", "notmodified", "nocontent", "error", "timeout", "abort" или "parsererror");

  • success — ссылка на функцию, которая будет вызвана в случае успешного выполнения запроса. Можно также указать массив ссылок на функции. Формат функции:
function <Название функции>(<Данные>, <Статус>, <Объект jqXHR>) {
   // ...
}

Через параметр <Данные> доступны данные, обработанные с учетом значения опции dataType;

  • error — ссылка на функцию, которая будет вызвана при ошибке. Можно также указать массив ссылок на функции. Формат функции:
function <Название функции>(<Объект jqXHR>,
                            <Статус>, <Исключение>) {
   // ...
}

Параметр <Статус> может содержать следующие значения: null, "timeout", "error", "abort" или "parsererror". Параметр <Исключение> позволяет получить информацию об ошибке;

  • statusCode — позволяет назначить обработчики для различных HTTP-кодов ответа сервера. Значение указывается в виде объекта:
statusCode: {
   404: function() {
      console.log('Страница не найдена');
   },
   200: function(data) {
      console.log(data);
   }
}
  • context — задает ссылку на DOM-элемент. Эта ссылка будет доступна внутри функций обратного вызова через указатель this. По умолчанию через this доступен объект с параметрами запроса. Пример:
$.ajax({
   url: '/ajax.php',
   method: 'GET',
   data: { txt1: '1', txt2: '2' },
   dataType: 'json',
   context: document.getElementById('div_ajax'),
   success: function(obj, status, xhr) {
      $(this).html(obj.txt1 + '<br>' + obj.txt2);
   }
});
  • global — если указано значение false, то глобальные обработчики (см. разд. 3.3.8) вызываться не будут. По умолчанию опция имеет значение true;
  • isLocal — значение true, если используется локальная система, и false — в противном случае;
  • xhrFields — позволяет изменить значения свойств объекта XMLHttpRequest. В качестве значения указывается объект с названиями свойств и их значениями. Отправим кроссдоменный запрос и разрешим отправку и получение cookies, указав для свойства withCredentials значение true (содержимое файла http://site1/ajax.php см. в листинге 3.18):
$.ajax({
   url: 'http://site1/ajax.php',
   method: 'GET',
   data: { txt1: '1' },
   dataType: 'json',
   xhrFields: {
      withCredentials: true
   },
   success: function(json, status, xhr) {
      $('#div_ajax').html(json.txt1 + '<br>' + json.myCookie);
   }
});
  • xhr — задает ссылку на функцию, возвращающую пользовательский объект XMLHttpRequest:
xhr: function() {
   return new XMLHttpRequest();
}
  • scriptAttrs — позволяет добавить параметры для тега <script>, используемого при отправке запроса с типом script или jsonp. Например, можно добавить параметры integrity и crossorigin. В качестве значения указывается объект с названиями параметров и их значениями;
  • accepts — позволяет указать MIME-тип для заголовка Accept, соответствующий значению опции dataType. В качестве значения указывается объект с названиями типов данных и соответствующих им MIME-типов:
dataType: 'mytype',
accepts: {
   mytype: 'application/x-mytype'
}

В результате при запросе будет добавлен заголовок Accept со следующим значением:

Accept: application/x-mytype, */*; q=0.01
  • contents — позволяет сопоставить название типа данных с содержимым заголовка Content-Type. В качестве значения указывается объект с названиями типов данных и регулярными выражениями для сопоставления:
contents: {
   mytype: /mytype/
}

Последовательность символов mytype в регулярном выражении будет найдена в таком заголовке и сопоставлена типу mytype:

Content-Type: application/x-mytype; charset=utf-8
  • converters — задает ссылку на функцию, которая будет использоваться для преобразования данных, полученных с сервера. Функция должна возвращать обработанные данные. Если вместо функции указать значение true, то преобразование не требуется. В качестве значения указывается объект с названиями типов данных и соответствующих им функциями. Получим данные типа mytype и преобразуем их в объект JSON:
$.ajax({
   url: '/ajax.php',
   method: 'GET',
   data: { txt1: '1', txt2: '2' },
   dataType: 'mytype json',
   contents: {
      mytype: /mytype/
   },
   converters: {
      'text mytype': true,
      'mytype json': function(data) {
         return JSON.parse(data);
      }
   },
   success: function(json, status, xhr) {
      $('#div_ajax').html(json.txt1 + '<br>' + json.txt2);
   }
});

Рассмотренные опции можно также указать в функции $.ajaxSetup(). В этом случае это будут значения по умолчанию для всех запросов. Формат функции:

$.ajaxSetup(<Объект с опциями>)

Пример:

$.ajaxSetup({                  // Запрос методом GET
   url: '/ajax.php',           // URL-адрес
   dataType: 'json',           // Тип возвращаемых данных
   cache: false                // Запрет кеширования
});
$.ajax({ // Опции запроса указаны в $.ajaxSetup()
   data: { txt1: '1', txt2: '2' },        // Передаваемые данные
   success: function(json, status, xhr) { // При удачном запросе
      $('#div_ajax').html(json.txt1 + '<br>' + json.txt2);
   },
   error: function(xhr, status, error) {  // При ошибке
      $('#div_ajax').text('Ошибка: ' + error);
   }
});
На заметку

Учебник по jQuery и AJAX
Учебник по jQuery и AJAX в формате PDF

Помощь сайту

ЮMoney (Yandex-деньги): 410011140483022

ПАО Сбербанк:
Счет: 40817810855006152256
Реквизиты банка:
Наименование: СЕВЕРО-ЗАПАДНЫЙ БАНК ПАО СБЕРБАНК
Корреспондентский счет: 30101810500000000653
БИК: 044030653
КПП: 784243001
ОКПО: 09171401
ОКОНХ: 96130
Скриншот реквизитов