XMLHttpRequest

翻譯不完整。 請幫助我們翻譯這篇文章!

藉由 XMLHttpRequest(XHR)物件的方式來存取伺服器端的資料,可以讓你直接經由指定的 URL 擷取資料卻不用刷新整個網頁。這樣一來當想要更新網頁中的部分資料時,不再需要藉由刷新整個頁面的方法而中斷使用者的操作。在AJAX應用中 XMLHttpRequest 被大量的使用。

雖然 XMLHttpRequest 這個物件的命名包含了 XML 與 HTTP 等字眼,但實際上 XMLHttpRequest 可用來接收任何類型的資料,不限於 XML 類型而已。

如果在資料交換的時候,需要接收從伺服器端傳來的事件或訊息:可以考慮透過EventSource介面使用server-sent 事件。對於和伺服器全雙工的資訊交換,WebSockets 可能是較佳的選擇。

建構式

XMLHttpRequest()
建構式用來初始化一個 XMLHttpRequest 物件。必須在其他任何所屬方法被呼叫之前被呼叫。

屬性

此介面也繼承了 XMLHttpRequestEventTargetEventTarget 的屬性。

XMLHttpRequest.onreadystatechange
一個 EventHandler(事件處理器)函式,會於 readyState 屬性之狀態改變時被呼叫。
XMLHttpRequest.readyState Read only
回傳一個無符號短整數(unsigned short)代表請求之狀態。
XMLHttpRequest.response Read only
回傳的內容可能是 ArrayBufferBlobDocument、JavaScript 物件或 DOMString。完全根據 XMLHttpRequest.responseType 的值決定回傳的內容為何種型態,資料為回應實體中的內容(response entity body)。
XMLHttpRequest.responseText Read only
回傳一個 DOMString,其內容為請求之回應的文字內容。如請求失敗或尚未發送,則為 null
XMLHttpRequest.responseType
為一可列舉(enumerated)值,定義回應內容的資料類型(response type)。
XMLHttpRequest.responseURL Read only
回傳一個回應(response)的序列化 URL,如 URL 為 null 則回傳空字串。
XMLHttpRequest.responseXML Read only
回傳一個 Document,其內容為請求之回應內容所解析成的文件物件。如請求失敗或尚未發送,又或是無法解析成 XML、HTML,則為 null。Not available in workers.
XMLHttpRequest.status Read only
回傳一個無符號短整數(unsigned short)表示已發送請求之回應的狀態。
XMLHttpRequest.statusText Read only
回傳一個 DOMString 表示 HTTP 伺服器回應之字串。和 XMLHTTPRequest.status 不同的是,XMLHttpRequest.statusText 包含了回應的整個文字訊息(如 "200 OK")。

Note: The HTTP/2 specification (8.1.2.4 Response Pseudo-Header Fields), HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.

XMLHttpRequest.timeout
為一無符號長整數(unsigned long),代表一個請求在逾時而被自動中止前的可等待時間(毫秒)。
XMLHttpRequestEventTarget.ontimeout
為一 EventHandler 物件,會於請求逾時時被呼叫。
XMLHttpRequest.upload Read only
為一 XMLHttpRequestUpload 物件,代表上傳的進度。
XMLHttpRequest.withCredentials
布林值。表示是否允許在跨站存取(cross-site Access-Control)之請求當中,發送如 cookies 或 authorization headers 等憑證資訊(credentials)。

非標準屬性

XMLHttpRequest.channelRead only
是一個 nsIChannel。當執行要求時,物件使用的頻道(Channel)。
XMLHttpRequest.mozAnonRead only
為一個布林值。如果為真,請求就會以沒有cookie及authentication headers的方式送出。
XMLHttpRequest.mozSystemRead only
這是一個布林值。If true, the same origin policy will not be enforced on the request.
XMLHttpRequest.mozBackgroundRequest
這是一個布林值。指出該物件是否為一個背景型態的服務要求。
XMLHttpRequest.mozResponseArrayBuffer 已過時 Gecko 6 Read only
Is an ArrayBuffer. The response to the request, as a JavaScript typed array.
XMLHttpRequest.multipart已過時 Gecko 22
This Gecko-only feature, a boolean, was removed in Firefox/Gecko 22. Please use Server-Sent Events, Web Sockets, or responseText from progress events instead.

事件處理器

所有瀏覽器都支援 XMLHttpRequest 物件實體的 onreadystatechange 屬性。

之後,各個瀏覽器實作了多種額外的事件處理器(如 onloadonerroronprogress 等)。請參考使用 XMLHttpRequest

除了以 on* 屬性來設定事件處理函式,更多現代覽瀏器(包括 Firefox)也支援使用標準的 addEventListener() API 註冊監聽 XMLHttpRequest 的事件。

方法

XMLHttpRequest.abort()
中止已發出的請求。
XMLHttpRequest.getAllResponseHeaders()
回傳所有的回應標頭(response headers),為一以斷行字元(CRLF)分行的字串,如未接收到回應則為 null
XMLHttpRequest.getResponseHeader()
回傳指定標頭文字之字串,假如回應尚未被接收或是標頭不存在於回應中則為 null
XMLHttpRequest.open()
初始化一個請求。此方法用於 JavaScript 中;若要在 native code 中初始化請求,請以 openRequest() 作為替代。
XMLHttpRequest.overrideMimeType()
覆寫伺服器回傳的 MIME type。
XMLHttpRequest.send()
發送請求。如果為非同步請求(預設值),此方法將在發出請求後便立即回傳(return)。
XMLHttpRequest.setRequestHeader()
設定 HTTP 請求標頭(request header)值。setRequestHeader() 可被呼叫的時間點必須於 open() 之後、在 send() 之前。

非標準方法

XMLHttpRequest.init()
使用 C++ 程式時,用來初始化這個物件。
注意: 請勿在 JavaScript 中呼叫這個方法。
XMLHttpRequest.openRequest()
初始化請求。這方法是用於原生程式,若想在 JavaScript 中初始化一個請求,請使用 open() 這個方法來代替。請參照 open() 的相關文件。
XMLHttpRequest.sendAsBinary()
另一種 send() 方法,用來送出二進位資料。

規範

規範 狀態 註解
XMLHttpRequest Living Standard Live standard, latest version

瀏覽器相容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
XMLHttpRequestChrome Full support 1Edge Full support 12
Full support 12
No support 12 — 79
Notes
Notes Implemented via ActiveXObject('Microsoft.XMLHTTP')
Firefox Full support 1IE Full support 7
Full support 7
Full support 5
Notes
Notes Implemented via ActiveXObject('Microsoft.XMLHTTP')
Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
abortChrome Full support 18Edge Full support 12Firefox Full support YesIE Full support 5Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
abort eventChrome Full support YesEdge Full support ≤79Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
error eventChrome Full support YesEdge Full support ≤79Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
getAllResponseHeadersChrome Full support 1Edge Full support 12Firefox Full support 4
Notes
Full support 4
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
IE Full support 5Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 4
Notes
Full support 4
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
getResponseHeaderChrome Full support 1Edge Full support 12Firefox Full support 1
Notes
Full support 1
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
IE Full support 5Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4
Notes
Full support 4
Notes
Notes Starting from Firefox 49, empty headers are returned as empty strings in case the preference network.http.keep_empty_response_headers_as_empty_string is set to true, defaulting to false. Before Firefox 49 empty headers had been ignored. Since Firefox 50 the preference defaults to true.
Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
load eventChrome Full support YesEdge Full support ≤79Firefox Full support YesIE Full support 9Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
loadend eventChrome Full support YesEdge Full support ≤79Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
loadstart eventChrome Full support YesEdge Full support ≤79Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
onreadystatechangeChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 5Opera Full support 9Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
openChrome Full support 1Edge Full support 12Firefox Full support 1
Notes
Full support 1
Notes
Notes Starting in Firefox 30, synchronous requests on the main thread have been deprecated due to their negative impact on performance and the user experience. Therefore, the async parameter may not be false except in a Worker.
IE Full support 5Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4
Notes
Full support 4
Notes
Notes Starting in Firefox 30, synchronous requests on the main thread have been deprecated due to their negative impact on performance and the user experience. Therefore, the async parameter may not be false except in a Worker.
Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
overrideMimeTypeChrome Full support 1Edge Full support 12Firefox Full support YesIE Full support 11
Full support 11
Full support 5
Notes
Notes Implemented via ActiveXObject
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 1.0
progress eventChrome Full support YesEdge Full support ≤79Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
readyStateChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
responseChrome Full support 9Edge Full support 12Firefox Full support 6IE Full support 10Opera Full support 11.6Safari Full support 5.1WebView Android Full support ≤37Chrome Android Full support 18Firefox Android Full support 6Opera Android Full support 12Safari iOS Full support 6Samsung Internet Android Full support 1.0
responseTextChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 5
Notes
Full support 5
Notes
Notes Before Internet Explorer 10, the value of XMLHttpRequest.responseText could be read only once the request was complete.
Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
responseTypeChrome Full support 31Edge Full support 12Firefox Full support 6IE Full support 10Opera Full support 18Safari Full support 7WebView Android Full support 55Chrome Android Full support 55Firefox Android Full support 50Opera Android Full support 42Safari iOS Full support 7Samsung Internet Android Full support 6.0
responseURLChrome Full support 37Edge Full support 14Firefox Full support 32IE No support NoOpera Full support 24Safari Full support 8WebView Android Full support 37Chrome Android Full support 37Firefox Android Full support 32Opera Android Full support 24Safari iOS Full support YesSamsung Internet Android Full support 3.0
responseXMLChrome Full support YesEdge Full support 12Firefox Full support Yes
Notes
Full support Yes
Notes
Notes Prior to Firefox 51, an error parsing the received data added a <parsererror> node to the top of the Document and then returned the Document in whatever state it happens to be in. This was inconsistent with the specification. Starting with Firefox 51, this scenario now correctly returns null as per the spec.
IE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes Prior to Firefox 51, an error parsing the received data added a <parsererror> node to the top of the Document and then returned the Document in whatever state it happens to be in. This was inconsistent with the specification. Starting with Firefox 51, this scenario now correctly returns null as per the spec.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
sendChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 5Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
sendAsBinary
DeprecatedNon-standard
Chrome No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
Edge No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
Firefox No support 2 — 31IE No support NoOpera No support NoSafari No support NoWebView Android No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
Chrome Android No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
Firefox Android No support 4 — 31Opera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
Notes
No support No
Notes
Notes There is a polyfill available to support sendAsBinary().
setRequestHeaderChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 5Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
statusChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7
Notes
Full support 7
Notes
Notes Internet Explorer version 5 and 6 supported ajax calls using ActiveXObject()
Opera Full support 8Safari Full support 1.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
statusTextChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 7
Notes
Full support 7
Notes
Notes Internet Explorer version 5 and 6 supported ajax calls using ActiveXObject()
Opera Full support YesSafari Full support 1.2WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 1.0
timeoutChrome Full support 29Edge Full support 12Firefox Full support 12IE Full support 8Opera Full support 17
Full support 17
No support 12 — 16
Safari Full support 6.1WebView Android Full support ≤37Chrome Android Full support 29Firefox Android Full support 14Opera Android Full support 18
Full support 18
No support 12 — 16
Safari iOS Full support 7Samsung Internet Android Full support 2.0
timeout eventChrome Full support YesEdge Full support ≤18Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
uploadChrome Full support 1Edge Full support 12Firefox Full support YesIE Full support 10Opera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support 18Firefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 1.0
withCredentialsChrome Full support 3Edge Full support 12Firefox Full support 3.5
Notes
Full support 3.5
Notes
Notes Starting with Firefox 11, it's no longer supported to use the withCredentials attribute when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR exception.
IE Full support 10
Notes
Full support 10
Notes
Notes Internet Explorer versions 8 and 9 supported cross-domain requests (CORS) using XDomainRequest.
Opera Full support 12Safari Full support 4WebView Android Full support ≤37Chrome Android Full support 18Firefox Android Full support 4
Notes
Full support 4
Notes
Notes Starting with Firefox 11, it's no longer supported to use the withCredentials attribute when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR exception.
Opera Android Full support 12Safari iOS Full support 3.2Samsung Internet Android Full support 1.0

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
See implementation notes.
See implementation notes.

參見