--- 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>