XMLHttpRequest defines an API that provides scripted client functionality for transferring data between a client and a server.
XMLHttpRequest
responseURL
attributestatus
attributestatusText
attributegetResponseHeader()
methodgetAllResponseHeaders()
methodoverrideMimeType()
methodresponseType
attributeresponse
attributeresponseText
attributeresponseXML
attributeFormData
ProgressEvent
This section is non-normative.
The XMLHttpRequest
object is an API for
fetching resources.
The name XMLHttpRequest
is historical and has no bearing on its
functionality.
Some simple code to do something with data from an XML document fetched over the network:
function processData(data) {
// taking care of data
}
function handler() {
if(this.status == 200 &&
this.responseXML != null &&
this.responseXML.getElementById('test').textContent) {
// success!
processData(this.responseXML.getElementById('test').textContent);
} else {
// something went wrong
…
}
}
var client = new XMLHttpRequest();
client.onload = handler;
client.open("GET", "unicorn.xml");
client.send();
If you just want to log a message to the server:
function log(message) {
var client = new XMLHttpRequest();
client.open("POST", "/log");
client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
client.send(message);
}
Or if you want to check the status of a document on the server:
function fetchStatus(address) {
var client = new XMLHttpRequest();
client.onload = function() {
// in case of network errors this might not give reliable results
returnStatus(this.status);
}
client.open("HEAD", address);
client.send();
}
The XMLHttpRequest
object was initially defined as part of
the WHATWG's HTML effort. (Based on Microsoft's implementation many years prior.)
It moved to the W3C in 2006. Extensions (e.g. progress events and
cross-origin requests) to XMLHttpRequest
were developed in a
separate draft (XMLHttpRequest Level 2) until end of 2011, at which point
the two drafts were merged and XMLHttpRequest
became a single
entity again from a standards perspective. End of 2012 it moved back to the
WHATWG.
Discussion that led to the current draft can be found in the following mailing list archives:
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this specification are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
User agents, Working Groups, and other interested parties are strongly encouraged to discuss new features with the WHATWG community.
This specification uses terminology, cross-linked throughout, from DOM, DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, HTTP, URL, Web IDL, and XML. [DOM] [DOMPS] [ENCODING] [FETCH] [FILEAPI] [HTML] [HTTP] [URL] [WEBIDL] [XML] [XMLNS]
It uses the typographic conventions from HTML. [HTML]
The term user credentials for the purposes of this
specification means cookies, HTTP authentication, and TLS client certificates.
Specifically it does not refer to proxy authentication or the
Origin
header.
[COOKIES]
XMLHttpRequest
[Exposed=(Window,DedicatedWorker,SharedWorker)] interface XMLHttpRequestEventTarget : EventTarget { // event handlers attribute EventHandler onloadstart; attribute EventHandler onprogress; attribute EventHandler onabort; attribute EventHandler onerror; attribute EventHandler onload; attribute EventHandler ontimeout; attribute EventHandler onloadend; }; [Exposed=(Window,DedicatedWorker,SharedWorker)] interface XMLHttpRequestUpload : XMLHttpRequestEventTarget { }; enum XMLHttpRequestResponseType { "", "arraybuffer", "blob", "document", "json", "text" }; [Constructor, Exposed=(Window,DedicatedWorker,SharedWorker)] interface XMLHttpRequest : XMLHttpRequestEventTarget { // event handler attribute EventHandler onreadystatechange; // states const unsigned short UNSENT = 0; const unsigned short OPENED = 1; const unsigned short HEADERS_RECEIVED = 2; const unsigned short LOADING = 3; const unsigned short DONE = 4; readonly attribute unsigned short readyState; // request void open(ByteString method, USVString url); void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null); void setRequestHeader(ByteString name, ByteString value); attribute unsigned long timeout; attribute boolean withCredentials; [SameObject] readonly attribute XMLHttpRequestUpload upload; void send(optional (Document or BodyInit)? body = null); void abort(); // response readonly attribute USVString responseURL; readonly attribute unsigned short status; readonly attribute ByteString statusText; ByteString? getResponseHeader(ByteString name); ByteString getAllResponseHeaders(); void overrideMimeType(DOMString mime); attribute XMLHttpRequestResponseType responseType; readonly attribute any response; readonly attribute USVString responseText; [Exposed=Window] readonly attribute Document? responseXML; };
An XMLHttpRequest
object has an associated
XMLHttpRequestUpload
object.
An XMLHttpRequest
object has an associated
state, which is one of
unsent,
opened,
headers received,
loading, and
done. Unless stated otherwise it is unsent.
An XMLHttpRequest
object has an associated
send()
flag. Unless stated otherwise it is unset.
An XMLHttpRequest
object has an associated stop timeout flag.
Unless stated otherwise it is unset.
client = new XMLHttpRequest()
XMLHttpRequest
object.
The XMLHttpRequest()
constructor, when
invoked, must return a new XMLHttpRequest
object.
An XMLHttpRequest
object must not be garbage collected if its
state is either
opened with the send()
flag set,
headers received, or loading, and it has one or more
event listeners
registered whose type is one of
readystatechange
,
progress
,
abort
,
error
,
load
,
timeout
, and
loadend
.
If an XMLHttpRequest
object is garbage collected while its
connection is still open, the user agent must terminate the request.
The following are the
event handlers (and their corresponding
event handler event types)
that must be supported on objects implementing an interface that inherits
from XMLHttpRequestEventTarget
as attributes:
event handler | event handler event type |
---|---|
onloadstart
| loadstart
|
onprogress
| progress
|
onabort
| abort
|
onerror
| error
|
onload
| load
|
ontimeout
| timeout
|
onloadend
| loadend
|
The following is the
event handler
(and its corresponding
event handler event type) that must be
supported as attribute solely by the
XMLHttpRequest
object:
event handler | event handler event type |
---|---|
onreadystatechange
| readystatechange |
client . readyState
Returns client's state.
The readyState
attribute's getter must return the value from the table below in the cell of the second
column, from the row where the value in the cell in the first column is
context object's
state:
unsent | UNSENT (numeric value 0)
| The object has been constructed. |
opened | OPENED (numeric value 1)
| The open() method has been successfully
invoked. During this state request headers can be set using
setRequestHeader() and the
fetch can be initiated using the send()
method.
|
headers received | HEADERS_RECEIVED
(numeric value 2)
| All redirects (if any) have been followed and all HTTP headers of the response have been received. |
loading | LOADING (numeric value 3)
| The response's body is being received. |
done | DONE (numeric value 4)
| The data transfer has been completed or something went wrong during the transfer (e.g. infinite redirects). |
Each XMLHttpRequest
object has the following
request-associated concepts:
request method,
request URL,
author request headers,
request body,
synchronous flag,
upload complete flag, and
upload listener flag.
The author request headers is an initially empty header list.
The request body is initially null.
The synchronous flag, upload complete flag, and upload listener flag are initially unset.
To terminate the request,
terminate the
fetch algorithm operated by the
XMLHttpRequest
object with reason fatal.
open()
methodclient . open(method, url [, async = true [, username = null [, password = null]]])
Sets the request method, request URL, and synchronous flag.
Throws a SyntaxError
exception if
either method is not a valid HTTP method or
url cannot be parsed.
Throws a SecurityError
exception
if method is a case-insensitive match for
`CONNECT
`, `TRACE
` or `TRACK
`.
Throws an InvalidAccessError
exception if async is false,
entry settings object's
global object is a Window
object, and the timeout
attribute is not zero or the
responseType
attribute is not the empty string.
Synchronous XMLHttpRequest
outside of workers is in the process of being removed from the web platform as it has
detrimental effects to the end user's experience. (This is a long process that takes many
years.) Developers must not pass false for the async argument when
entry settings object's
global object is a Window
object. User agents are strongly encouraged to warn about such usage in developer tools and may
experiment with throwing an
InvalidAccessError
exception when it occurs.
The
open(method, url, async, username, password)
method, when invoked, must run these steps:
If context object's
relevant settings object has a
responsible document and it is not
fully active,
throw an InvalidStateError
exception.
If method is a forbidden method,
throw a
SecurityError
exception.
Normalize method.
Let parsedURL be the result of parsing url with context object's relevant settings object's API base URL.
If parsedURL is failure,
throw a
SyntaxError
exception.
If the async argument is omitted, set async to true, and set username and password to null.
Unfortunately legacy content prevents treating the async
argument being undefined
identical from it being omitted.
If parsedURL's host is non-null, run these substeps:
If the username argument is not null, set the username given parsedURL and username.
If the password argument is not null, set the password given parsedURL and password.
If async is false, entry settings object's
global object is a Window
object, and the timeout
attribute value is not zero
or the responseType
attribute value is not the
empty string, then throw an
InvalidAccessError
exception.
A fetch can be ongoing at this point.
Set variables associated with the object as follows:
Unset the send()
flag, stop timeout flag, and
upload listener flag.
Set request method to method.
Set request URL to parsedURL.
Set the synchronous flag, if async is false, and unset the synchronous flag otherwise.
Empty author request headers.
Set response to a network error.
Set received bytes to the empty byte sequence.
Set response ArrayBuffer
object to null.
Set response Blob
object to null.
Set response Document
object to null.
Set response JSON object to null.
If the state is not opened, run these substeps:
Set state to opened.
Fire an event named readystatechange
.
setRequestHeader()
methodclient . setRequestHeader(name, value)
Combines a header in author request headers.
Throws an InvalidStateError
exception if either state is not
opened or the send()
flag is set.
Throws a SyntaxError
exception if
name is not a header name or if value is not a header value.
As indicated in the algorithm below certain headers cannot
be set and are left up to the user agent. In addition there are certain
other headers the user agent will take control of if they are not set by
the author as indicated at the end of the
send()
method section.
The
setRequestHeader(name, value)
method must run these steps:
If state is not
opened, throw an
InvalidStateError
exception.
If the send()
flag is set,
throw an
InvalidStateError
exception.
Normalize value.
If name is not a
name or value
is not a value,
throw a
SyntaxError
exception.
Terminate these steps if name is a forbidden header name.
Combine name/value in author request headers.
Some simple code demonstrating what happens when setting the same header twice:
// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send();
// …results in the following header being sent:
X-Test: one, two
timeout
attributeclient . timeout
Can be set to a time in milliseconds. When set to a non-zero value
will cause fetching to
terminate after the given time has passed. When the time has passed, the request has
not yet completed, and the synchronous flag is unset, a
timeout
event will then be
dispatched,
or a TimeoutError
exception will be
thrown otherwise
(for the send()
method).
When set: throws an
InvalidAccessError
exception if
the synchronous flag is set and
entry settings object's
global object is a Window
object.
The
timeout
attribute must return its value. Initially its value must be zero.
Setting the timeout
attribute must run these steps:
If entry settings object's
global object is a Window
object and the synchronous flag is set,
throw an
InvalidAccessError
exception.
Set its value to the new value.
This implies that the
timeout
attribute can be
set while fetching is in
progress. If that occurs it will still be measured relative to the start
of fetching.
withCredentials
attributeclient . withCredentials
True when user credentials are to be included in a cross-origin request. False when they are to be excluded in a cross-origin request and when cookies are to be ignored in its response. Initially false.
When set: throws an
InvalidStateError
exception if
state is not unsent or
opened, or if the send()
flag is set.
The
withCredentials
attribute must return its value. Initially its value must be false.
Setting the
withCredentials
attribute must run these steps:
If state is not
unsent or opened,
throw an
InvalidStateError
exception.
If the send()
flag is set,
throw an
InvalidStateError
exception.
Set the withCredentials
attribute's value to the given value.
The withCredentials
attribute has no effect when
fetching
same-origin resources.
upload
attributeclient . upload
Returns the associated XMLHttpRequestUpload
object. It can be used to gather transmission information when data is
transferred to a server.
The
upload
attribute must return the associated
XMLHttpRequestUpload
object.
As indicated earlier, each XMLHttpRequest
object has an associated XMLHttpRequestUpload
object.
send()
methodclient . send([body = null])
Initiates the request. The optional argument provides the
request body. The argument is ignored if
request method is GET
or
HEAD
.
Throws an InvalidStateError
exception if either
state is not opened or the
send()
flag is set.
The send(body)
method must run these steps:
If state is not
opened, throw an
InvalidStateError
exception.
If the send()
flag is set,
throw an
InvalidStateError
exception.
If the request method is GET
or
HEAD
, set body to null.
If body is null, go to the next step.
Otherwise, let encoding be null, Content-Type be null, and then follow these rules, depending on body:
Document
Set encoding to `UTF-8
`.
If body is an HTML document, set
Content-Type to `text/html
`, and set Content-Type
to `application/xml
` otherwise. Then append `;charset=UTF-8
`
to Content-Type.
Set request body to body, serialized with the require well-formed flag set, converted to Unicode, and utf-8 encoded. Rethrow any exceptions.
If body cannot be
serialized, an
InvalidStateError
exception is thrown.
BodyInit
If body is a string, set encoding to
`UTF-8
`.
Set request body and Content-Type to the result of extracting body.
If Content-Type is non-null and author request headers
contains no header
named
`Content-Type
`,
append
`Content-Type
`/Content-Type to
author request headers.
Otherwise, if the header
named
`Content-Type
` in author request headers has a
value that is a
valid MIME type, which has a
`charset
` parameter whose value is not a case-insensitive
match for encoding, and encoding
is not null, then set all the `charset
` parameters whose value is not a
case-insensitive match for encoding of that
`Content-Type
`
header's
value to
encoding.
If one or more event listeners are registered on the associated
XMLHttpRequestUpload
object, then set upload listener flag.
Let req be a new request, initialized as follows:
cors
"
withCredentials
attribute value is true, "include
", and "same-origin
"
otherwise.
Unset the upload complete flag.
If req's body is null, set the upload complete flag.
Set the send()
flag.
If the synchronous flag is unset, run these substeps:
Fire a progress event named loadstart
with 0 and 0.
If the upload complete flag is unset and upload listener flag is
set, then fire a progress event named
loadstart
on the
XMLHttpRequestUpload
object with 0 and req's
body's
total bytes.
Fetch req. Handle the tasks queued on the networking task source per below.
Run these subsubsteps in parallel:
Let milliseconds be zero.
Every millisecond, as long as the stop timeout flag is unset, queue a microtask to run these subsubsubsteps:
To process request body for request, run these subsubsteps:
If not roughly 50ms have passed since these subsubsteps were last invoked, terminate these subsubsteps.
If upload listener flag is set, then
fire a progress event named
progress
on the
XMLHttpRequestUpload
object with request's
body's
transmitted bytes and
request's
body's
total bytes.
These subsubsteps are only invoked when new bytes are transmitted.
To process request end-of-body for request, run these subsubsteps:
Set the upload complete flag.
If upload listener flag is unset, then terminate these subsubsteps.
Let transmitted be request's body's transmitted bytes.
Let length be request's body's total bytes.
Fire a progress event named
progress
on the
XMLHttpRequestUpload
object with transmitted and
length.
Fire a progress event named
load
on the
XMLHttpRequestUpload
object with transmitted and
length.
Fire a progress event named
loadend
on the
XMLHttpRequestUpload
object with transmitted and
length.
To process response for response, run these subsubsteps:
If the stop timeout flag is unset, set the stop timeout flag.
Set response to response.
Handle errors for response.
If response is a network error, return.
Set state to headers received.
Fire an event named
readystatechange
.
If state is not headers received, then return.
If response's body is null, then run handle response end-of-body and return.
Let reader be the result of getting a reader from response's body's stream.
This operation will not throw an exception.
Let read be the result of reading a chunk from response's body's stream with reader.
When read is fulfilled with an object whose done
property is false
and whose value
property is a Uint8Array
object, run these
subsubsubsteps and then run the above subsubstep again:
Append the value
property to received bytes.
If not roughly 50ms have passed since these subsubsubsteps were last invoked, then terminate these subsubsubsteps.
Fire an event named
readystatechange
.
Web compatibility is the reason
readystatechange
fires more often than
state changes.
Fire a progress event named
progress
with response's
body's
transmitted bytes and
response's body's
total bytes.
When read is fulfilled with an object whose done
property is true,
run handle response end-of-body for response.
When read is rejected with an exception, run handle errors for response.
Otherwise, if the synchronous flag is set, run these substeps:
Let response be the result of fetching req.
If the timeout
attribute value is not
zero, terminate this
fetch if it has not returned
within the amount of milliseconds from the
timeout
attribute value with reason
timeout.
If response's body is null, then run handle response end-of-body and return.
Let reader be the result of getting a reader from response's body's stream.
This operation will not throw an exception.
Let promise be the result of reading all bytes from response's body's stream with reader.
Wait for promise to be fulfilled or rejected.
If promise is fulfilled with bytes, then append bytes to received bytes.
Run handle response end-of-body for response.
To handle response end-of-body for response, run these steps:
If the synchronous flag is set, set response to response.
Handle errors for response.
If response is a network error, return.
If the synchronous flag is unset, update response's body using response.
Fire a progress event named
progress
with transmitted and length.
Set state to done.
Unset the send()
flag.
Fire an event named readystatechange
.
Let transmitted be response's body's transmitted bytes.
Let length be response's body's total bytes.
Fire a progress event named load
with transmitted and length.
Fire a progress event named loadend
with transmitted and length.
To handle errors for response run these steps:
If the send()
flag is unset, return.
If response is a
network error, run the
request error steps for event error
and
exception NetworkError
.
Otherwise, if response has a termination reason:
Run the request error steps for event
abort
and exception
AbortError
.
Set state to done.
Unset the send()
flag.
Set response to a network error.
Run the request error steps for event
timeout
and exception
TimeoutError
.
The request error steps for event event and optionally an exception exception are:
Set state to done.
Unset the send()
flag.
Set response to a network error.
If the synchronous flag is set, throw an exception exception.
Fire an event named readystatechange
.
At this point it is clear that the synchronous flag is unset.
If the upload complete flag is unset, follow these substeps:
Set the upload complete flag.
If upload listener flag is unset, then terminate these substeps.
Fire a progress event named
event on the XMLHttpRequestUpload
object with 0 and 0.
Fire a progress event named
loadend
on the XMLHttpRequestUpload
object with 0 and 0.
Fire a progress event named event with 0 and 0.
Fire a progress event named
loadend
with 0 and 0.
abort()
methodclient . abort()
The abort()
method, when invoked, must
run these steps:
If state is either
opened with the send()
flag set,
headers received, or loading, run the
request error steps for event abort
.
If state is done, set state to unsent.
No readystatechange
event
is dispatched.
An XMLHttpRequest
has an associated response. Unless stated
otherwise it is a
network error.
An XMLHttpRequest
also has an associated received bytes (a byte
sequence). Unless stated otherwise it is the empty byte sequence.
responseURL
attributeThe responseURL
attribute
must return the empty string if response's
url is null and its
serialization with the
exclude fragment flag set otherwise.
status
attributeThe
status
attribute must return the response's
status.
statusText
attributeThe
statusText
attribute must return the response's
status message.
getResponseHeader()
methodThe
getResponseHeader(name)
method must run these steps:
If response's header list has no header whose name is name, then return null.
Return the combined value given name and response's header list.
The Fetch Standard filters response's header list. [FETCH]
For the following script:
var client = new XMLHttpRequest();
client.open("GET", "unicorns-are-teh-awesome.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == this.HEADERS_RECEIVED) {
print(client.getResponseHeader("Content-Type"));
}
}
The print()
function will get to process something
like:
text/plain; charset=UTF-8
getAllResponseHeaders()
methodThe
getAllResponseHeaders()
method, when invoked, must run these steps:
Let output be an empty byte sequence.
Let headers be the result of running sort and combine with response's header list.
For each header in headers, run these substeps:
Return output.
The Fetch Standard filters response's header list. [FETCH]
For the following script:
var client = new XMLHttpRequest();
client.open("GET", "narwhals-too.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == this.HEADERS_RECEIVED) {
print(this.getAllResponseHeaders());
}
}
The print()
function will get to process something
like:
Date: Sun, 24 Oct 2004 04:58:38 GMT
Server: Apache/1.3.31 (Unix)
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8
The response MIME type is the
MIME type the `Content-Type
` header contains excluding any
parameters and
converted to ASCII lowercase, or null if
the response header can not be parsed or was omitted. The
override MIME type is initially null
and can get a value if
overrideMimeType()
is invoked. Final MIME type is the
override MIME type unless that is null in which case it is
the response MIME type.
The response charset is the value of
the charset
parameter of the `Content-Type
` header
or null if there was no `charset
` parameter or the header could
not be parsed or was omitted. The
override charset is initially null and
can get a value if overrideMimeType()
is invoked.
Final charset is the
override charset unless
that is null in which case it is the response charset.
An XMLHttpRequest
object has an associated
response ArrayBuffer
object,
response Blob
object,
response Document
object, and a
response JSON object. Their shared initial value is null.
An arraybuffer response is the return value of these steps:
If response ArrayBuffer
object is non-null, return it.
Set response ArrayBuffer
object to a new ArrayBuffer
object representing received bytes. If this throws an exception, then set
response ArrayBuffer
object to null and set received bytes
to the empty byte sequence.
Allocating an ArrayBuffer
buffer is not guaranteed to succeed.
[ECMASCRIPT]
Return response ArrayBuffer
object.
A blob response is the return value of these steps:
If response Blob
object is non-null, return it.
Let type be the empty string, if final MIME type is null, and final MIME type otherwise.
Set response Blob
object to a new
Blob
object representing received bytes with
type
type and
return it.
A document response is the return value of these steps:
If response Document
object is non-null, return it.
If final MIME type is not null,
text/html
, text/xml
,
application/xml
, or does not end in
+xml
, return null.
If responseType
is
the empty string and final MIME type is
text/html
, return null.
This is restricted to
responseType
being
"document
" in order to prevent breaking legacy
content.
If final MIME type is text/html
, run these
substeps:
Let charset be the final charset.
If charset is null, prescan the first 1024 bytes of received bytes and if that does not terminate unsuccessfully then let charset be the return value.
If charset is null, set charset to utf-8.
Let document be a document that represents the result parsing received bytes following the rules set forth in the HTML Standard for an HTML parser with scripting disabled and a known definite encoding charset. [HTML]
Flag document as an HTML document.
Otherwise, let document be a document that represents the result of running the XML parser with XML scripting support disabled on received bytes. If that fails (unsupported character encoding, namespace well-formedness error, etc.), then return null. [HTML]
Resources referenced will not be loaded and no associated XSLT will be applied.
If charset is null, set charset to utf-8.
Set document's encoding to charset.
Set document's content type to final MIME type.
Set document's origin to context object's relevant settings object's origin.
Set response Document
object to
document and return it.
A JSON response is the return value of these steps:
If response JSON object is non-null, return it.
Let JSON text be the result of running utf-8 decode on received bytes.
Let JSON object be the result of invoking the initial value of the
parse
property of the JSON
object, with
JSON text as its only argument. If that threw an exception, return null.
[ECMASCRIPT]
Set response JSON object to JSON object and return it.
A text response is the return value of these steps:
Let charset be the final charset.
If responseType
is
the empty string, charset is null, and
final MIME type is either null, text/xml
,
application/xml
or ends in +xml
, use the
rules set forth in the XML specifications to determine the encoding. Let
charset be the determined encoding.
[XML] [XMLNS]
This is restricted to
responseType
being
the empty string to keep the non-legacy
responseType
value
"text
" simple.
If charset is null, set charset to utf-8.
Return the result of running decode on received bytes using fallback encoding charset.
Authors are strongly encouraged to always encode their resources using utf-8.
overrideMimeType()
methodclient . overrideMimeType(mime)
Sets the `Content-Type
` header for response to
mime.
Throws an InvalidStateError
exception if
state is
loading or done.
Throws a SyntaxError
exception if
mime is not a valid MIME type.
The
overrideMimeType(mime)
method must run these steps:
If state is
loading or done,
throw an
InvalidStateError
exception.
If parsing mime analogously to the value of
the `Content-Type
` header fails,
throw a
SyntaxError
exception.
If mime is successfully parsed, set override MIME type to its MIME type, excluding any parameters, and converted to ASCII lowercase.
If a `charset
` parameter is successfully parsed, set
override charset to its value.
responseType
attributeclient . responseType
[ = value ]
Returns the response type.
Can be set to change the response type. Values are:
the empty string (default),
"arraybuffer
",
"blob
",
"document
",
"json
", and
"text
".
When set: setting to "document
" is ignored if
entry settings object's
global object is not a
Window
object.
When set: throws an
InvalidStateError
exception if
state is loading or
done.
When set: throws an
InvalidAccessError
exception if the
synchronous flag is set and
entry settings object's
global object is a Window
object.
The
responseType
attribute must return its value. Initially its value must be the empty
string.
Setting the
responseType
attribute must run these steps:
If entry settings object's
global object is not a
Window
object and the given value is
"document
", terminate these steps.
If state is
loading or done,
throw an
InvalidStateError
exception.
If entry settings object's
global object is a Window
object and the synchronous flag is set,
throw an
InvalidAccessError
exception.
Set the
responseType
attribute's value to the given value.
response
attributeThe
response
attribute must return the result of running these
steps:
responseType
is the empty string or "text
"If state is not loading or done, return the empty string.
Return the text response.
If state is not done, return null.
responseType
is
"arraybuffer
"Return the arraybuffer response.
responseType
is
"blob
"Return the blob response.
responseType
is
"document
"Return the document response.
responseType
is
"json
"Return the JSON response.
responseText
attributeclient . responseText
Returns the text response.
Throws an InvalidStateError
exception if
responseType
is not
the empty string or "text
".
The
responseText
attribute must return the result of running these
steps:
If responseType
is not the
empty string or "text
",
throw an
InvalidStateError
exception.
If state is not loading or done, return the empty string.
Return the text response.
responseXML
attributeclient . responseXML
Returns the document response.
Throws an InvalidStateError
exception if
responseType
is not
the empty string or "document
".
The
responseXML
attribute must return the result of running these steps:
If
responseType
is not
the empty string or "document
",
throw an
InvalidStateError
exception.
If state is not done, return null.
Return the document response.
The
responseXML
attribute
has XML in its name for historical reasons. It also returns HTML resources
as documents.
This section is non-normative.
The following events are dispatched on XMLHttpRequest
and/or XMLHttpRequestUpload
objects:
Event name | Interface | Dispatched when… |
---|---|---|
readystatechange |
Event |
The readyState attribute changes
value, except when it changes to UNSENT.
|
loadstart |
ProgressEvent |
The fetch initiates. |
progress |
ProgressEvent |
Transmitting data. |
abort |
ProgressEvent |
When the fetch has been aborted. For instance, by invoking the
abort() method. |
error |
ProgressEvent |
The fetch failed. |
load |
ProgressEvent |
The fetch succeeded. |
timeout |
ProgressEvent |
The author specified timeout has passed before the fetch completed. |
loadend |
ProgressEvent |
The fetch completed (success or failure). |
FormData
typedef (File or USVString) FormDataEntryValue; [Constructor(optional HTMLFormElement form), Exposed=(Window,Worker)] interface FormData { void append(USVString name, USVString value); void append(USVString name, Blob value, optional USVString filename); void delete(USVString name); FormDataEntryValue? get(USVString name); sequence<FormDataEntryValue> getAll(USVString name); boolean has(USVString name); void set(USVString name, USVString value); void set(USVString name, Blob value, optional USVString filename); iterable<USVString, FormDataEntryValue>; };
The FormData
object represents an ordered list of
entries. Each
entry consists of a
name and a
value.
For the purposes of interaction with other algorithms, an
entry's type is "string" if its
value is a string and "file" otherwise. If
an entry's type is "file", its filename is
the empty string if value is not
a File
object, and otherwise its filename is the
value of entry's
value's
name
attribute.
To create an entry for name, value, and optionally a filename, run these steps:
Let entry be a new entry.
Set entry's name to name.
If value is a Blob
object and not a
File
object, then set value to a new
File
object, representing the same bytes, whose
name
attribute value is
"blob
".
If value is (now) a File
object and
filename is given, then set value to a new
File
object, representing the same bytes, whose
name
attribute value is
filename.
Set entry's value to value.
Return entry.
The
FormData(form)
constructor must run these steps:
Let fd be a new FormData
object.
If form is given, set fd's entries to the result of constructing the form data set for form.
Return fd.
The
append(name, value, filename)
method, when invoked, must run these steps:
Let entry be the result of creating an entry with name, value, and filename if given.
Append entry to context object's list of entries.
The
delete(name)
method, when invoked, must remove all entries
whose name is name.
The get(name)
method, when
invoked, must return the value of the first
entry whose
name is name, and null
otherwise.
The getAll(name)
method,
when invoked, must return the values of
all entries whose
name is name, in list order, and
the empty sequence otherwise.
The has(name)
method, when
invoked, must return true if there is an entry
whose name is name, and false
otherwise.
The
set(name, value, filename)
method, when invoked, must run these steps:
Let entry be the result of creating an entry with name, value, and filename if given.
If there are any entries in context object's list of entries whose name is name, then replace the first such entry with entry and remove the others.
Otherwise, append entry to context object's list of entries.
The value pairs to iterate over are the entries with the key being the name and the value the value.
ProgressEvent
[Constructor(DOMString type, optional ProgressEventInit eventInitDict), Exposed=(Window,DedicatedWorker,SharedWorker)] interface ProgressEvent : Event { readonly attribute boolean lengthComputable; readonly attribute unsigned long long loaded; readonly attribute unsigned long long total; }; dictionary ProgressEventInit : EventInit { boolean lengthComputable = false; unsigned long long loaded = 0; unsigned long long total = 0; };
Events using
the ProgressEvent
interface indicate some kind of
progression.
The
lengthComputable
,
loaded
, and
total
attributes must return the value they were initialized to.
ProgressEvent
interfaceTo
fire a progress event named e
given transmitted and length,
fire an event named e
with an event
using the ProgressEvent
interface that also meets these
conditions:
Set the loaded
attribute value to
transmitted.
If length is not 0, set the
lengthComputable
attribute value to
true and the total
attribute value to
length.
ProgressEvent
interfaceThis section is non-normative.
The suggested type
attribute values for use with
events using the
ProgressEvent
interface are summarized in the table below.
Specification editors are free to tune the details to their specific
scenarios, though are strongly encouraged to discuss their usage with the
WHATWG community to ensure input from people familiar with the subject.
type attribute value
| Description | Times | When |
---|---|---|---|
loadstart
| Progress has begun. | Once. | First. |
progress
| In progress. | Once or more. | After loadstart has been
dispatched.
|
error
| Progression failed. | Zero or once (mutually exclusive). | After the last progress has
been
dispatched.
|
abort
| Progression is terminated. | ||
timeout
| Progression is terminated due to preset time expiring. | ||
load
| Progression is successful. | ||
loadend
| Progress has stopped. | Once. | After one of error , abort ,
timeout or load has been
dispatched.
|
The error
, abort
, timeout
, and
load
event types are mutually exclusive.
Throughout the web platform the error
, abort
,
timeout
and load
event types have
their bubbles
and
cancelable
attributes initialized to false, so it is suggested that for consistency all
events using the
ProgressEvent
interface do the same.
For cross-origin requests some kind of opt-in, e.g. the
CORS protocol defined in the Fetch Standard, has to be
used before events using the
ProgressEvent
interface are
dispatched
as information (e.g. size) would be revealed that cannot be obtained
otherwise. [FETCH]
In this example XMLHttpRequest
, combined with concepts
defined in the sections before, and the HTML
progress
element are used together to
display the process of
fetching a resource.
<!DOCTYPE html> <title>Waiting for Magical Unicorns</title> <progress id=p></progress> <script> var progressBar = document.getElementById("p"), client = new XMLHttpRequest() client.open("GET", "magical-unicorns") client.onprogress = function(pe) { if(pe.lengthComputable) { progressBar.max = pe.total progressBar.value = pe.loaded } } client.onloadend = function(pe) { progressBar.value = pe.loaded } client.send() </script>
Fully working code would of course be more elaborate and deal with more scenarios, such as network errors or the end user terminating the request.
Thanks to Addison Phillips, Adrian Bateman, Ahmed Kamel, Alan Thomas, Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Andrea Marchesini, Asbjørn Ulsberg, Bertrand Guay-Paquet, Björn Höhrmann, Boris Zbarsky, Caitlin Potter, Cameron McCormack, Chris Marrin, Christophe Jolif, Charles McCathieNevile, Dan Winship, David Andersson, David Flanagan, David Håsäther, David Levin, Dean Jackson, Denis Sureau, Domenic Denicola, Dominik Röttsches, Doug Schepers, Douglas Livingstone, Elliott Sprehn, Elliotte Harold, Eric Lawrence, Eric Uhrhane, Erik Arvidsson, Erik Dahlström, Feras Moussa, Geoffrey Sneddon, Gideon Cohn, Glenn Adams, Gorm Haug Eriksen, Håkon Wium Lie, Hallvord R. M. Steen, Henri Sivonen, Hiroshige Hayashizaki, Huub Schaeks, Ian Davis, Ian Hickson, Ivan Herman, Jake Archibald, Jared Jacobs, Jarred Nicholls, Jeff Walden, Jens Lindström, Jim Deegan, Jim Ley, Joe Farro, Jonas Sicking, Julian Reschke, 송정기 (Jungkee Song), 呂康豪 (Kang-Hao Lu), Karl Dubost, Keith Yeung, Lachlan Hunt, Maciej Stachowiak, Magnus Kristiansen, Manish Goregaokar, Marc Hadley, Marcos Caceres, Mark Baker, Mark Birbeck, Mark Nottingham, Mark S. Miller, Martin Hassman, Mohamed Zergaoui, Ms2ger, Odin Hørthe Omdal, Olli Pettay, Pawel Glowacki, Peter Michaux, Philip Jägenstedt, Philip Taylor, Robin Berjon, Rune F. Halvorsen, Ruud Steltenpool, Sergiu Dumitriu, Shivakumar Jagalur Matt, Sigbjørn Finne, Simon Pieters, Stewart Brodie, Sunava Dutta, Takeshi Kurosawa, Takeshi Yoshino, Thomas Roessler, Thomas Wisniewski, Tom Magliery, Travis Leithead, Yehuda Katz, Youenn Fablet, and Zhenbin Xu for their contributions to this standard.
Special thanks to the Microsoft employees who first implemented the
XMLHttpRequest
interface, which was first widely deployed by the
Windows Internet Explorer browser.
Special thanks to Ian Hickson for drafting an initial version of this specification in the HTML Standard (then Web Applications 1.0). [HTML]
Special thanks to the W3C SVG WG for drafting the original
ProgressEvent
class as part of the
SVG Micro DOM.
This standard is written by Anne van Kesteren (Mozilla, annevk@annevk.nl).
Per CC0, to the extent possible under law, the editor has waived all copyright and related or neighboring rights to this work.