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 the responseType attribute when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR exception. This change has been proposed to the W3C for standardization.
responseXML Только для чтения	Document?	Ответ является объектом DOM Document, или 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 use Server-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().

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, или будет выброшено исключение.

user

Необязательный параметр, используется для аутентификации пользователя. По умолчанию, пустая строка.

password

Необязательный параметр, используется для аутентификации пользователя. По умолчанию пустая строка.

overrideMimeType()

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

void overrideMimeType(DOMString mimetype);

send()

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

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

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 an nsIInputStream, it must be compatible with nsIUploadChannel's setUploadStream() method. In that case, a Content-Length header is added to the request, with its value obtained using nsIInputStream's available() 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 the setRequestHeader() method prior to calling send().

The best way to send binary content (like in files upload) is using an ArrayBufferView or Blobs in conjuncton with the send() method. However, if you want to send a stringifiable raw data, use the sendAsBinary() method instead, or the StringView Non native typed arrays superclass.

setRequestHeader()

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

void setRequestHeader( DOMString header, DOMString value ); Параметры header

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

value

Значение, заданное как тело заголовка.

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

init()

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

[noscript] void init( in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow ); Параметры principal

Принцип, используемый для запроса; не должен быть null.

scriptContext

Контекст скрипта, используемого для запроса; не должен быть null.

ownerWindow

Окно, связанное с запросом; может быть null.

openRequest()

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

sendAsBinary()

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

void sendAsBinary( in DOMString body );

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

Параметры body

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

sendAsBinary() polyfill

Since sendAsBinary() is an experimental feature, here is a polyfill for browsers that don't support the sendAsBinary() method but support typed arrays.

Notes

• By default, Firefox 3 limits the number of XMLHttpRequest connections per server to 6 (previous versions limit this to 2 per server). Some interactive web sites may keep an XMLHttpRequest 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 the network.http.max-persistent-connections-per-server preference in about:config.
• From Gecko 7.0 headers set by setRequestHeader are sent with the request when following a redirect. Previously these headers would not be sent.
• XMLHttpRequest is implemented in Gecko using the nsIXMLHttpRequest, nsIXMLHttpRequestEventTarget, and nsIJSXMLHttpRequest interfaces.
• When a request reaches its timeout value, a "timeout" event is raised.

Events

onreadystatechange as a property of the XMLHttpRequest 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, see nsIXMLHttpRequestEventTarget and Using XMLHttpRequest.

More recent browsers, including Firefox, also support listening to the XMLHttpRequest events via standard addEventListener APIs in addition to setting on* properties to a handler function.

Permissions

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

Совместимость с браузерами

Enable JavaScript to view this browser compatibility table.

Смотрите также

• MDN articles about XMLHttpRequest:

  • AJAX - Getting Started
  • Using XMLHttpRequest
  • HTML in XMLHttpRequest
  • FormData

• XMLHttpRequest references from W3C and browser vendors:

  • W3C: XMLHttpRequest (base features)
  • W3C: XMLHttpRequest (latest editor's draft with extensions to the base functionality, formerly XMLHttpRequest Level 2
  • Microsoft documentation
  • Apple developers' reference

• "Using the XMLHttpRequest Object" (jibbering.com)

• XMLHttpRequest - REST and the Rich User Experience

• HTML5 Rocks - New Tricks in XMLHttpRequest2

• Thread on the naming convention of XMLHttpRequest

• Chrome scope availability - how to access from JSM modules etc which do not have access to DOM

  • Components.utils.importGlobalProperties
  • nsIXMLHttpRequest [en-US]