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
|
---
title: XMLHttpRequest
slug: Web/API/XMLHttpRequest
tags:
- AJAX
- Fixit
- HTTP
- MakeBrowserAgnostic
- NeedsCleanup
- NeedsMobileBrowserCompatibility
- NeedsTranslation
- TopicStub
- XMLHttpRequest
translation_of: Web/API/XMLHttpRequest
---
<div>{{DefaultAPISidebar("XMLHttpRequest")}}</div>
<p><span class="seoSummary">藉由 <code>XMLHttpRequest</code>（XHR）物件的方式來存取伺服器端的資料，可以讓你直接經由指定的 URL 擷取資料卻不用刷新整個網頁。這樣一來當想要更新網頁中的部分資料時，不再需要藉由刷新整個頁面的方法而中斷使用者的操作。在</span>{{Glossary("AJAX")}}應用中 <code>XMLHttpRequest</code> 被大量的使用。</p>
<p>{{InheritanceDiagram(650, 150)}}</p>
<p>雖然 <span class="seoSummary"><code>XMLHttpRequest</code></span> 這個物件的命名包含了 XML 與 HTTP 等字眼，但實際上 <code>XMLHttpRequest</code> 可用來接收任何類型的資料，不限於 XML 類型而已。</p>
<p>如果在資料交換的時候，需要接收從伺服器端傳來的事件或訊息：可以考慮透過{{domxref("EventSource")}}介面使用<a href="/zh-TW/docs/Web/API/Server-sent_events">server-sent 事件</a>。對於和伺服器全雙工的資訊交換，<a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</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 id="xmlhttprequest-onreadystatechange">{{domxref("XMLHttpRequest.onreadystatechange")}}</dt>
<dd>一個 {{event("Event_handlers")}}（事件處理器）函式，會於 <code>readyState</code> 屬性之狀態改變時被呼叫。</dd>
<dt id="xmlhttprequest-readystate">{{domxref("XMLHttpRequest.readyState")}} {{readonlyinline}}</dt>
<dd>回傳一個無符號短整數（<code>unsigned short</code>）代表請求之狀態。</dd>
<dt>{{domxref("XMLHttpRequest.response")}} {{readonlyinline}}</dt>
<dd>回傳的內容可能是 {{domxref("ArrayBuffer")}}、{{domxref("Blob")}}、{{domxref("Document")}}、JavaScript 物件或 {{domxref("DOMString")}}。完全根據 {{domxref("XMLHttpRequest.responseType")}} 的值決定回傳的內容為何種型態，資料為回應實體中的內容（response entity body）。</dd>
<dt id="xmlhttprequest-responsetext">{{domxref("XMLHttpRequest.responseText")}} {{readonlyinline}}</dt>
<dd>回傳一個 {{domxref("DOMString")}}，其內容為請求之回應的文字內容。如請求失敗或尚未發送，則為 <code>null</code>。</dd>
<dt id="xmlhttprequest-responsetype">{{domxref("XMLHttpRequest.responseType")}}</dt>
<dd>為一可列舉（enumerated）值，定義回應內容的資料類型（response type）。</dd>
<dt id="xmlhttprequest-responsexml">{{domxref("XMLHttpRequest.responseURL")}} {{readonlyinline}}</dt>
<dd>回傳一個回應（response）的序列化 URL，如 URL 為 null 則回傳空字串。</dd>
<dt id="xmlhttprequest-responsexml">{{domxref("XMLHttpRequest.responseXML")}} {{readonlyinline}}</dt>
<dd>回傳一個 {{domxref("Document")}}，其內容為請求之回應內容所解析成的文件物件。如請求失敗或尚未發送，又或是無法解析成 XML、HTML，則為 <code>null</code>。Not available in workers.</dd>
<dt id="xmlhttprequest-status">{{domxref("XMLHttpRequest.status")}} {{readonlyinline}}</dt>
<dd>回傳一個無符號短整數（<code>unsigned short</code>）表示已發送請求之回應的狀態。</dd>
<dt id="xmlhttprequest-statustext">{{domxref("XMLHttpRequest.statusText")}} {{readonlyinline}}</dt>
<dd>回傳一個 {{domxref("DOMString")}} 表示 HTTP 伺服器回應之字串。和 {{domxref("XMLHTTPRequest.status")}} 不同的是，<code>XMLHttpRequest.statusText</code> 包含了回應的整個文字訊息（如 "<code>200 OK</code>"）。</dd>
</dl>
<div class="note">
<p><strong>Note:</strong> The HTTP/2 specification (<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 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.</p>
</div>
<dl>
<dt id="xmlhttprequest-timeout">{{domxref("XMLHttpRequest.timeout")}}</dt>
<dd>為一無符號長整數（<code>unsigned long</code>），代表一個請求在逾時而被自動中止前的可等待時間（毫秒）。</dd>
<dt id="xmlhttprequesteventtarget-ontimeout">{{domxref("XMLHttpRequestEventTarget.ontimeout")}}</dt>
<dd>為一 {{event("Event_handlers")}} 物件，會於請求逾時時被呼叫。{{gecko_minversion_inline("12.0")}}</dd>
<dt id="xmlhttprequest-upload">{{domxref("XMLHttpRequest.upload")}} {{readonlyinline}}</dt>
<dd>為一 {{domxref("XMLHttpRequestUpload")}} 物件，代表上傳的進度。</dd>
<dt id="xmlhttprequest-withcredentials">{{domxref("XMLHttpRequest.withCredentials")}}</dt>
<dd>{{domxref("Boolean","布林值")}}。表示是否允許在跨站存取（cross-site <code>Access-Control</code>）之請求當中，發送如 cookies 或 authorization headers 等憑證資訊（credentials）。</dd>
</dl>
<h3 id="非標準屬性">非標準屬性</h3>
<dl>
<dt>{{domxref("XMLHttpRequest.channel")}}{{ReadOnlyInline}}</dt>
<dd>是一個 {{Interface("nsIChannel")}}。當執行要求時，物件使用的頻道（Channel）。</dd>
<dt>{{domxref("XMLHttpRequest.mozAnon")}}{{ReadOnlyInline}}</dt>
<dd>為一個布林值。如果為真，請求就會以沒有cookie及authentication headers的方式送出。</dd>
<dt>{{domxref("XMLHttpRequest.mozSystem")}}{{ReadOnlyInline}}</dt>
<dd>這是一個布林值。If true, the same origin policy will not be enforced on the request.</dd>
<dt>{{domxref("XMLHttpRequest.mozBackgroundRequest")}}</dt>
<dd>這是一個布林值。指出該物件是否為一個背景型態的服務要求。</dd>
<dt>{{domxref("XMLHttpRequest.mozResponseArrayBuffer")}}{{gecko_minversion_inline("2.0")}} {{obsolete_inline("6")}} {{ReadOnlyInline}}</dt>
<dd>Is an <a href="/zh-TW/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer"><code>ArrayBuffer</code></a>. The response to the request, as a JavaScript typed array.</dd>
<dt>{{domxref("XMLHttpRequest.multipart")}}{{obsolete_inline("22")}}</dt>
<dd><strong>This Gecko-only feature, a boolean, was removed in Firefox/Gecko 22.</strong> Please use <a href="/zh-TW/docs/Web/API/Server-sent_events">Server-Sent Events</a>, <a href="/zh-TW/docs/Web/API/WebSockets_API">Web Sockets</a>, or <code>responseText</code> from progress events instead.</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="https://developer.mozilla.org/zh-TW/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">使用 XMLHttpRequest</a>。</p>
<p>除了以 <code>on*</code> 屬性來設定事件處理函式，更多現代覽瀏器（包括 Firefox）也支援使用標準的 <code><a href="/zh-TW/docs/Web/API/EventTarget/addEventListener">addEventListener()</a></code> API 註冊監聽 <code>XMLHttpRequest</code> 的事件。</p>
<dl>
</dl>
<h2 id="方法">方法</h2>
<dl>
<dt>{{domxref("XMLHttpRequest.abort()")}}</dt>
<dd>中止已發出的請求。</dd>
<dt>{{domxref("XMLHttpRequest.getAllResponseHeaders()")}}</dt>
<dd>回傳所有的回應標頭（response headers），為一以斷行字元（<a href="/zh-TW/docs/Glossary/CRLF">CRLF</a>）分行的字串，如未接收到回應則為 <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-TW/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest#openRequest()"><code>openRequest()</code></a> 作為替代。</dd>
<dt>{{domxref("XMLHttpRequest.overrideMimeType()")}}</dt>
<dd>覆寫伺服器回傳的 MIME type。</dd>
<dt>{{domxref("XMLHttpRequest.send()")}}<span class="hidden"> </span></dt>
<dd>發送請求。如果為非同步請求（預設值），此方法將在發出請求後便立即回傳（return）。</dd>
<dt>{{domxref("XMLHttpRequest.setRequestHeader()")}}</dt>
<dd>設定 HTTP 請求標頭（request header）值。<code>setRequestHeader()</code> 可被呼叫的時間點必須於 <a href="#open"><code>open()</code></a> 之後、在 <code>send()</code> 之前。</dd>
</dl>
<h3 id="非標準方法">非標準方法</h3>
<dl>
<dt>{{domxref("XMLHttpRequest.init()")}}</dt>
<dd>使用 C++ 程式時，用來初始化這個物件。</dd>
</dl>
<div class="warning"><strong>注意:</strong> 請勿在 JavaScript 中呼叫這個方法。</div>
<dl>
<dt>{{domxref("XMLHttpRequest.openRequest()")}}</dt>
<dd>初始化請求。這方法是用於原生程式，若想在 JavaScript 中初始化一個請求，請使用 <a class="internal" href="/zh-TW/docs/Mozilla/Tech/XPCOM/Reference/Interface/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>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">規範</th>
<th scope="col">狀態</th>
<th scope="col">註解</th>
</tr>
<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>MDN 上涵蓋 XMLHttpRequest 的相關教學：
<ul>
<li><a href="/zh-TW/docs/AJAX/Getting_Started">Ajax — Getting Started</a></li>
<li><a href="/zh-TW/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">使用 XMLHttpRequest</a></li>
<li><a href="/zh-TW/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a></li>
<li><a href="/zh-TW/docs/Web/API/FormData"><code>FormData</code></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><code>Chrome scope availability</code> — how to access XMLHttpRequest from JSM modules etc., which do not have access to DOM
<ul>
<li><a href="/zh-TW/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.importGlobalProperties">Components.utils.importGlobalProperties</a></li>
<li><a href="/zh-TW/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest">nsIXMLHttpRequest</a></li>
</ul>
</li>
</ul>
|
