XMLHttpRequest

使用 XMLHttpRequest 物件與伺服器互動,你可以從 URL 擷取資料且不須刷新整個頁面。這使得網頁可以只更新其中的一部分而不中斷使用者的操作。XMLHttpRequest 被大量使用於 AJAX 應用。

歷史

XMLHttpRequest 最早為微軟所設計,後被 Mozilla、Apple 及 Google 採用。目前WHATWG 進行標準化。僅管名字用的是 XML 與 HTTP,XMLHttpRequest 其實可以用來接收任何類型的資料,並不限於 XML。同時它也支援 HTTP 以外的通訊協定(包括 fileftp)。

建構式

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 Not available to workers
回傳一個 Document,其內容為請求之回應內容所解析成的文件物件。如請求失敗或尚未發送,又或是無法解析成 XML、HTML,則為 null
XMLHttpRequest.status Read only
回傳一個無符號短整數(unsigned short)表示已發送請求之回應的狀態。
XMLHttpRequest.statusText Read only
回傳一個 DOMString 表示 HTTP 伺服器回應之字串。和 XMLHTTPRequest.status 不同的是,XMLHttpRequest.statusText 包含了回應的整個文字訊息(如 "200 OK")。

Note: via 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
Is a nsIChannel. The channel used by the object when performing the request.
XMLHttpRequest.mozAnonRead only
Is a boolean. If true, the request will be sent without cookie and authentication headers.
XMLHttpRequest.mozSystemRead only
Is a boolean. If true, the same origin policy will not be enforced on the request.
XMLHttpRequest.mozBackgroundRequest
Is a boolean. It indicates whether or not the object represents a background service request.
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 等),Firefox 也同樣支援這些屬性。詳細請參考 nsIXMLHttpRequestEventTarget使用 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()
Initializes the object for use from C++ code.
Warning: This method must not be called from JavaScript.
XMLHttpRequest.openRequest()
Initializes a request. This method is to be used from native code; to initialize a request from JavaScript code, use open() instead. See the documentation for open().
XMLHttpRequest.sendAsBinary()
A variant of the send() method that sends binary data.

規範

Specification Status Comment
XMLHttpRequest Living Standard Live standard, latest version

瀏覽器相容性

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (XHR1) 1 (Yes) 1.0 (1.7 or earlier) 7 (Yes) 1.2
send(ArrayBuffer) 9 (Yes) 9.0 (9.0) 10 11.60 ?
send(ArrayBufferView) 22 (Yes) 20.0 (20.0) ? ? ?
send(Blob) 7 (Yes) 3.6 (1.9.2) 10 12 ?
send(FormData) 6 (Yes) 4.0 (2.0) 10 12 ?
sendAsBinary(DOMString) No support[1] No support 2.0 (1.8.1) No support No support No support
response 10 (Yes) 6.0 (6.0) 10 11.60 (Yes)
responseType = 'arraybuffer' 10 (Yes) 6.0 (6.0) 10 11.60 (Yes)
responseType = 'blob' 19 (Yes) 6.0 (6.0) 10 12 (Yes)
responseType = 'document' 18 (Yes) 11.0 (11.0) 10 No support 6.1
responseType = 'json' 31 No support 10.0 (10.0) No support 12[2]
No support 16
17
(Yes)
Progress Events 7 (Yes) 3.5 (1.9.1) 10 12 (Yes)
withCredentials 3 (Yes) 3.5 (1.9.1) 10 12 4
timeout 29.0 (Yes) 12.0 (12.0) 8 12
16
(Yes)
responseType = 'moz-blob' No support No support 12.0 (12.0) No support No support No support
Feature Android Chrome for Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support ? 1.0 (Yes) (Yes) ? ? ?
send(ArrayBuffer) ? ? (Yes) ? ? ? ?
send(ArrayBufferView) ? ? (Yes) ? ? ? ?
send(Blob) ? ? (Yes) ? ? ? ?
send(FormData) ? ? (Yes) ? ? ? ?
sendAsBinary(DOMString) ? ? No support ? ? ? ?
response ? ? (Yes) ? ? ? ?
responseType = 'arraybuffer' ? ? (Yes) ? ? ? ?
responseType = 'blob' ? ? (Yes) ? ? ? ?
responseType = 'document' ? ? (Yes) ? ? ? ?
responseType = 'json' ? ? No support ? ? ? ?
Progress Events ? ? (Yes) ? ? ? ?
withCredentials ? ? (Yes) ? ? ? ?
timeout ? ? (Yes) ? ? ? ?
responseType = 'moz-blob' ? ? No support ? ? ? ?

[1] There is a polyfill available to support sendAsBinary().

[2] Before switching to Blink/Chromium, Opera supported responseType=json between Opera 12 and Opera 15. Support was added again in Opera 17.

參見

 
 

文件標籤與貢獻者

 此頁面的貢獻者: jackblackevo, teoli, foxbrush, natevw
 最近更新: jackblackevo,