jQuery ajax - метод ajax()

Руководство по jQuery Ajax

Пример

Загрузка фрагмента текста через AJAX:

jQuery-код:

$(document).ready(function(){
  $("#b01").click(function(){
  htmlobj=$.ajax({url:"/jquery/test1.txt",async:false});
  $("#myDiv").html(htmlobj.responseText);
  });
});

HTML-код:

<div id="myDiv"><h2>Позвольте AJAX изменить этот текст</h2></div>
<button id="b01" type="button">Изменить содержимое</button>

Попробуйте сами

Определение и использование

Метод ajax() загружает удаленные данные через HTTP-запрос.

Этот метод является底层 реализацией AJAX в jQuery. Примеры простого использования на более высоком уровне - $.get, $.post и т.д. Функция $.ajax() возвращает созданный ею объект XMLHttpRequest. В большинстве случаев вам не нужно напрямую взаимодействовать с этой функцией,除非 вам нужно работать с редко используемыми параметрами для получения большей гибкости.

В наиболее простом случае $.ajax() можно использовать без параметров.

Внимание:Все параметры можно глобально настроить с помощью функции $.ajaxSetup().

Синтаксис

jQuery.ajax([settings]
Параметры Описание
settings

Опционально. Набор значений ключ-значение для конфигурации AJAX-запросов.

Любые параметры можно установить по умолчанию с помощью $.ajaxSetup().

Параметры

options

Тип: Объект

Опционально. Настройки AJAX-запроса. Все параметры опциональны.

async

Тип: Логический

Значение по умолчанию: true. По умолчанию все запросы являются асинхронными. Если необходимо отправить синхронный запрос, установите этот параметр в false.

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

beforeSend(XHR)

Тип: Функция

Функция, позволяющая изменить объект XMLHttpRequest до отправки запроса, например, добавить пользовательские HTTP-заголовки.

Объект XMLHttpRequest является единственным параметром.

Это Ajax-событие. Если возвращено false, можно отменить текущий ajax-запрос.

cache

Тип: Логический

Значение по умолчанию: true, dataType script и jsonp по умолчанию false. Установка false не будет кэшировать эту страницу.

jQuery 1.2 нововведения.

complete(XHR, TS)

Тип: Функция

Каллбэк-функция после завершения запроса (вызывается после успешного или неуспешного выполнения запроса).

Параметры: объект XMLHttpRequest и строка, описывающая тип запроса.

Это Ajax-событие.

contentType

Тип: Строка

Значение по умолчанию: "application/x-www-form-urlencoded". Тип кодирования содержимого при отправке данных на сервер.

Значение по умолчанию подходит для большинства случаев. Если вы явно передаете content-type в $.ajax(), то он будет отправлен на сервер (даже если нет данных для отправки).

context

Тип: Объект

Этот объект используется для установки контекста回调-функций Ajax. То есть, позволяет функции回调 устанавливать this на этот объект (если этот параметр не установлен, then this будет指向 параметры options, переданные при вызове этого AJAX-запроса). Например, если указать DOM-элемент в качестве параметра context, то устанавливается контекст success-回调 функции на этот DOM-элемент.

Так, например:

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

Тип: Строка

Данные, отправляемые на сервер. Автоматически преобразуются в формат строки запроса. В запросах GET будут добавлены в конце URL. См. описание параметра processData, чтобы запретить автоматическое преобразование. Должен быть в формате Key/Value. Если это массив, jQuery автоматически создаст одно и то же имя для различных значений. Например, {foo: ["bar1", "bar2"]} преобразуется в '&foo=bar1&foo=bar2'.

dataFilter

Тип: Функция

Функция предобработки данных, переданных Ajax. Предоставляет два параметра: data - это исходные данные, возвращенные Ajax, type - это параметр dataType, предоставленный jQuery.ajax. Значение, возвращаемое функцией, будет обработано jQuery.

dataType

Тип: Строка

Тип данных, который ожидается от сервера. Если не указать, jQuery автоматически определит тип данных на основе MIME-информации HTTP-пакета, например, тип MIME XML будет распознан как XML. В версии 1.4 JSON будет преобразован в объект JavaScript, а script будет выполнен. Затем возвращаемые данные сервера будут проанализированы по этому значению и переданы функции回调. Доступны значения:

  • "xml": возвращает документ XML, который можно обработать с помощью jQuery.
  • "html": возвращает информацию HTML в чистом тексте; содержащиеся в нем теги script будут выполняться при вставке в dom.
  • "script": возвращает чистый текст JavaScript кода. Результаты не будут автоматически кэшироваться,除非 был установлен параметр "cache". Замечание: при удаленных запросах (не в одной домене), все запросы POST будут преобразованы в запросы GET (поскольку будет использоваться тег script DOM).
  • "json": возвращает данные JSON .
  • "jsonp": формат JSONP. При вызове функции в формате JSONP, например "myurl?callback=?", jQuery автоматически заменяет ? на правильное имя функции, чтобы выполнить функцию回调.
  • "text": возвращает строку纯 текста
error

Тип: Функция

Значение по умолчанию: автоматическое определение (xml или html). Вызовите эту функцию при неудачном запросе.

Есть три параметра: объект XMLHttpRequest, информация об ошибке, (опционально) объект исключения,捕获ленный.

Если произошла ошибка, информация об ошибке (второй параметр) кроме null может быть "timeout", "error", "notmodified" и "parsererror".

Это Ajax-событие.

global

Тип: Логический

Инициировать ли глобальные события AJAX. Значение по умолчанию: true. Установите значение false, чтобы не инициировать глобальные события AJAX, такие как ajaxStart или ajaxStop, которые можно использовать для управления различными событиями Ajax.

ifModified

Тип: Логический

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

jsonp

Тип: Строка

В запросе jsonp перепишите имя функции回调. Это значение используется для замены части "callback" в URL параметрах GET или POST запросов типа "callback=?", например {jsonp:'onJsonPLoad'} приведет к передаче "onJsonPLoad=?" серверу.

jsonpCallback

Тип: Строка

Указывает имя回调-функции для запросов jsonp. Это значение будет использоваться вместо автоматически сгенерированного случайного имени функции jQuery. Это主要用于 генерации уникальных имен функций jQuery, что упрощает управление запросами и предоставляет возможность предоставления回调-функций и обработки ошибок. Вы также можете указать это имя回调-функции, если хотите, чтобы браузер кэшировал GET-запросы.

password

Тип: Строка

Используется для ответа на запросы аутентификации HTTP с указанием пароля

processData

Тип: Логический

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

scriptCharset

Тип: Строка

Используется только при dataType "jsonp" или "script" и type "GET" для принудительного изменения charset. Обычно используется, когда содержимое кодировки локального и удаленного контента различается.

success

Тип: Функция

回调-функция после успешного выполнения запроса.

Параметры: данные, возвращаемые сервером, обработанные в зависимости от параметра dataType; строка состояния.

Это Ajax-событие.

traditional

Тип: Логический

Если вы хотите использовать традиционный способ сериализации данных, установите значение true. См. jQuery.param в разделе Инструменты.

timeout

Тип: Число

Настройка времени ожидания запроса (миллисекунды). Эта настройка заменит глобальные настройки.

type

Тип: Строка

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

url

Тип: Строка

Значение по умолчанию: адрес текущей страницы. Адрес для отправки запроса.

username

Тип: Строка

Используется для ответа на запросы аутентификации HTTP с указанием пользователя.

xhr

Тип: Функция

Необходимо вернуть объект XMLHttpRequest. По умолчанию в IE это ActiveXObject, а в других случаях XMLHttpRequest. Используется для перезаписи или предоставления улучшенного объекта XMLHttpRequest.

Callback-функции

Чтобы обработать данные, полученные от $.ajax(), необходимо использовать callback-функции: beforeSend, error, dataFilter, success, complete.

beforeSend

Эта функция вызывается перед отправкой запроса и передается объект XMLHttpRequest.

error

Эта функция вызывается при ошибке запроса. Передаются объект XMLHttpRequest, строка, описывающая тип ошибки, и объект исключения (если есть).

dataFilter

Эта функция вызывается после успешного выполнения запроса. Передаются возвращенные данные и значение параметра dataType. И необходимо вернуть новые данные (возможно, обработанные), которые будут переданы функции success callback.

success

Этот функцию вызывают после выполнения запроса. Передаются возвращенные данные и строка, содержащая код успеха.

complete

Этот функцию вызывают после завершения запроса, независимо от успеха или неудачи. Передается объект XMLHttpRequest и строка, содержащая код успеха или ошибки.

Тип данных

Функция $.ajax() зависит от информации, предоставленной сервером, для обработки возвращаемых данных. Если сервер сообщает, что возвращаемые данные являются XML, результат можно обрабатывать с помощью обычных методов XML или выборщиков jQuery. Если видны другие типы, такие как HTML, данные будут рассмотрены как текст.

С помощью опции dataType можно指定 другие способы обработки данных. Помимо простого XML, можно指定 html, json, jsonp, script или text.

Для типов text и xml возвращаемые данные не обрабатываются. Данные просто передаются функции success callback через атрибут responseText или responseHTML XMLHttpRequest.

Внимание:Мы должны убедиться, что MIME-тип, который сообщает веб-сервер, соответствует dataType, который мы выбрали. Например, если это XML, сервер должен объявить text/xml или application/xml, чтобы получить一致альный результат.

Если указан тип html, любая вbuilt JavaScript будет выполнена до того, как HTML будет возвращен в виде строки. Аналогично, если указан тип script, сначала будет выполнен JavaScript, сгенерированный на сервере, а затем скрипт будет возвращен в виде текстовых данных.

Если указан тип json, то полученные данные будут интерпретированы как объект JavaScript, и созданный объект будет возвращен в качестве результата. Для достижения этой цели он сначала пытается использовать JSON.parse(). Если браузер не поддерживает это, используется функция для создания объекта.

JSON-данные представляют собой структурированные данные, которые можно легко парсить с помощью JavaScript. Если данные файла хранятся на удаленном сервере (домены различаются, то есть данные получены через跨доменную запросу),则需要 использовать тип jsonp. Используя этот тип, будет создан параметр строки запроса callback=?, который добавляется в конце URL запроса. Серверная сторона должна добавить имя回调 функции перед JSON-данными, чтобы выполнить эффективный запрос JSONP. Если необходимо указать имя параметра回调 функции, отличное от по умолчанию callback, можно установить параметр jsonp в $.ajax().

Внимание:JSONP - это расширение формата JSON. Оно требует наличия на сервере кода для обнаружения и обработки параметров строки запроса.

Если указан тип script или jsonp, то при получении данных от сервера используется тег <script>, а не объект XMLHttpRequest. В этом случае $.ajax() больше не возвращает объект XMLHttpRequest и не передает обработчики событий, такие как beforeSend.

Отправка данных на сервер

По умолчанию, запросы Ajax используют метод GET. Если необходимо использовать метод POST, можно установить значение параметра type. Эта опция также влияет на то, как содержимое опции data отправляется на сервер.

Опция data может содержать строку запроса, например key1=value1&key2=value2, или карту, например {key1: 'value1', key2: 'value2'}. Если используется后者, данные будут преобразованы в строку запроса перед отправкой. Этот процесс также можно избежать, установив опцию processData в false. Если необходимо отправить объект XML серверу, этот процесс может быть не подходящим. В этом случае также следует изменить значение опции contentType, используя другой подходящий MIME-тип, вместо по умолчанию application/x-www-form-urlencoded.

Дополнительные параметры

Опция global используется для предотвращения регистрации обратных вызовов, таких как .ajaxSend или ajaxError, и т.д. Это может быть полезно в некоторых случаях, например, когда отправляемые запросы очень частые и короткие, можно отключить эту опцию в ajaxSend.

Если сервер требует HTTP аутентификации, можно использовать имя пользователя и пароль для настройки через опции username и password.

Запросы Ajax ограничены по времени, поэтому после捕获 и обработки ошибки уведомления можно использовать для улучшения пользовательского опыта. Параметр timeout обычно оставляют на default, или его можно установить глобально через jQuery.ajaxSetup, редко для конкретного запроса изменяется параметр timeout.

По умолчанию запрос всегда отправляется, но браузер может извлечь данные из своего кэша. Чтобы запретить использование результатов кэша, можно установить параметр cache в false. Если вы хотите, чтобы система сообщала об ошибке, если данные с последнего запроса не изменились, можно установить ifModified в true.

scriptCharset позволяет устанавливать для запроса тега <script> специфическую кодировку, используемую для скриптов или данных jsonp. Это особенно полезно, когда кодировка скрипта и страницы различается.

Первая буква Ajax - это начальная буква слова asynchronous, что означает, что все операции выполняются параллельно, и порядок их выполнения не имеет значения. Параметр async в $.ajax() всегда установлен в true, что означает, что после начала запроса другое кодирование по-прежнему может выполняться. Категорически не рекомендуется устанавливать этот параметр в false, что означает, что все запросы больше не будут асинхронными, что также может привести к блокировке браузера.

$.ajax функция возвращает созданный ею объект XMLHttpRequest. Обычно jQuery обрабатывает и создает этот объект внутри себя, но пользователь также может передать созданный самим себе объект xhr через опцию xhr. Возвращаемый объект обычно выбрасывается, но предоставляет底层 интерфейс для наблюдения и управления запросом. Например, вызов метода .abort() на объекте может приостановить запрос до его завершения.

Руководство по jQuery Ajax