当前位置：文江博客知识库简体中文文档 Web API XMLHTTPRequest

XMLHttpRequest - Web API 接口参考编辑

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

  <div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 23.076923076923077%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 650 150" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/wiki/zh-CN/docs/Web/API/EventTarget" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25  121,20  121,30  111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/wiki/zh-CN/docs/Web/API/XMLHttpRequestEventTarget" target="_top"><rect x="151" y="1" width="250" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="276" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">XMLHttpRequestEventTarget</text></a><polyline points="401,25  411,20  411,30  401,25" stroke="#D4DDE4" fill="none"/><line x1="411" y1="25" x2="441" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/wiki/zh-CN/docs/Web/API/XMLHttpRequest" target="_top"><rect x="441" y="1" width="140" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text  x="511" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">XMLHttpRequest</text></a></svg></div>

  a:hover text { fill: #0095DD; pointer-events: all;}

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

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

构造函数

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

属性

此接口继承了 XMLHttpRequestEventTarget 和 EventTarget 的属性。

XMLHttpRequest.onreadystatechange: 当 readyState 属性发生变化时，调用的 EventHandler。
XMLHttpRequest.readyState 只读: 返回一个无符号短整型（unsigned short）数字，代表请求的状态码。
XMLHttpRequest.response 只读: 返回一个 ArrayBuffer、Blob、Document，或 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）数字，表示该请求的最大请求时间（毫秒），若超出该时间，请求会自动终止。
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 Event、Web Socket、或来自进度事件的 responseText 代替。

事件处理器

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

后来，许多浏览器实现了一些额外的事件（onload、onerror、onprogress 等）。详见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(): 初始化一个请求。这个方法只能在原生 C++ 代码中使用；如果用 JavaScript 代码来初始化请求，使用 open() 代替。可参考 open() 的文档。
XMLHttpRequest.sendAsBinary(): send() 方法的变体，用来发送二进制数据。

事件

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