• Заметки
    •

    Шпаргалка по jQuery функциям работающим с Ajax

    Меню

    Отредактировано: 23 Октября 2019

    Asynchronous Javascript And Xml — полное название технологии AJAX. Это технология обращения к серверу без перезагрузки страницы.

    jQuery функции работающие с технологией Ajax:

    • $.ajax() —  детальная настройка ajax параметров. Эта функция лежит в основе всех Ajax jQ запросов.
    • $.ajaxSetup() — указание настроек «по умолчанию».

      jQuery.ajaxSetup( [settings] )

      settings — объект с настройками, заданный в формате {имя:значение, имя:значение...}

      // установим адрес ajax-запроса, который будет использоваться по умолчанию
$.ajaxSetup({
  url: "test.php"
});

// вызовем ajax функцию, при этом она будет направлена на адрес указанный выше
$.ajax({
  data: {'name': 'Tim'},
});
    • $.get() — отправляет GET запрос на сервер.

      jQuery.get(url,[data],[callback],[dataType])

      • url — url-адрес, по которому будет отправлен запрос.
      • data — данные, которые будут отправлены на сервер. Они должны быть представлены в объектом, в формате: {fName1:value1, fName2:value2, ...}.
      • callback(data, textStatus, jqXHR) — пользовательская функция, которая будет вызвана после ответа сервера.
        • data — данные, присланные с сервера.
        • textStatus — статус того, как был выполнен запрос.
        • jqXHR — объект jqXHR (в версиях до jquery-1.5, вместо него использовался XMLHttpRequest)
      • dataType — ожидаемый тип данных, которые пришлет сервер в ответ на запрос.
    • $.post() — отправляет POST запрос на сервер.

      jQuery.post(url,[data],[callback],[dataType])

      • url — url-адрес, по которому будет отправлен запрос.
      • data — данные, которые будут отправлены на сервер. Они должны быть представлены в объектом, в формате: {fName1:value1, fName2:value2, ...}.
      • callback(data, textStatus, jqXHR) — пользовательская функция, которая будет вызвана после ответа сервера.
        • data — данные, присланные с сервера.
        • textStatus — статус того, как был выполнен запрос.
        • jqXHR — объект jqXHR (в версиях до jquery-1.5, вместо него использовался XMLHttpRequest)
      • dataType — ожидаемый тип данных, которые пришлет сервер в ответ на запрос.
      $.post(document.location.href, {
            action: 'filter',
            fields: fields
        }, function(data) {
           ...
        });
    • $().load() — подгружает ответ от сервера внутрь указанного элемента.

      jQuery(this).load(url,[data],[callback],[dataType])

      • url — url-адрес, по которому будет отправлен запрос.
      • data — данные, которые будут отправлены на сервер. Они должны быть представлены в объектом, в формате: {fName1:value1, fName2:value2, ...}.
      • callback(data, textStatus, jqXHR) — пользовательская функция, которая будет вызвана после ответа сервера.
        • data — данные, присланные с сервера.
        • textStatus — статус того, как был выполнен запрос.
        • jqXHR — объект jqXHR (в версиях до jquery-1.5, вместо него использовался XMLHttpRequest)
      • dataType — ожидаемый тип данных, которые пришлет сервер в ответ на запрос.

      Частичная вставка данных

      Если в url адресе установлен селектор, то код будет вставлен частично. 
      $('#result').load('ajax/test.html #container');
    • $.getJSON() — GET запрос JSON-данных с сервера.

      jQuery.getJSON(url,[data],[callback])

      • url — url-адрес, по которому будет отправлен запрос.
      • data — данные, которые будут отправлены на сервер. Они должны быть представлены в объектом, в формате: {fName1:value1, fName2:value2, ...}.
      • callback(data, textStatus, jqXHR) — пользовательская функция, которая будет вызвана после ответа сервера.
        • data — данные, присланные с сервера.
        • textStatus — статус того, как был выполнен запрос.
        • jqXHR — объект jqXHR (до jQuery 1.5, использовался XMLHttpRequest).
      // $.getJSON() — сокращенный вариант функции $.ajax(), вызванной со следующими параметрами
$.ajax({
  url: url,
  dataType: 'json',
  data: data,
  success: callback
});
    • $.getScript() — GET запрос JavaScript данных с сервера, с последующим выполнением.

      jQuery.getScript(url, [success(data, textStatus)])

      • url — url-адрес, url-адрес js-файла.
      • success(data, textStatus) — пользовательская функция, которая будет вызвана после удачного выполнения загруженного js-файла.
        • data — данные, присланные с сервера.
        • textStatus — статус того, как был выполнен запрос.
      // Запрос файла "test.js" у сервера. После окончания загрузки он будет автоматически выполнен
$.getScript("test.js");

// загрузка файла и вывод сообщения, после его удачного выполнения
$.getScript("test.js", function(){
   alert("Скрипт выполнен.");
 });

    Дополнительные функции:

    • $.param() — преобразует объект, массив или массив объектов в строку, пригодную для передачи через url.
    • $().serialize() — преобразует данные формы в строку, пригодную для передачи через url.
    • $().serializeArray() — преобразует данные формы в массив объектов, содержащий данные элементов формы.

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

    Официальная документация

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

    jQuery.ajax( url [, settings] ) — запись для JQ начиная с версии 1.5

    jQuery.ajax( [settings] ) — запись для JQ начиная с версии 1.0

    url — URL адрес, на который будет отправлен Ajax запрос. Тип: Строка.
    settings — набор параметров вида «ключ: значение», которые настраивают запрос Ajax. Все настройки опциональны. Настройки по умолчанию устанавливаются с помощью $.ajaxSetup(). Тип: Объект.

    Возвращает объект jqXHR (надмножество объекта XMLHTTPRequest).

    Список возможных настроек параметров $.Ajax()

    accepts

    По умолчанию: зависит от параметра DataType

    Тип: объект

    При выполнении запроса, в заголовках (header) указываются допустимые MIME-типы содержимого, ожидаемого от сервера. Значения этих типов будут взяты из параметра accepts.

    async

    По умолчанию: true

    Тип: boolean

    Определяет способ обработки скрипта. По умолчанию, после отправки запроса на сервер, страница не останавливает свою работу в ожидании ответа, т.е. работает асинхронно.

    Чтобы включить синхронный запрос, укажите в параметре- false, но имейте в виду, что выполнение запросов в синхронном режиме может привести к блокировке страницы, пока запрос не будет полностью выполнен. А также, что кроссдоменные запросы и запросы типа "jsonp" не могут выполняться в синхронном режиме.

    beforeSend(jqXHR, объект settings)

    Тип: функция

    Содержит функцию, которая будет вызвана непосредственно перед отправкой ajax-запроса на сервер. Такая функция может быть полезна для модификации jqXHR-объекта (в ранних версиях библиотеки (до 1.5), вместо jqXHR используется XMLHttpRequest). Например, можно изменить/указать нужные заголовки (headers) и.т.д. Объект-jqXHR будет передан в функцию первым аргументом. Вторым аргументом передаются настройки запроса.

    beforeSend относится к ajax-событиям. Поэтому если указанная в нем функция вернет false, ajax-запрос будет отменен.

    Начиная с jQuery-1.5, beforeSend вызывается независимо от типа запроса.

    cache

    По умолчанию: boolean

    Тип: true, false для типов данных 'script' and 'jsonp'

    Если false, запрашиваемая страница не будет кэшироваться браузером

    complete(jqXHR, строка textStatus)

    Тип: функция или массив

    Функция, которая будет вызвана после завершения ajax запроса (срабатывает после функций-обработчиков success и error). Принимает два аргумента:

    • объект типа jqXHR (в ранних версиях, до jQuery 1.4.x использовался XMLHttpRequest);
    • textStatus — cтроку, характеризующую статус запроса: "success", "notmodified", "error", "timeout", "abort", или "parsererror" (начиная с jQuery 1.5, complete может принимать массив функций).
    contents

    Тип: объект

    Параметр задается в формате {строка:регулярное выражение} и определяет, как jQuery будет разбирать ответ от сервера, в зависимости от его типа. (добавлено в версии 1.5)

    contentType

    По умолчанию: 'application/x-www-form-urlencoded; charset=UTF-8'

    Тип: строка

    При отправке Ajax запроса, данные передаются в том виде, в котором указаны в данном параметре. По умолчанию используется 'application/x-www-form-urlencoded; charset=UTF-8'. Если задать значение самим, то оно будет отправлено на сервер. Если кодировка не указана, то по умолчанию будет использоваться кодировка выставленная на сервере.

    context

    Тип: объект

    Объект, который станет контекстом после выполнения запроса (передаваемое значение в переменную this). Например, если указать в качестве контекста DOM-элемент, то все обработчики ajax-запроса тоже будут выполняться в контексте данного DOM-элемента. В данном примере ключевое слово this будет содержать document.body:

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

    По умолчанию: {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML}

    Тип: объект

    Определяет, с помощью каких функций будет производиться конвертация значений из одного типа, в другой. (добалено в версии 1.5

    crossDomain

    По умолчанию: false для одного и того же домена, true для кроссдоменных запросов.

    Тип: boolean

    Если вы хотите, чтобы выполнить кросс-доменный запрос (например, JSONP) на том же домене, выставите true в настройке crossDomain. Это позволяет, например, сделать серверные перенаправление на другой домен. (добалено в версии 1.5)

    data

    Тип: объект или строка

    Данные, которые будут переданы на сервер. Если данные не являются строкой, то они конвертируются в строку запроса.

    Для запросов типа GET данные прикрепляются к URL. Объект должен состоять из пар ключ/значение. Если в значении массив, то jQuery упорядочивает значения в зависимости от настройки traditional. По умолчанию, например, {foo:["bar1", "bar2"]} превращается в &foo=bar1&foo=bar2.

    dataFilter(строка data, строка type)

    Тип: функция

    Функция, с помощью которой будут обрабатываться сырые данные типа XMLHttpRequest, полученные от сервера. Ваша функция должна играть роль фильтра и возвращать очищенную строку. В функцию передаются два параметра: полученные данные и значение параметра dataType.

    dataType

    По умолчанию: автоматически определяемая строка (xml, json, script, или html)

    Тип: строка

    Тип данных, ожидаемых от сервера. Если опция не определена, то jQuery попытается определить тип, основываясь на MIME-типе ответа.

    error(jqXHR, строка textStatus, строка errorThrown)

    Функция, исполняемая в случае неудачного запроса. Принимает 3 аргумента:

    • объект jqXHR (в прошлом XMLHttpRequest);
    • строку с описанием ошибки. Может содержать:
      • null
      • timeout
      • error
      • abort
      • parsererror
    • строку исключения, если оно было выброшено. если происходит HTTP ошибка, то в третий аргумент будет записан её текстовой статус. К примеру, "Not Found" или "Internal Server Error". Начиная с jQuery 1.5, вместо одной функции, этот параметр может принимать массив функций.

    Событие error не происходит при dataType равному script или JSONP.

    global

    По умолчанию: true

    Тип: boolean

    Вызывать или нет глобальные обработчики событий Ajax для этого запроса.

    Глобальные события:

    • $.ajaxStart() — начало.
      • $.ajaxError() — ошибка.
      • $.ajaxSuccess() — успешное выполнение.
      • $.ajaxComplete() — завершение запроса.
      • $.ajaxSend() — отправка.
    • $.ajaxStop() — конец.
    headers

    По умолчанию: {}

    Тип: объект

    Здесь можно указать дополнительные заголовки запроса (header). Значения этой настройки будут введены до вызова функции beforeSend, в которой могут быть внесены окончательные изменения в заголовки. (добалено в версии 1.5)

    ifModified

    По умолчанию: false

    Тип: boolean

    Запрос будет считаться успешным только в случае, если данные ответа изменились со времени последнего запроса. Проверка осуществляется по заголовку Last-Modified. По умолчани, данная опция отключена. В jQuery 1.4 так же проверяется значение 'etag', для отслеживания факта изменения данных.

    isLocal

    По умолчанию: зависит от текущей локации

    Тип: boolean

    Параметр определяет, запущена ли веб-страница локально (например по протоколу file, *-extension, и widget) или нет (например по протоколу http).

    jsonp

    Тип: строка

    Определяет имя параметра, который добавляется в url JSONP-запроса(по умолчанию, используется "callback"). К примеру настройка {jsonp:'onJSONPLoad'} преобразуется в часть url строки 'onJSONPLoad=?'. Начиная с версии 1.5, указание в этом параметре false предотвращает добавление в url дополнительного параметра. В этом случае, необходимо установить значение настройки jsonpCallback. Например так: {jsonp:false, jsonpCallback:"callbackName"}.

    jsonpCallback

    Тип: строка или функция

    Функция, которая будет вызвана при ответе сервера на запрос типа JSONP. По умолчанию, jQuery генерирует произвольное уникальное имя этой функции, что более предпочтительно. Если вы хотите использовать кэширование GET запросов, то вписывайте название функции сами. Начиная с версии 1.5 можно указать функцию, для того, чтобы обработать ответ сервера самостоятельно.

    method

    По умолчанию: GET

    Тип: строка

    Метод передачи данных который надо использовать ("POST", "GET", "PUT"). Добавлено в версии 1.9.0.

    mimeType

    Тип: строка

    Здесь можно указать тип данных, в котором ожидается ответ от сервера вместо XHR. Добалено в версии 1.5.1.

    password

    Тип: строка

    Пароль, который будет использоваться в ответ на запрос проверки подлинности доступа HTTP (если это требуется)

    processData

    По умолчанию: true

    Тип: boolean

    По умолчанию передаваемые на сервер данные преобразуются из объекта в строку запроса и отправляются как "application/x-www-form-urlencoded". Если вам необходимо отправить DOM-документ или иные данные, которые нельзя подвергать конвертированию установите опцию processData в false.

    scriptCharset

    Тип: строка

    Применяется только для Ajax GET-запросов типов 'JSONP' и 'script '. Если сервер на стороннем домене использует кодировку, отличную от вашей, необходимо указать кодировку стороннего сервера.

    statusCode

    По умолчанию: {}

    Тип: объект

    Набор пар, в котором кодам выполнения запроса сопоставляются функции, которые при этом будет вызваны. Например, для кода 404 (страницы не существуют) можно сделать вывод сообщения на экран:

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

    Если запрос прошёл успешно, то в качестве параметра, анонимная функция будет принимать те же параметры, что и при success. При ошибке, будет принимать то же самое что и при функции-обработчике error. Добалено в версии 1.5

    success(объект data, строка textStatus, объект jqXHR)

    Тип: функция или массив

    Функция, которая будет вызвана в случае успешного завершения запроса. Принимает 3 аргумента:

    • data — данные, присланные сервером и прошедшие предварительную обработку;
    • textStatus — строка со статусом выполнения;
    • объект jqXHR.
      • В версиях до 1.5 вместо jqXHR используется XMLHttpRequest. 
      • В версиях после 1.5, вместо одной функции, этот параметр может принимать массив функций.

    Если в качестве параметра dataType указан JSON, данная функция может не обрабатываться, по многим причинам, но в основе большинства причин лежит ошибка. Чтобы понять почему не обрабатывается функция:

    • проверьте консоль в браузере на наличие ошибок;
    • проверьте логи CMS или иной платформы;
    • проверьте логи сервера.

    Ошибка не обязательно должна быть связана с тем что указано в блоке.

    timeout

    Тип: число

    Время ожидания ответа от сервера в миллисекундах. Переписывает глобальную настройку этого же параметра в $.ajaxSetup(). Если это время будет превышено, запрос будет завершен с ошибкой и произойдет событие error, которое будет иметь статус "timeout".

    traditional

    По умолчанию: false

    Тип: boolean

    Установите значение этого параметра в true, для того, чтобы использовать традиционный стиль сериализации.

    type

    По умолчанию: GET

    Тип: строка

    Определяет тип запроса GET или POST. Можно также использовать другие HTTP-запросы (такие как PUT или DELETE), но следует помнить, что они поддерживаются не всеми бразерами.

    url

    По умолчанию: текущая страница

    Тип: строка

    Страница, накоторую будет отправлен запрос.

    username

    Тип: строка

    Имя пользователя, которое будет использоваться в ответ на запрос проверки подлинности доступа HTTP (если это требуется)

    xhr

    По умолчанию: ActiveXObject в IE, XMLHttpRequest в других браузерах

    Тип: функция

    Callback-функция, для создания объекта XMLHttpRequest. Создав свою функцию, вы берёте на себя всю ответственность за формирование объекта.

    xhrFields

    По умолчанию: значение

    Тип: map

    Объект вида {имя:значене} для изменения значений соответствующих полей объекта XMLHttpRequest. Добалено в версии 1.5.1.

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

    $.ajaxPrefilter() — устанавливает обработчик, вызываемый перед выполнением каждого ajax-запроса. Предшествует выполнению любых других обработчиков ajax.

    Объект jqXHR

    Объект jqXHR является надмножеством объекта XMLHTTPRequest, и содержит в себе:

    • responseText свойство;
    • responseXML свойство;
    • getResponseHeader() метод.
    • overrideMimeType() метод (до JQuery 1.5.1), может использоваться в функции beforeSend(), например, для изменения content-type заголовка.

    Примеры jQuery Ajax функций

    Пример установки глобальных параметров с помощью $.ajaxSetup():

    // Функция для постоянного выполнения одинаковых запросов (например: чат)
$.ajaxSetup({
   url: "script.php",
   global: true,
   type: "POST"
});

    Пример функции .get():

    $("#button").click(function(){
   $.get(){"script.php",
           // параметр data можно указать в строковом типе
           // data=content
           (data: "content"), // тип объект
            function(data, textStatus){
                $("#content").empty()
                             .append(textStatus + ":" + data);
            },
            "html" // тип данных, возможные типы смотрите в параметре dataType 
   },
});

    Пример функции .post():

    $("#button").click(function(){
   $.post(){"script.php",
           // параметр data можно указать в типе object
           // (data: "content")
            data=content, // тип строка
            function(data, textStatus){
                $("#content").empty()
                             .append(textStatus + ":" + data);
            },
            "html" // тип данных, возможные типы смотрите в параметре dataType 
   },
});

    Пример функции .load():

    $("#button").click(function(){
   $("#content").load(){"script.php",
           // параметр data можно указать в строковом типе, при этом метод отправки будет GET
           // (data: "content")
           (data: "content", data2: "content2"), // тип объект, метод POST
           // необязательный параметр
           function(responceText, textStatus, XMLHttpRequest){
                alert(responceText + "<br>" + textStatus);
            },
   },
});

    Пример обработки Ajax события:

    $("#content").ajaxSuccess(function(event,request,settings){
       $(this).append("<br>Запрос успешно обработан");
});

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

    $.ajax({
    url: '/test.php',
    method: 'POST',
    data: {text: textValue},
    success: function(data) {
        alert(data);
    }
});

     

    front-end jq