This page was translated from English by the community.Learn more and join the MDN Web Docs community.

View in EnglishAlways switch to English

XMLHttpRequest

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨июль 2015 г.⁩.

* Some parts of this feature may have varying levels of support.

Примечание: This feature is available inWeb Workers, except forService Workers.

XMLHttpRequest это API, который предоставляет клиенту функциональность для обмена данными между клиентом и сервером. Данный API предоставляет простой способ получения данных по ссылке без перезагрузки страницы. Это позволяет обновлять только часть веб-страницы не прерывая пользователя.XMLHttpRequest используется в AJAX запросах и особенно в single-page приложениях.

XMLHttpRequest изначально был разработан Microsoft и позже заимствован Mozilla, Apple, и Google. Сейчас онстандартизирован WHATWG. Несмотря на своё название,XMLHttpRequest может быть использован для получения любых типов данных, не только XML, и поддерживает протоколы помимоHTTP (включаяfile иftp).

Чтобы начать работать сXMLHttpRequest, выполните этот код:

var myRequest = new XMLHttpRequest();

более детальное описание создание объекта, можно увидеть в разделеUsing XMLHttpRequest.

Список методов объекта

`XMLHttpRequest(JSObject objParameters);`
`void abort();`
`DOMString getAllResponseHeaders();`
`DOMString? getResponseHeader(DOMString header);`
`void open(DOMString method, DOMString url, optional boolean async, optional DOMString? user, optional DOMString? password);`
`void overrideMimeType(DOMString mime);`
`void send();void send(ArrayBufferView data);void send(Blob data);void send(Document data);void send(DOMString? data);void send(FormData data);`
`void setRequestHeader(DOMString header, DOMString value);`
Нестандартные методы
`[noscript] void init(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow);`
`[noscript] void openRequest(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password);`
`void sendAsBinary(in DOMString body);`Устарело

Поля объекта

Attribute Type Description

onreadystatechange

Function?

Callback - функция, которая вызывается всякий раз, когда полеreadyState меняет своё значение. Callback выполняется в потоке работы приложения.

Внимание: Он не должен использоваться в синхронных запросах, и не должен выполняться из нативного кода (? must not be used from native code).

readyState

unsigned short

Состояние запроса:

Значение	Состояние	Описание
`0`	`UNSENT`	Клиент создан. Метод`open()` ещё не вызван.
`1`	`OPENED`	Вызван метод open`()`. В этом состоянии можно добавить заголовки через метод`setRequestHeader()`; вызов метода`send()` отправит запрос.
`2`	`HEADERS_RECEIVED`	Вызван метод`send()`, получены заголовки и код ответа (200, 404, 501 и проч.).
`3`	`LOADING`	Загрузка; если значение`responseType` равно "text" или пустой строке, то`responseText` содержит частичные данные.
`4`	`DONE`	Операция завершена. Все данные получены.

response

varies

Тело сущности запроса. Согласно полюresponseType, может бытьArrayBuffer,Blob,Document, JavaScript объектом (для "json"), или строкой. Равноnull если запрос не завершён или окончен с ошибкой.

responseTextТолько для чтения DOMString Ответ на запрос в виде строки илиnull в случае если запрос не успешен или ответ ещё не получен.

responseType

XMLHttpRequestResponseType

Может использоваться для определения типа ответа.

Value	Data type of`response` property
`""` (пустая строка)	String (строка, дефолтное значение)
`"arraybuffer"`	`ArrayBuffer`
`"blob"`	`Blob`
`"document"`	`Document`
`"json"`	JavaScript объект, полученный путём парсинга JSON строки, полученной с сервера.
`"text"`	String (строка)
`"moz-blob"`	Firefox - велосипед, который позволяет работать с частично-полученными данными`Blob` при помощи событий прогресса (progressing events). Эта штука позволяет работать с ответом от сервера, до того как он получен полностью.
`"moz-chunked-text"`	Похоже на поле`"text"`, но только находится в потоке(streaming). Это значит, что значение доступно только в промежуток времени между событиями прогресса (`"progress"` event), и содержит данные которые пришли из последнего события прогресса. Поле содержит строку, пока выполняются события прогресса. После того как ответ получен полностью, значение поля меняется на`null`. Работает только в Firefox.
`"moz-chunked-arraybuffer"`	Похоже на поле`"arraybuffer"`, но только находится в потоке(streaming). Это значит, что значение доступно только в промежуток времени между событиями прогресса (`"progress"` event), и содержит данные которые пришли из последнего события прогресса. Поле содержит строку, пока выполняются события прогресса. После того как ответ получен полностью, значение поля меняется на`null`. Работает только в Firefox.

Note: Starting with Gecko 11.0 , as well as WebKit build 528, these browsers no longer let you use theresponseType attribute when performing synchronous requests. Attempting to do so throws anNS_ERROR_DOM_INVALID_ACCESS_ERR exception. This change has been proposed to the W3C for standardization.

responseXMLТолько для чтения

Document?

Ответ является объектом DOMDocument, илиnull в случае если запрос окончился ошибкой, или ответ не получен полностью, или если ответ невозможно распарсить какXML или HTML. Ответ парсится как если бы это былtext/xml stream. Когда значениеresponseType равно"document" и запрос выполнен асинхронно, ответ парсится какtext/html stream.

Примечание: Если сервер не работает с заголовком (не присылает в ответе) "Content-type:text/xml", то можно использовать методoverrideMimeType() для того чтобы парсить получаемый ответ какXML.

statusТолько для чтения unsigned short Статус ответа на запрос. Равен кодам HTTP (200 - успешно, 404 не найдено, 301 - перенесено навсегда).

statusTextТолько для чтения DOMString Строка статуса ответа. В отличи от поляstatus, эта строка включает в себя текст - ("200 OK", например).

timeout

unsigned long

Время в миллисекундах, после которого запрос будет отменён. Значение 0 (по умолчанию) значит что таймаута не будет. Никогда.

Примечание: Вы можете не использовать поле timeout для синхронных запросов из owning window.

ontimeout

Function

Колбэк-функция которая будет вызвана в случае таймаута.

upload XMLHttpRequestUpload Загрузка (upload process) может отслеживаться обработчиком события.

withCredentials

boolean

Определяет что cross-site запрос, согласноAccess-Control должен использовать авторизацию (креды для логина и пароля) через куки, или заголовок с авторизационными данными. По умолчанию false.

Примечание: Не влияет на same-site запросы.

Примечание: Начиная с Gecko 11.0 , Gecko больше не позволяет использовать полеwithCredentials при выполнении синхронных запросов. Попытка выполнить это выбрасываетNS_ERROR_DOM_INVALID_ACCESS_ERR исключение.

Нестандартные свойства

Attribute	Type	Description
`channel`Только для чтения	`nsIChannel`	The channel used by the object when performing the request. This is`null` if the channel hasn't been created yet. In the case of a multi-part request, this is the initial channel, not the different parts in the multi-part request.Requires elevated privileges to access.
`mozAnon`Только для чтения	`boolean`	Если значение равно true, запрос отправляется без куки и заголовков авторизации.
`mozSystem`Только для чтения	`boolean`	Если значение равно true, same origin policy не будут использоваться в запросе (кроссдоменный запрос не сработает).
`mozBackgroundRequest`	`boolean`	Этот метод не может быть вызван из контекста страницы. Для того чтобы воспользоваться им нужны повышенные привелегии (elevated privileges). Флаг, означающий что запрос от пользователя надо скрыть. Для пользователя не появится никаких сообщений и/или оповещений что запрос вообще был. В случае, если для продолжения запроса нужна какая-то аутентификация, и в других случаях было бы отображено оповещение, этот запрос просто не сработает. Note: Этот флаг должен быть выставлен до вызова метода`open()`.
`mozResponseArrayBuffer`Только для чтения	`ArrayBuffer`	Массив, в который ляжет ответ от сервера, если ответ приходит в виде Javascript массива ([]). В случае, если запрос не удалось завершить, или если запрос не был отправлен, то это поле будет null.
`multipart`	`boolean`	This Gecko-only feature was removed in Firefox/Gecko 22. Please useServer-Sent Events,Web Sockets, or`responseText` from progress events instead. Indicates whether or not the response is expected to be a stream of possibly multiple XML documents. If set to`true`, the content type of the initial response must be`multipart/x-mixed-replace` or an error will occur. All requests must be asynchronous. This enables support for server push; for each XML document that's written to this request, a new XML DOM document is created and the`onload` handler is called between documents. Note: When this is set, the`onload` handler and other event handlers are not reset after the first XMLdocument is loaded, and the`onload` handler is called after each part of the response is received.

Конструктор

XMLHttpRequest()

Конструктор создаёт объект XMLHttpRequest. Он должен быть вызван перед обращением к любому методу класса.

Gecko/Firefox 16 добавляет нестандартные параметры в конструктор, для лучшего взаимодействия с режимом инкогнито, (смотриBug 692677). Установка флагаmozAnon в значениеtrue создаёт сущностьAnonXMLHttpRequest() описанную в XMLHttpRequest спецификации, но не реализованную не в одном из браузеров (информация сентября 2012).

XMLHttpRequest (  JSObject objParameters);

Параметры (нестандартные)

objParameters

Вы можете использовать два флага:

mozAnon: Boolean: Использование этого флага уберёт из запроса заголовки origin, иuser credentials. Кроме этого, куки не будут отправлены в запросе, если только они не будут добавлены к запросу специально, через метод setRequestHeader.
mozSystem: Boolean: Если выставить этот флаг в значениеtrue то это позволит делать cross-доменные запросы без необходимости получения специальных заголовков со стороны сервера (CORS). Для использования этого флага необходимо использовать дополнительный флаг*mozAnon: true, поскольку для отправки запроса на другой домен, нельзя использовать куки и креды пользователя. Этот флагработает только с привилегированными (одобренными) приложениями; он не сработает с произвольно загруженными страницами.*

Методы

abort()

Отменяет запрос, если он был отправлен.

getAllResponseHeaders()

DOMString getAllResponseHeaders();

Возвращает все заголовки ответа как строку, илиnull если ответ не был получен. Для multypart запросов возвращает заголовки текущей части запроса, а не всего канала.

getResponseHeader()

DOMString? getResponseHeader(DOMString header);

Возвращает значение указанного заголовка из полученного ответа, илиnull в случает если ответ не получен, или такого заголовка в ответе нет. Возвращаемая строка имеет кодировку UTF.

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

open()

Инициализирует запрос. Этот метод может (и должен) быть вызван из JavaScript-кода; если необходимо вызвать запрос из нативного кода, то нужно использовать методopenRequest().

Примечание:Вызов этого метода из активного запроса (если методopen() илиopenRequest() уже были вызваны) эквивалентно вызову методаabort().

void open(   DOMString method,   DOMString url,   optional boolean async,   optional DOMString user,   optional DOMString password);

Параметры

method: HTTP метод отправки сообщения - "GET", "POST", "PUT", "DELETE", и проч.. Ignored for non-HTTP(S) URLs.
url: URL адрес, на который будет отправлено сообщение.
async: Необязательный boolean параметр, по умолчанию равныйtrue. Определяет, будет ли запрос отправлен асинхронно. Если значение равноfalse, методsend() вернёт ответ в общем потоке работы приложения (иначе говоря, приложение зависнет на некоторое время), в противном случае, ответ может быть получен только при помощи определённых обработчиков событий. В случае, если используется отправкаmultipart запроса, то этот атрибутдолжен бытьtrue, или будет выброшено исключение.
Примечание:Начиная с Gecko 30.0, синхронные запросы объявлены как deprecated, в силу того что все пользователи недовольны тем, что приложение "зависает".
user: Необязательный параметр, используется для аутентификации пользователя. По умолчанию, пустая строка.
password: Необязательный параметр, используется для аутентификации пользователя. По умолчанию пустая строка.

overrideMimeType()

Переопределяет MIME тип, получаемый от сервера. Это может быть использовано, например, для того чтобы получить и распарсить данные в формате text/xml, даже, если сервер сообщает что это не так. Этот метод должен быть вызван перед вызовом методаsend().

void overrideMimeType(DOMString mimetype);

send()

Отправляет запрос. Если запрос асинхронный (а по умолчанию это так), этот метод вернёт значение сразу после того как метод вызван.

Примечание:В этом случае, в ответе не будет содержаться информации, которая пришла с сервера, поскольку она ещё не пришла. Для того чтобы получить эту информацию, нужно слушать события загрузки, или использовать promise.

Если запрос синхронный, то метод вернёт значение только после того, как придёт запрос от сервера.

Примечание:Все необходимые обработчики событий должны быть установлены перед вызовомsend().

Примечание:Лучше не использовать параметр ArrayBuffer. Сейчас он не входит в спецификациюXMLHttpRequest. Вместо него можно использовать ArrayBufferView (смотри таблицу совместимости для различных версий).

void send();void send(ArrayBuffer data);void send(ArrayBufferView data);void send(Blob data);void send(Document data);void send(DOMString? data);void send(FormData data);

Примечания

Если типdata -Document, то он будет сериализован перед отправкой. Firefox до версии 3 всегда отправляет такой запрос в кодировке UTF-8;Firefox 3 отправляет данные в той кодировке, которая указаны вbody.xmlEncoding, или UTF-8 если такой информации нет.

If it's annsIInputStream, it must be compatible withnsIUploadChannel'ssetUploadStream() method. In that case, a Content-Length header is added to the request, with its value obtained usingnsIInputStream'savailable() method. Any headers included at the top of the stream are treated as part of the message body. The stream's MIMEtype should be specified by setting the Content-Type header using thesetRequestHeader() method prior to callingsend().

The best way to send binary content (like in files upload) is using anArrayBufferView orBlobs in conjuncton with thesend() method. However, if you want to send astringifiable raw data, use thesendAsBinary() method instead, or theStringView Non native typed arrays superclass.

setRequestHeader()

Устанавливает значение заголовка HTTP-запроса. Вы должны вызватьsetRequestHeader() послеopen(), но передsend(). Если данный метод вызывается несколько раз с одним и тем же заголовком, все значения объединяются в один заголовок запроса.

void setRequestHeader(   DOMString header,   DOMString value);

Параметры

header: Имя заголовка, значение которого будет установлено.
value: Значение, заданное как тело заголовка.

Нестандартные методы

init()

Инициализирует объект для использования с C++ кодом.

Предупреждение:Этот методнельзя вызывать из JavaScript.

[noscript] void init(   in nsIPrincipal principal,   in nsIScriptContext scriptContext,   in nsPIDOMWindow ownerWindow);

Параметры

principal: Принцип, используемый для запроса; не должен бытьnull.
scriptContext: Контекст скрипта, используемого для запроса; не должен бытьnull.
ownerWindow: Окно, связанное с запросом; может бытьnull.

openRequest()

Инициализирует запрос. Этот метод должен использоваться из собственного кода; для инициализации запроса из кода JavaScript вместо этого используйте используйтеopen() метод. Смотрите документацию дляopen().

sendAsBinary()Устарело

Вариант методаsend() который посылает бинарные данные.

Примечание:Этот нестандартный метод считается устарелым по состоянию на Gecko 31, и со временем будет удалён. Взамен может использоваться стандарт методаsend(Blob data).

void sendAsBinary(   in DOMString body);

Данный метод используется в сочетании с методомreadAsBinaryString, который присутствует в FileReader API, и позволяетпрочитать изагрузить файл любого типа и превратить необработанные данные вJSON-строку.

Параметры

body: Тело запроса в видеDOMstring. Эти данные конвертированы в строку с однобайтовыми символами с помощью усечения (удаления байта с высоким порядком в каждом символе).

`sendAsBinary()` polyfill

SincesendAsBinary() is an experimental feature, here isa polyfill for browsers thatdon't support thesendAsBinary() method but supporttyped arrays.

/*\|*||*|  :: XMLHttpRequest.prototype.sendAsBinary() Polyfill ::|*||*|  https://developer.mozilla.org/ru/docs/DOM/XMLHttpRequest#sendAsBinary()|*|\*/if (!XMLHttpRequest.prototype.sendAsBinary) {  XMLHttpRequest.prototype.sendAsBinary = function (sData) {    var nBytes = sData.length,      ui8Data = new Uint8Array(nBytes);    for (var nIdx = 0; nIdx < nBytes; nIdx++) {      ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff;    }    /* send as ArrayBufferView...: */    this.send(ui8Data);    /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */  };}

Примечание:It's possible to build this polyfill putting two types of data as argument forsend(): anArrayBuffer (ui8Data.buffer – the commented code) or anArrayBufferView (ui8Data, which is atyped array of 8-bit unsigned integers – uncommented code). However, on Google Chrome, when you try to send anArrayBuffer, the following warning message will appear:ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead. Another possible approach to send binary data is theStringView Non native typed arrays superclass in conjunction with thesend() method.

Notes

By default, Firefox 3 limits the number ofXMLHttpRequest connections per server to 6 (previous versions limit this to 2 per server). Some interactive web sites may keep anXMLHttpRequest connection open, so opening multiple sessions to such sites may result in the browser hanging in such a way that the window no longer repaints and controls don't respond. This value can be changed by editing thenetwork.http.max-persistent-connections-per-server preference inabout:config.
From Gecko 7.0 headers set bysetRequestHeader are sent with the request when following a redirect. Previously these headers would not be sent.
XMLHttpRequest is implemented in Gecko using thensIXMLHttpRequest,nsIXMLHttpRequestEventTarget, andnsIJSXMLHttpRequest interfaces.
When a request reaches its timeout value, a "timeout" event is raised.

Events

onreadystatechange as a property of theXMLHttpRequest instance is supported in all browsers.

Since then, a number of additional event handlers were implemented in various browsers (onload,onerror,onprogress, etc.). These are supported in Firefox. In particular, seensIXMLHttpRequestEventTarget andUsing XMLHttpRequest.

More recent browsers, including Firefox, also support listening to theXMLHttpRequest events via standardaddEventListener APIs in addition to settingon* properties to a handler function.

Permissions

When using System XHR via themozSystem property, for example for Firefox OS apps, you need to be sure to add thesystemXHR permission into your manifest file. System XHR can be used in privileged or certified apps.