XMLHttpRequest

使用 XMLHttpRequest(XHR)对象可以与服务器交互。您可以从URL获取数据,而无需让整个的页面刷新。这允许网页在不影响用户的操作的情况下更新页面的局部内容。AJAX 编程中,XMLHttpRequest 被大量使用。

尽管名称如此,XMLHttpRequest 可以用于获取任何类型的数据,而不仅仅是XML,它甚至支持 HTTP 以外的协议(包括 file:// 和 FTP)。

如果您的通信流程需要从服务器接收事件或消息数据,请考虑通过 EventSource 接口使用 server-sent events。对于全双工的通信, WebSocket 则可能是更好的选择。

构造函数

XMLHttpRequest()
该构造函数用于初始化一个 XMLHttpRequest 对象。在调用下列任何其他方法之前,必须先调用该构造函数,或通过其他方式间接得到一个 XMLHttpRequest 对象。

属性

此接口继承了 XMLHttpRequestEventTargetEventTarget 的属性。

XMLHttpRequest.onreadystatechange
当 readyState 属性发生变化时调用的 EventHandler
XMLHttpRequest.readyState 只读
返回 一个无符号短整型(unsigned short)数字,代表请求的状态码。
XMLHttpRequest.response 只读
返回一个 ArrayBufferBlobDocument,或 DOMString,具体是哪种类型取决于 XMLHttpRequest.responseType 的值。其中包含整个响应体(response body)。
XMLHttpRequest.responseText 只读
返回一个 DOMString,该 DOMString 包含对请求的响应,如果请求未成功或尚未发送,则返回 null
XMLHttpRequest.responseType
一个用于定义响应类型的枚举值(enumerated value)。
XMLHttpRequest.responseURL 只读
返回响应的序列化(serialized)URL,如果该 URL 为空,则返回空字符串。
XMLHttpRequest.responseXML 只读
返回一个 Document,其中包含该请求的响应,如果请求未成功、尚未发送或时不能被解析为 XML 或 HTML,则返回 null
XMLHttpRequest.status 只读
返回一个无符号短整型(unsigned short)数字,代表请求的响应状态。
XMLHttpRequest.statusText 只读
返回一个 DOMString,其中包含 HTTP 服务器返回的响应状态。与 XMLHTTPRequest.status 不同的是,它包含完整的响应状态文本(例如,"200 OK")。

注意:根据 HTTP/2 规范(8.1.2.4 Response Pseudo-Header Fields,响应伪标头字段),HTTP/2 没有定义任何用于携带 HTTP/1.1 状态行中包含的版本或原因短语的方法。

XMLHttpRequest.timeout

一个无符号长整型(unsigned long)数字,表示该请求的最大请求时间(毫秒),若超出该时间,则请求会自动结束。

XMLHttpRequestEventTarget.ontimeout

当请求超时调用的 EventHandler

XMLHttpRequest.upload 只读

XMLHttpRequestUpload,代表上传过程。

XMLHttpRequest.withCredentials

一个布尔值,用来指定跨域 Access-Control 请求是否应带有授权信息,如 cookie 或授权 header 头。

非标准属性

XMLHttpRequest.channel只读
nsIChannel,对象在执行请求时使用的通道。
XMLHttpRequest.mozAnon只读
一个布尔值,如果为真,请求将在没有cookie和身份验证header头的情况下发送。
XMLHttpRequest.mozSystem只读
一个布尔值,如果为真,则在请求时不会强制执行同源策略。
XMLHttpRequest.mozBackgroundRequest
一个布尔值,它指示对象是否是后台服务器端的请求。
XMLHttpRequest.mozResponseArrayBuffer 已废弃 Gecko 6 只读
一个 ArrayBuffer,把请求的响应作为一个 JavaScript TypedArray。
XMLHttpRequest.multipart已废弃 Gecko 22
这是一个 Gecko 专有属性,是一个布尔值,已在 Firefox/Gecko 22 中被删除。请考虑使用 Server-Sent EventWeb Socket、或来自进度事件的 responseText 代替。

事件处理器

作为 XMLHttpRequest 实例的属性,所有浏览器都支持 onreadystatechange

后来,许多浏览器实现了一些额外的事件(onloadonerroronprogress 等)。详见Using XMLHttpRequest

更多现代浏览器,包括 Firefox,除了可以设置 on* 属性外,也提供标准监听器 addEventListener() API 来监听XMLHttpRequest 事件。

方法

XMLHttpRequest.abort()
如果请求已被发送,则立刻中止请求。
XMLHttpRequest.getAllResponseHeaders()
以字符串的形式返回所有用 CRLF 分隔的响应头,如果没有收到响应,则返回 null
XMLHttpRequest.getResponseHeader()
返回包含指定响应头的字符串,如果响应尚未收到或响应中不存在该报头,则返回 null
XMLHttpRequest.open()
初始化一个请求。该方法只能在 JavaScript 代码中使用,若要在 native code 中初始化请求,请使用 openRequest()
XMLHttpRequest.overrideMimeType()
重写由服务器返回的 MIME 类型。
XMLHttpRequest.send()
发送请求。如果请求是异步的(默认),那么该方法将在请求发送后立即返回。
XMLHttpRequest.setRequestHeader()
设置 HTTP 请求头的值。您必须在 open() 之后、send() 之前调用 setRequestHeader() 方法。

非标准方法

XMLHttpRequest.init()
在 C++ 代码中初始化一个 XHR 对象。
警告:该方法不能在 JavaScript 代码中使用。
XMLHttpRequest.openRequest()
初始化一个请求. 这个方法用于本地代码; 如果用JavaScript 代码来初始化请求,使用 open()代替. 可参考 open() 的文档。
XMLHttpRequest.sendAsBinary()
send() 方法的变体,用来发送二进制数据。

事件

abort
当 request 被停止时触发,例如当程序调用 XMLHttpRequest.abort() 时。
也可以使用 onabort 属性。
error
当request遭遇错误时触发。
也可以使用 onerror 属性
load
XMLHttpRequest请求成功完成时触发。
也可以使用 onload 属性.
loadend
当请求结束时触发, 无论请求成功 ( load) 还是失败 (aborterror)。
也可以使用 onloadend 属性。
loadstart
接收到响应数据时触发。
也可以使用 onloadstart 属性。
progress
接收数据开始周期触发。
也可以使用 onprogress 属性。
timeout
在预设时间内没有接收到响应时触发。
也可以使用 ontimeout 属性。

规范

规范 状态 注释
XMLHttpRequest Living Standard Live standard, latest version

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
XMLHttpRequestChrome Full support 1Edge Full support YesFirefox Full support 1IE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
abortChrome Full support 18Edge Full support 12Firefox Full support YesIE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
abort eventChrome Full support YesEdge ? Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
error eventChrome Full support YesEdge ? Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
getAllResponseHeadersChrome Full support 1Edge Full support 12Firefox Full support 4
Notes
Full support 4
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
IE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 4
Notes
Full support 4
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
getResponseHeaderChrome Full support 1Edge Full support 12Firefox Full support Yes
Notes
Full support Yes
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
IE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support Yes
Notes
Full support Yes
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
load eventChrome Full support YesEdge ? Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
loadend eventChrome Full support YesEdge ? Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
loadstart eventChrome Full support YesEdge ? Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
onreadystatechangeChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7
Notes
Full support 7
Notes
Notes Internet Explorer version 5 and 6 supported ajax calls using ActiveXObject()
Opera Full support YesSafari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
openChrome Full support 1Edge Full support 12Firefox Full support Yes
Notes
Full support Yes
Notes
Notes Starting in Firefox 30, synchronous requests on the main thread have been deprecated due to their negative impact on performance and the user experience. Therefore, the async parameter may not be false except in a Worker.
IE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support Yes
Notes
Full support Yes
Notes
Notes Starting in Firefox 30, synchronous requests on the main thread have been deprecated due to their negative impact on performance and the user experience. Therefore, the async parameter may not be false except in a Worker.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
overrideMimeTypeChrome Full support 1Edge Full support 12Firefox Full support YesIE Full support 11
Full support 11
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
progress eventChrome Full support YesEdge ? Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
readyStateChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
responseChrome Full support YesEdge Full support 12Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
responseTextChrome Full support YesEdge Full support 12Firefox Full support YesIE Full support Yes
Notes
Full support Yes
Notes
Notes Before IE 10, the value of XMLHttpRequest.responseText could be read only once the request was complete.
Opera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
responseTypeChrome Full support 31Edge Full support 12Firefox Full support 6IE Full support 10Opera Full support 18Safari Full support 7WebView Android Full support 55Chrome Android Full support 55Firefox Android Full support 50Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 6.0
responseURLChrome Full support 37Edge Full support 14Firefox Full support 32IE No support NoOpera Full support 24Safari Full support 8WebView Android Full support 37Chrome Android Full support 37Firefox Android Full support 32Opera Android Full support 24Safari iOS Full support YesSamsung Internet Android Full support Yes
responseXMLChrome Full support YesEdge Full support 12Firefox Full support Yes
Notes
Full support Yes
Notes
Notes Prior to Firefox 51, an error parsing the received data added a <parsererror> node to the top of the Document and then returned the Document in whatever state it happens to be in. This was inconsistent with the specification. Starting with Firefox 51, this scenario now correctly returns null as per the spec.
IE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes Prior to Firefox 51, an error parsing the received data added a <parsererror> node to the top of the Document and then returned the Document in whatever state it happens to be in. This was inconsistent with the specification. Starting with Firefox 51, this scenario now correctly returns null as per the spec.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
sendChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
sendAsBinary
DeprecatedNon-standard
Chrome No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
Edge No support NoFirefox No support 2 — 31IE No support NoOpera No support NoSafari No support NoWebView Android No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
Chrome Android No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
Firefox Android No support 4 — 31Opera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
setRequestHeaderChrome Full support 1Edge Full support 12Firefox Full support YesIE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
statusChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7
Notes
Full support 7
Notes
Notes Internet Explorer version 5 and 6 supported ajax calls using ActiveXObject()
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
statusTextChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7
Notes
Full support 7
Notes
Notes Internet Explorer version 5 and 6 supported ajax calls using ActiveXObject()
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
timeoutChrome Full support 29Edge Full support 12Firefox Full support 12IE Full support 8Opera Full support 17
Full support 17
No support 12 — 16
Safari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support 18
Full support 18
No support 12 — 16
Safari iOS Full support YesSamsung Internet Android Full support Yes
timeout eventChrome Full support YesEdge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
uploadChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support 18Firefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
withCredentialsChrome Full support YesEdge Full support 12Firefox Full support 3.5
Notes
Full support 3.5
Notes
Notes Starting with Firefox 11, it's no longer supported to use the withCredentials attribute when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR exception.
IE Full support 10
Notes
Full support 10
Notes
Notes Internet Explorer versions 8 and 9 supported cross-domain requests (CORS) using XDomainRequest.
Opera Full support 12Safari Full support 4WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 4
Notes
Full support 4
Notes
Notes Starting with Firefox 11, it's no longer supported to use the withCredentials attribute when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR exception.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
See implementation notes.
See implementation notes.

参见