XMLHttpRequest

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

XMLHttpRequest(XHR)对象用于与服务器交互。通过 XMLHttpRequest 可以在不刷新页面的情况下请求特定 URL,获取数据。这允许网页在不影响用户操作的情况下,更新页面的局部内容。XMLHttpRequestAJAX 编程中被大量使用。

尽管名称如此,XMLHttpRequest 可以用于获取任何类型的数据,而不仅仅是 XML。它甚至支持 HTTP 以外的协议(包括 file:// 和 FTP),尽管可能受到更多出于安全等原因的限制。

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

构造函数

XMLHttpRequest()

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

属性

此接口继承了 XMLHttpRequestEventTargetEventTarget 的属性。

XMLHttpRequest.onreadystatechange

readyState 属性发生变化时,调用的事件处理器。

XMLHttpRequest.readyState 只读

返回 一个无符号短整型(unsigned short)数字,代表请求的状态码。

XMLHttpRequest.response 只读

返回一个 ArrayBufferBlobDocument,或 DOMString,具体是哪种类型取决于 XMLHttpRequest.responseType 的值。其中包含整个响应实体(response entity 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 状态行中包含的版本(version)或者原因短语(reason phrase)的方法。

XMLHttpRequest.timeout

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

XMLHttpRequest.upload 只读

XMLHttpRequestUpload,代表上传进度。

XMLHttpRequest.withCredentials

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

非标准属性

XMLHttpRequest.channel只读

一个 nsIChannel,对象在执行请求时使用的通道。

XMLHttpRequest.mozAnon只读

一个布尔值,如果为真,请求将在没有 cookie 和身份验证 header 头的情况下发送。

XMLHttpRequest.mozSystem只读

一个布尔值,如果为真,则在请求时不会强制执行同源策略。

XMLHttpRequest.mozBackgroundRequest

一个布尔值,它指示对象是否是后台服务器端的请求。

事件处理器

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

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

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

实例方法

XMLHttpRequest.abort()

如果请求已被发出,则立刻中止请求。

XMLHttpRequest.getAllResponseHeaders()

以字符串的形式返回所有用 CRLF 分隔的响应头,如果没有收到响应,则返回 null

XMLHttpRequest.getResponseHeader()

返回包含指定响应头的字符串,如果响应尚未收到或响应中不存在该报头,则返回 null

XMLHttpRequest.open()

初始化一个请求。

XMLHttpRequest.overrideMimeType()

覆写由服务器返回的 MIME 类型。

XMLHttpRequest.send()

发送请求。如果请求是异步的(默认),那么该方法将在请求发送后立即返回。

XMLHttpRequest.setRequestHeader()

设置 HTTP 请求标头的值。必须在 open() 之后、send() 之前调用 setRequestHeader() 方法。

事件

abort

当 request 被停止时触发,例如当程序调用 XMLHttpRequest.abort() 时。 也可以使用 onabort 属性。

error

当 request 遭遇错误时触发。 也可以使用 onerror 属性

load

XMLHttpRequest请求成功完成时触发。 也可以使用 onload 属性。

loadend

当请求结束时触发,无论请求成功 ( load) 还是失败 (aborterror)。 也可以使用 onloadend 属性。

loadstart

接收到响应数据时触发。 也可以使用 onloadstart 属性。

progress

当请求接收到更多数据时,周期性地触发。 也可以使用 onprogress 属性。

timeout

在预设时间内没有接收到响应时触发。 也可以使用 ontimeout 属性。

规范

Specification
XMLHttpRequest Standard
# interface-xmlhttprequest

浏览器兼容性

BCD tables only load in the browser

参见