---
title: XMLHttpRequest
slug: Web/API/XMLHttpRequest
tags:
- AJAX
- API
- HTTP
- Reference
- Web
- XHR
- XMLHttpRequest
translation_of: Web/API/XMLHttpRequest
---
<div>{{DefaultAPISidebar("XMLHttpRequest")}}</div>
<p><span class="seoSummary"><code>XMLHttpRequest</code>（XHR）对象用于与服务器交互。通过 XMLHttpRequest 可以在不刷新页面的情况下请求特定 URL，获取数据。这允许网页在不影响用户操作的情况下，更新页面的局部内容。</span><code>XMLHttpRequest</code> 在 {{Glossary("AJAX")}} 编程中被大量使用。</p>
<p>{{InheritanceDiagram(650, 150)}}</p>
<p>尽管名称如此，<code>XMLHttpRequest</code> 可以用于获取任何类型的数据，而不仅仅是 XML。它甚至支持 <a href="/en-US/docs/Web/HTTP">HTTP</a> 以外的协议（包括 file:// 和 FTP），尽管可能受到更多出于安全等原因的限制。</p>
<p>如果您的通信流程需要从服务器端接收事件或消息数据，请考虑通过 {{domxref("EventSource")}} 接口使用 <a href="/en-US/docs/Web/API/Server-sent_events">server-sent events</a>。对于<span class="op_dict_text2">全双工的</span>通信， <a href="/en-US/docs/Web/API/WebSockets_API">WebSocket</a> 可能是更好的选择。</p>
<h2 id="构造函数">构造函数</h2>
<dl>
<dt>{{domxref("XMLHttpRequest.XMLHttpRequest", "XMLHttpRequest()")}}</dt>
<dd>该构造函数用于初始化一个 <code>XMLHttpRequest</code> 实例对象。在调用下列任何其他方法之前，必须先调用该构造函数，或通过其他方式，得到一个实例对象。</dd>
</dl>
<h2 id="属性">属性</h2>
<p><em>此接口继承了 {{domxref("XMLHttpRequestEventTarget")}} 和 {{domxref("EventTarget")}} 的属性。</em></p>
<dl>
<dt>{{domxref("XMLHttpRequest.onreadystatechange")}}</dt>
<dd>当 <code>readyState</code> 属性发生变化时，调用的 {{event("Event_handlers", "event handler")}}。</dd>
<dt>{{domxref("XMLHttpRequest.readyState")}} {{readonlyinline}}</dt>
<dd>返回 一个无符号短整型（<code>unsigned short</code>）数字，代表请求的状态码。</dd>
<dt>{{domxref("XMLHttpRequest.response")}} {{readonlyinline}}</dt>
<dd>返回一个 {{domxref("ArrayBuffer")}}、{{domxref("Blob")}}、{{domxref("Document")}}，或 {{domxref("DOMString")}}，具体是哪种类型取决于 {{domxref("XMLHttpRequest.responseType")}} 的值。其中包含整个响应实体（response entity body）。</dd>
<dt>{{domxref("XMLHttpRequest.responseText")}} {{readonlyinline}}</dt>
<dd>返回一个 {{domxref("DOMString")}}，该 {{domxref("DOMString")}} 包含对请求的响应，如果请求未成功或尚未发送，则返回 <code>null</code>。</dd>
<dt>{{domxref("XMLHttpRequest.responseType")}}</dt>
<dd>一个用于定义响应类型的枚举值（enumerated value）。</dd>
<dt>{{domxref("XMLHttpRequest.responseURL")}} {{readonlyinline}}</dt>
<dd>返回经过序列化（serialized）的响应 URL，如果该 URL 为空，则返回空字符串。</dd>
<dt>{{domxref("XMLHttpRequest.responseXML")}} {{readonlyinline}}</dt>
<dd>返回一个 {{domxref("Document")}}，其中包含该请求的响应，如果请求未成功、尚未发送或时不能被解析为 XML 或 HTML，则返回 <code>null</code>。</dd>
<dt>{{domxref("XMLHttpRequest.status")}} {{readonlyinline}}</dt>
<dd>返回一个无符号短整型（<code>unsigned short</code>）数字，代表请求的响应状态。</dd>
<dt>{{domxref("XMLHttpRequest.statusText")}} {{readonlyinline}}</dt>
<dd>返回一个 {{domxref("DOMString")}}，其中包含 HTTP 服务器返回的响应状态。与 {{domxref("XMLHTTPRequest.status")}} 不同的是，它包含完整的响应状态文本（例如，"<code>200 OK</code>"）。
<div class="note">
<p><strong>注意：</strong>根据 HTTP/2 规范（<a href="https://http2.github.io/http2-spec/#rfc.section.8.1.2.4">8.1.2.4</a> <a href="https://http2.github.io/http2-spec/#HttpResponse">Response Pseudo-Header Fields</a>，响应伪标头字段），HTTP/2 没有定义任何用于携带 HTTP/1.1 状态行中包含的版本（version）或者原因短语（reason phrase）的方法。</p>
</div>
</dd>
</dl>
<dl>
<dt>{{domxref("XMLHttpRequest.timeout")}}</dt>
<dd>一个无符号长整型（<code>unsigned long</code>）数字，表示该请求的最大请求时间（毫秒），若超出该时间，请求会自动终止。</dd>
<dt>{{domxref("XMLHttpRequestEventTarget.ontimeout")}}</dt>
<dd>当请求超时调用的 {{event("Event_handlers", "event handler")}}。{{ gecko_minversion_inline(" 12.0 ")}}</dd>
<dt>{{domxref("XMLHttpRequest.upload")}} {{readonlyinline}}</dt>
<dd>{{domxref("XMLHttpRequestUpload")}}，代表上传进度。</dd>
<dt>{{domxref("XMLHttpRequest.withCredentials")}}</dt>
<dd>一个{{domxref("Boolean", "布尔值")}}，用来指定跨域 <code>Access-Control</code> 请求是否应当带有授权信息，如 cookie 或授权 header 头。</dd>
</dl>
<h3 id="非标准属性">非标准属性</h3>
<dl>
<dt>{{domxref("XMLHttpRequest.channel")}}{{ReadOnlyInline}}</dt>
<dd>一个 {{Interface("nsIChannel")}}，对象在执行请求时使用的通道。</dd>
<dt>{{domxref("XMLHttpRequest.mozAnon")}}{{ReadOnlyInline}}</dt>
<dd>一个布尔值，如果为真，请求将在没有 cookie 和身份验证 header 头的情况下发送。</dd>
<dt>{{domxref("XMLHttpRequest.mozSystem")}}{{ReadOnlyInline}}</dt>
<dd>一个布尔值，如果为真，则在请求时不会强制执行同源策略。</dd>
<dt>{{domxref("XMLHttpRequest.mozBackgroundRequest")}}</dt>
<dd>一个布尔值，它指示对象是否是后台服务器端的请求。</dd>
<dt>{{domxref("XMLHttpRequest.mozResponseArrayBuffer")}}{{gecko_minversion_inline("2.0")}} {{obsolete_inline("6")}} {{ReadOnlyInline}}</dt>
<dd>一个 {{jsxref("ArrayBuffer")}}，把请求的响应作为一个 JavaScript TypedArray。</dd>
<dt>{{domxref("XMLHttpRequest.multipart")}}{{obsolete_inline("22")}}</dt>
<dd><strong>这是一个 Gecko 专有属性，是一个布尔值，已在 Firefox/Gecko 22 中被删除。</strong>请考虑使用 <a href="/en-US/docs/Web/API/Server-sent_events">Server-Sent Event</a>、<a href="/en-US/docs/Web/API/WebSockets_API">Web Socket</a>、或来自进度事件的 <code>responseText</code> 代替。</dd>
</dl>
<h3 id="事件处理器">事件处理器</h3>
<p>作为 <code>XMLHttpRequest</code> 实例的属性之一，所有浏览器都支持 <code>onreadystatechange</code>。</p>
<p>后来，许多浏览器实现了一些额外的事件（<code>onload</code>、<code>onerror</code>、<code>onprogress</code> 等）。详见<a href="/zh-CN/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a>。</p>
<p>更多现代浏览器，包括 Firefox，除了可以设置 <code>on*</code> 属性外，也提供标准的监听器 {{domxref("EventTarget.addEventListener", "addEventListener()")}} API 来监听<code>XMLHttpRequest</code> 事件。</p>
<h2 id="方法">方法</h2>
<dl>
<dt>{{domxref("XMLHttpRequest.abort()")}}</dt>
<dd>如果请求已被发出，则立刻中止请求。</dd>
<dt>{{domxref("XMLHttpRequest.getAllResponseHeaders()")}}</dt>
<dd>以字符串的形式返回所有用 {{Glossary("CRLF")}} 分隔的响应头，如果没有收到响应，则返回 <code>null</code>。</dd>
<dt>{{domxref("XMLHttpRequest.getResponseHeader()")}}</dt>
<dd>返回包含指定响应头的字符串，如果响应尚未收到或响应中不存在该报头，则返回 <code>null</code>。</dd>
<dt>{{domxref("XMLHttpRequest.open()")}}</dt>
<dd>初始化一个请求。该方法只能在 JavaScript 代码中使用，若要在 native code 中初始化请求，请使用 <a class="internal" href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest"><code>openRequest()</code></a>。</dd>
<dt>{{domxref("XMLHttpRequest.overrideMimeType()")}}</dt>
<dd>覆写由服务器返回的 MIME 类型。</dd>
<dt>{{domxref("XMLHttpRequest.send()")}}</dt>
<dd>发送请求。如果请求是异步的（默认），那么该方法将在请求发送后立即返回。</dd>
<dt>{{domxref("XMLHttpRequest.setRequestHeader()")}}</dt>
<dd>设置 HTTP 请求头的值。必须在 <code>open()</code> 之后、<code>send()</code> 之前调用 <code>setRequestHeader()</code> 方法。</dd>
</dl>
<h3 id="非标准方法">非标准方法</h3>
<dl>
<dt>{{domxref("XMLHttpRequest.init()")}}</dt>
<dd>在 C++ 代码中初始化一个 XHR 对象。
<div class="warning"><strong>警告：</strong>该方法不能在 JavaScript 代码中使用。</div>
</dd>
<dt>{{domxref("XMLHttpRequest.openRequest()")}}</dt>
<dd>初始化一个请求。这个方法只能在原生 C++ 代码中使用；如果用 JavaScript 代码来初始化请求，使用 <a href="/zh-cn/nsIXMLHttpRequest#open()"><code>open()</code></a> 代替。可参考 <code>open()</code> 的文档。</dd>
<dt>{{domxref("XMLHttpRequest.sendAsBinary()")}}{{deprecated_inline()}}</dt>
<dd><code>send()</code> 方法的变体，用来发送二进制数据。</dd>
</dl>
<h2 id="事件">事件</h2>
<dl>
<dt>{{domxref("XMLHttpRequest/abort_event", "abort")}}</dt>
<dd>当 request 被停止时触发，例如当程序调用 {{domxref("XMLHttpRequest.abort()")}} 时。<br>
也可以使用 {{domxref("XMLHttpRequestEventTarget/onabort", "onabort")}} 属性。</dd>
<dt>{{domxref("XMLHttpRequest/error_event", "error")}}</dt>
<dd>当 request 遭遇错误时触发。<br>
也可以使用 {{domxref("XMLHttpRequestEventTarget/onerror", "onerror")}} 属性</dd>
<dt>{{domxref("XMLHttpRequest/load_event", "load")}}</dt>
<dd>{{domxref("XMLHttpRequest")}}请求成功完成时触发。<br>
也可以使用 {{domxref("XMLHttpRequestEventTarget/onload", "onload")}} 属性.</dd>
<dt>{{domxref("XMLHttpRequest/loadend_event", "loadend")}}</dt>
<dd>当请求结束时触发, 无论请求成功 ( {{domxref("XMLHttpRequest/load_event", "load")}}) 还是失败 ({{domxref("XMLHttpRequest/abort_event", "abort")}} 或 {{domxref("XMLHttpRequest/error_event", "error")}})。<br>
也可以使用 {{domxref("XMLHttpRequestEventTarget/onloadend", "onloadend")}} 属性。</dd>
<dt>{{domxref("XMLHttpRequest/loadstart_event", "loadstart")}}</dt>
<dd>接收到响应数据时触发。<br>
也可以使用 {{domxref("XMLHttpRequestEventTarget/onloadstart", "onloadstart")}} 属性。</dd>
<dt>{{domxref("XMLHttpRequest/progress_event", "progress")}}</dt>
<dd>当请求接收到更多数据时，周期性地触发。<br>
也可以使用 {{domxref("XMLHttpRequestEventTarget/onprogress", "onprogress")}} 属性。</dd>
<dt>{{domxref("XMLHttpRequest/timeout_event", "timeout")}}</dt>
<dd>在预设时间内没有接收到响应时触发。<br>
也可以使用 {{domxref("XMLHttpRequestEventTarget/ontimeout", "ontimeout")}} 属性。</dd>
</dl>
<h2 id="规范">规范</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">规范</th>
<th scope="col">状态</th>
<th scope="col">注释</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName('XMLHttpRequest')}}</td>
<td>{{Spec2('XMLHttpRequest')}}</td>
<td>Live standard, latest version</td>
</tr>
</tbody>
</table>
<h2 id="浏览器兼容性">浏览器兼容性</h2>
<div>{{Compat("api.XMLHttpRequest")}}</div>
<h2 id="参见">参见</h2>
<ul>
<li>{{domxref("XMLSerializer")}}：将 DOM 树解析为 XML 对象</li>
<li>MDN 教程中的 <code>XMLHttpRequest</code>：
<ul>
<li><a href="/en-US/docs/AJAX/Getting_Started">Ajax — Getting Started</a></li>
<li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li>
<li><a href="/en-US/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a></li>
</ul>
</li>
<li><a class="external" href="http://www.html5rocks.com/en/tutorials/file/xhr2/">HTML5 Rocks — New Tricks in XMLHttpRequest2</a></li>
<li>HTTP Feature-Policy 指令 {{httpheader("Feature-Policy/sync-xhr", "sync-xhr")}}</li>
</ul>