1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
---
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>
|
