The XMLHttpRequest Level 2 specification enhances the
XMLHttpRequest object with new features, such as
cross-origin requests, progress events, and the handling of byte streams
for both sending and receiving.
Status of this Document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current
W3C publications and the latest revision of this technical report can be
found in the W3C technical reports index
at http://www.w3.org/TR/.
This is the 16 August 2011 W3C Working Draft of
XMLHttpRequest Level 2. Please send comments to
public-webapps@w3.org
(archived)
with [XHR2] at the start of the subject line.
Publication as a Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
The XMLHttpRequest object implements an interface exposed
by a scripting engine that allows scripts to perform HTTP client
functionality, such as submitting form data or loading data from a
server. It is the ECMAScript HTTP API.
[ECMASCRIPT]
The name of the object is XMLHttpRequest for compatibility
with the Web, though each component of this name is potentially
misleading. First, the object supports any text based format, including
XML. Second, it can be used to make requests over both HTTP and HTTPS
(some implementations support protocols in addition to HTTP and HTTPS, but
that functionality is not covered by this specification). Finally, it
supports "requests" in a broad sense of the term as it pertains to HTTP;
namely all activity involved with HTTP requests or responses for the
defined HTTP methods.
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.readyState == this.DONE) {
if(this.status == 200 &&
this.responseXML != null &&
this.responseXML.getElementById('test').textContent) {
// success!
processData(this.responseXML.getElementById('test').textContent);
return;
}
// something went wrong
processData(null);
}
}
var client = new XMLHttpRequest();
client.onreadystatechange = 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.onreadystatechange = function() {
// in case of network errors this might not give reliable results
if(this.readyState == this.DONE)
returnStatus(this.status);
}
client.open("HEAD", address);
client.send();
}
2 Conformance
Everything in this specification is normative except for diagrams,
examples, notes and sections marked non-normative.
The key words must, must not, should, should not and may in this
document are to be interpreted as described in RFC 2119.
[RFC2119]
This specification defines a single conformance class:
Conforming user agent
A user agent must behave as described in this
specification in order to be considered conformant.
User agents may implement algorithms given in
this specification in any way desired, so long as the end result is
indistinguishable from the result that would be obtained by the
specification's algorithms.
This specification uses both the terms "conforming user
agent(s)" and "user agent(s)" to refer to this product class.
2.1 Dependencies
This specification relies on several underlying specifications.
Cross-Origin Resource Sharing
A conforming user agent must
support the algorithms of the Cross-Origin Resource Sharing
specification. [CORS]
DOM Core
A conforming user agent must
support at least the subset of the functionality defined in DOM Core that
this specification relies upon, such as various exceptions and
EventTarget. [DOMCORE]
File API
A conforming user agent must
support at least the subset of the functionality defined in File API that
this specification relies upon, such as the Blob and
File interfaces. [FILEAPI]
HTML
A conforming user agent must
support at least the subset of the functionality defined in HTML that
this specification relies upon, such as the basics of the
Window object and serializing a Document
object. [HTML]
HTTP
A conforming user agent must
support some version of the HTTP protocol. Requirements regarding HTTP
are made throughout the specification. [HTTP]
A conforming user agent must also
be a conforming implementation of the IDL fragments in this
specification, as described in the Web IDL specification.
[WEBIDL]
User agents, Working Groups, and other interested parties are
strongly encouraged to discuss extensions on a relevant public
forum, preferably
public-webapps@w3.org. If this
is for some reason not possible prefix the extension in some way and start
the prefix with an uppercase letter. E.g. if company Foo wants to add a
private method bar() it could be named FooBar()
to prevent clashes with a potential future standardized
bar().
3 Terminology
The term user credentials for the purposes of this
specification means cookies, HTTP authentication, and client-side SSL
certificates. Specifically it does not refer to proxy authentication or
the Origin header.
[COOKIES]
To deflate a DOMString into a byte sequence means to create
a sequence of bytes such that the nth byte of the
sequence is equal to the low-order byte of the nth
code point in the original DOMString.
To inflate a byte sequence into a DOMString means to create
a DOMString such that the nth code point has 0x00 as
the high-order byte and the nth byte of the byte
sequence as the low-order byte.
4 The XMLHttpRequest Interface
The XMLHttpRequest object can be used by scripts to issue
HTTP requests.
Each XMLHttpRequest object has an associated
XMLHttpRequest origin and an
XMLHttpRequest base URL.
This specification defines their values when the global object is
represented by the Window object. When
the XMLHttpRequest object is used in other contexts their
values will have to be defined as appropriate for that context. That is
considered to be out of scope for this specification.
In environments where the global object is represented by the
Window object the
XMLHttpRequest object has an associated
XMLHttpRequestDocument which is the
Document object associated with the
Window object for which the
XMLHttpRequest interface object was created.
The XMLHttpRequest object can be in several states. The
readyState
attribute must return the current state, which must be one of the
following values:
UNSENT
(numeric value 0)
The object has been constructed.
OPENED
(numeric value 1)
The open() method has been successfully invoked.
During this state request headers can be set using
setRequestHeader()
and the request can be made using the
send() method.
HEADERS_RECEIVED
(numeric value 2)
All redirects (if any) have been followed and all HTTP headers of
the final response have been received. Several response members of the
object are now available.
The data transfer has been completed or something went wrong
during the transfer (e.g. infinite redirects).
The OPENED state has an associated
send() flag that indicates whether
the send() method has been
invoked. It can be either true or false and has an initial value of
false.
The error flag indicates some type of
network error or abortion. It is used during the
DONE state. It can be either
true or false and has an initial value of false.
4.6 Request
The XMLHttpRequest object holds the following request
metadata variables:
The asynchronous flag
True when fetching is
done asychronously. False when fetching is done synchronously.
If any code point in method is higher than
U+00FF LATIN SMALL LETTER Y WITH DIAERESIS or after
deflatingmethod it does not match the
Method token production raise a SYNTAX_ERR
exception and terminate these steps. Otherwise let method be
the result of
deflatingmethod.
If method is a case-insensitive match for
CONNECT, DELETE, GET,
HEAD, OPTIONS, POST,
PUT, TRACE, or TRACK
subtract 0x20 from each byte in the range 0x61 (ASCII a) to
0x7A (ASCII z).
If it does not match any of the above, it is passed
through literally, including in the final request.
If method is a case-sensitive match for
CONNECT, TRACE, or TRACK raise a
SECURITY_ERR exception and terminate these steps.
Allowing these methods poses a security risk.
[HTTPVERBSEC]
If the "user:password" format in the
userinfo production is not supported
for the relevant
<scheme> and
url contains this format raise a
SYNTAX_ERR
and terminate these steps.
If url contains the "user:password"
format let temp user be the user part and
temp password be the password part.
If url just contains the "user"
format let temp user be the user part.
Let async be the value of the async argument
or true if it was omitted.
If the user argument was not omitted follow these
sub steps:
Throws a SYNTAX_ERR exception if
header is not a valid HTTP header field name or if
value is not a valid HTTP header field 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.
For non same origin requests using the HTTP
GET method a preflight request is made when headers other
than Accept and Accept-Language are set.
When the
setRequestHeader(header, value)
method is invoked, the user agent must run these
steps:
If any code point in header is higher than
U+00FF LATIN SMALL LETTER Y WITH DIAERESIS or after
deflatingheader it does not match the
field-name production raise a
SYNTAX_ERR
exception and terminate these steps. Otherwise let header be
the result of
deflatingheader.
If any code point in value is higher than
U+00FF LATIN SMALL LETTER Y WITH DIAERESIS or after
deflatingvalue it does not match the
field-value production raise a
SYNTAX_ERR
exception and terminate these steps. Otherwise let value be
the result of
deflatingvalue.
The empty string is legal and represents the empty
header value.
Terminate these steps if header is a case-insensitive
match for one of the following headers:
Accept-Charset
Accept-Encoding
Access-Control-Request-Headers
Access-Control-Request-Method
Connection
Content-Length
Cookie
Cookie2
Content-Transfer-Encoding
Date
Expect
Host
Keep-Alive
Origin
Referer
TE
Trailer
Transfer-Encoding
Upgrade
User-Agent
Via
… or if the start of header is a case-insensitive
match for Proxy- or Sec- (including when
header is just Proxy- or Sec-).
The above headers are controlled by the user agent to
let it control those aspects of transport. This guarantees data
integrity to some extent. Header names starting with Sec-
are not allowed to be set to allow new headers to be minted that are
guaranteed not to come from XMLHttpRequest.
If header is not in the
author request headers list append header with
its associated value to the list and terminate these
steps.
If header is in the author request headers
list either use multiple headers, combine the values or use a combination
of those (section 4.2, RFC 2616).
[HTTP]
See also the
send() method regarding user
agent header handling for caching, authentication, proxies, and
cookies.
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
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 the
send(data)
method is invoked, the user agent must run these steps
(unless otherwise noted). This algorithm can be
terminated by invoking the
open() or
abort() method. When it is
terminated the user agent
must terminate the algorithm after finishing the step
it is on.
The send()
algorithm can only be terminated when the asynchronous flag
is true and only after the method call has returned.
If a Content-Type header is set using
setRequestHeader()
whose value is a valid MIME type and
has a charset parameter whose value is not a case-insensitive
match for encoding, and encoding
is not null, set all the charset parameters of the
Content-Type header to encoding.
If no Content-Type header has been set using
setRequestHeader()
and mime type is not null set a
Content-Type request header with as value
mime type.
If the user agent allows the end user to configure a proxy it
should modify the request appropriately; i.e., connect
to the proxy host instead of the origin server, modify the
Request-Line and send Proxy-Authorization
headers as specified.
If the user agent supports HTTP Authentication and
Authorization is not in the list
of author request headers, it should
consider requests originating from the XMLHttpRequest object
to be part of the protection space that includes the accessed URIs and
send Authorization headers and
handle 401 Unauthorized requests appropriately.
Otherwise, if authentication fails, user agents
must not prompt the end user for their username and
password. [HTTPAUTH]
End users are not prompted for various cases so that
authors can implement their own user interface.
If the user agent supports HTTP State Management it
should persist, discard and send cookies (as received
in the Set-Cookie response header, and sent in the
Cookie header) as applicable.
[COOKIES]
If the user agent implements a HTTP cache it should
respect Cache-Control request headers set by the
setRequestHeader()
(e.g., Cache-Control: no-cache bypasses the cache). It
must not send Cache-Control or
Pragma request headers automatically unless the end user
explicitly requests such behavior (e.g. by reloading the page).
For 304 Not Modified responses that are a result of a
user agent generated conditional request the user agent
must act as if the server gave a 200 OK
response with the appropriate content. The user agent
must allow
setRequestHeader()
to override automatic cache validation by setting request headers (e.g.
If-None-Match or If-Modified-Since), in which
case 304 Not Modified responses must be
passed through. [HTTP]
If the user agent implements server-driven content-negotiation
it must follow these constraints for the
Accept and Accept-Language request headers:
Both headers must not be modified if they are
already set through
setRequestHeader().
If not set through
setRequestHeader()Accept-Language should be set as
appropriate.
If not set through
setRequestHeader()Accept must be set with as value
*/*.
Responses must have the content-encodings
automatically decoded. [HTTP]
Besides the author request headers user agents
should not include additional request headers other than those mentioned
above or other than those authors are not allowed to set using
setRequestHeader().
This ensures that authors have a reasonably predictable API.
4.6.7 Infrastructure for the send() method
The same-origin request event rules are as follows:
If the response has an HTTP status code of 301, 302, 303, or 307
If the redirect violates infinite loop precautions this is a
network error.
Otherwise, run these steps:
Set the request URL to the
URL conveyed by the
Location header.
HTTP places requirements on the user agent regarding the
preservation of the request method and
request entity body during redirects, and also requires end
users to be notified of certain kinds of automatic redirections.
In case of DNS errors, TLS negotiation failure, or other type of
network errors, this is a network error. Do not request any
kind of end user interaction.
This does not include HTTP responses that indicate
some type of error, such as HTTP status code 410.
If timeout is not 0
and since the request started the amount of milliseconds specified by
timeout has passed
When it is said to make progress notifications, while the
download is progressing, queue a task to
fire a progress event named progress
about every 50ms or for every byte received, whichever is least
frequent.
When it is said to make upload progress notifications run
these steps:
When the
abort()
method is invoked, the user agent must run these steps
(unless otherwise noted). This algorithm can be
terminated by invoking the
open() method. When it is
terminated the user agent
must terminate the algorithm after finishing the step
it is on.
The abort()
algorithm can only be terminated by invoking
open() from an event
handler.
If header is a case-insensitive match for
Set-Cookie or Set-Cookie2 return null and
terminate these steps.
If header is a case-insensitive match for multiple HTTP
response headers, return the
inflated
values of these headers as a single concatenated string separated from
each other by a U+002C COMMA U+0020 SPACE character pair and terminate
these steps.
If header is a case-insensitive match for a single HTTP
response header, return the
inflated
value of that header and terminate these steps.
Return null.
The Cross-Origin Resource Sharing specification filters
the headers that are exposed by
getResponseHeader()
for non same-origin
requests. [CORS]
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 == 2) {
print(client.getResponseHeader("Content-Type"));
}
}
The print() function will get to process something
like:
Returns all headers from the response, with the exception of those
whose field name is Set-Cookie or
Set-Cookie2.
When the
getAllResponseHeaders()
method is invoked, the user agent must run these steps:
If the state is UNSENT or
OPENED return the empty string and
terminate these steps.
If the error flag is true return the empty string and
terminate these steps.
Return all the HTTP headers, excluding headers that are a
case-insensitive match for Set-Cookie or
Set-Cookie2,
inflated,
as a single string, with each header line
separated by a U+000D CR U+000A LF pair, excluding the status line, and
with each header name and header value separated by a
U+003A COLON U+0020 SPACE pair.
The response MIME type is the MIME
type the Content-Type header contains without any
parameters or null if the header could not be parsed properly 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 if
the header could not be parsed properly 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.
The response entity body is the
fragment of the entity body of the
response received so far
(LOADING) or the complete
entity body of the response
(DONE). If the response
does not have an entity body the response entity body is null.
The text response entity body
is a DOMString representing the response entity
body. The text response entity body is the return value of the
following algorithm:
If the response entity body is null return the empty string and
terminate these steps.
If charset is null and mime is null,
text/xml, application/xml or ends in
+xml use the rules set forth in the XML
specifications to determine the character encoding. Let
charset be the determined character encoding.
If charset is null and mime is
text/html follow the rules set forth in the HTML
specification to determine the character encoding. Let
charset be the determined character encoding.
[HTML]
If charset is null then, for each of the rows in the
following table, starting with the first one and going down, if the first
bytes of bytes match the bytes given in the first column, then
let charset be the encoding given in the cell in the second
column of that row. If there is no match charset remains
null.
Bytes in Hexadecimal
Description
FE FF
UTF-16BE BOM
FF FE
UTF-16LE BOM
EF BB BF
UTF-8 BOM
If charset is null let charset be
UTF-8.
Return the result of decoding the response entity body using
charset. Replace bytes or sequences of bytes that are not
valid accordng to the charset with a single
U+FFFD REPLACEMENT CHARACTER character. Remove one leading
U+FEFF BYTE ORDER MARK character, if present.
Authors are strongly encouraged to always encode their
resources using UTF-8.
If final MIME type is not null,
text/html, text/xml,
application/xml, or does not end in
+xml, return null and terminate these
steps.
If final MIME type is text/html let
document be Document object that represents
the response entity body parsed following the rules set
forth in the HTML specification for an HTML parser with scripting
disabled. [HTML]
Otherwise, let document be a
Document object that represents the result of parsing the
response entity body into a document tree following the
rules set forth in the XML specifications. If that fails
(unsupported character encoding, namespace well-formedness error et
cetera) return null and terminate these steps.
[XML][XMLNS]
Scripts in the resulting document tree will not be executed,
resources referenced will not be loaded and no associated XSLT will be
applied.
When the
FormData()
constructor is invoked a new FormData object
must be returned.
When the
FormData(form)
constructor is invoked (i.e. with a form argument) a new
FormData object must be returned with as
entries the result of
constructing the form data set for
form.
Appends a new name/value-pair to the FormData
object.
When the
append(name, value)
method is invoked, the user agent must create a new
entry with the following parameters set:
Set its name to name.
Set its value to value.
Set its type to "text" if value is a string and "file" if
it is a Blob.
If type is "file" set filename to "blob".
If type is "file" and value is a
File whose
name attribute
is not the empty string, set filename to the attribute's value.
It then must append this entry to the end of the
collection the FormData object represents.
Differences from XMLHttpRequest
XMLHttpRequest Level 2 adds the following new features:
The ability to make cross-origin requests.
The ability to make anonymous requests —
Referer, origin, and credentials are not part of the
request.
The ability to register for progress events. Both for downloads
(put listeners on the XMLHttpRequest object itself) and
uploads (put listeners on the XMLHttpRequestUpload object,
returned by the upload
attribute).
The ability to override the media type and character encoding of
the response through the
overrideMimeType()
method.
The editor would like to thank
Addison Phillips,
Ahmed Kamel,
Alex Hopmann,
Alex Vincent,
Alexey Proskuryakov,
Asbjørn Ulsberg,
Boris Zbarsky,
Björn Höhrmann,
Cameron McCormack,
Chris Marrin,
Christophe Jolif,
Charles McCathieNevile,
Dan Winship,
David Andersson,
David Flanagan,
David Håsäther,
David Levin,
Dean Jackson,
Denis Sureau,
Doug Schepers,
Douglas Livingstone,
Elliotte Harold,
Eric Lawrence,
Eric Uhrhane,
Erik Dahlström,
Geoffrey Sneddon,
Gideon Cohn,
Gorm Haug Eriksen,
Håkon Wium Lie,
Hallvord R. M. Steen,
Henri Sivonen,
Huub Schaeks,
Ian Davis,
Ian Hickson,
Ivan Herman,
Jeff Walden,
Jens Lindström,
Jim Deegan,
Jim Ley,
Joe Farro,
Jonas Sicking,
Julian Reschke,
Karl Dubost,
Lachlan Hunt,
Maciej Stachowiak,
Magnus Kristiansen,
Marc Hadley,
Marcos Caceres,
Mark Baker,
Mark Birbeck,
Mark Nottingham,
Mark S. Miller,
Martin Hassman,
Mohamed Zergaoui,
Olli Pettay,
Pawel Glowacki,
Peter Michaux,
Philip Taylor,
Robin Berjon,
Rune Halvorsen,
Ruud Steltenpool,
Sergiu Dumitriu,
Simon Pieters,
Stewart Brodie,
Sunava Dutta,
Thomas Roessler,
Tom Magliery, and
Zhenbin Xu
for their contributions to this specification.
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 also to the WHATWG for drafting an initial version of
this specification in their Web Applications 1.0 document (now renamed to
HTML). [HTML]
Thanks also to all those who have helped to improve this specification
by sending suggestions and corrections. (Please, keep bugging us with your
issues!)
翻译：