XMLHttpRequest

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

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

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

建構式

XMLHttpRequest()

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

屬性

此介面也繼承了 XMLHttpRequestEventTarget (en-US)EventTarget 的屬性。

XMLHttpRequest.onreadystatechange (en-US)

一個事件處理器函式,會於 readyState 屬性之狀態改變時被呼叫。

XMLHttpRequest.readyState Read only

回傳一個無符號短整數(unsigned short)代表請求之狀態。

XMLHttpRequest.response (en-US) Read only

回傳的內容可能是 ArrayBufferBlobDocument (en-US)、JavaScript 物件或 DOMString。完全根據 XMLHttpRequest.responseType (en-US) 的值決定回傳的內容為何種型態,資料為回應實體中的內容(response entity body)。

XMLHttpRequest.responseText (en-US) Read only

回傳一個 DOMString,其內容為請求之回應的文字內容。如請求失敗或尚未發送,則為 null

XMLHttpRequest.responseType (en-US)

為一可列舉(enumerated)值,定義回應內容的資料類型(response type)。

XMLHttpRequest.responseURL (en-US) Read only

回傳一個回應(response)的序列化 URL,如 URL 為 null 則回傳空字串。

XMLHttpRequest.responseXML (en-US) Read only

回傳一個 Document (en-US),其內容為請求之回應內容所解析成的文件物件。如請求失敗或尚未發送,又或是無法解析成 XML、HTML,則為 null。Not available in workers.

XMLHttpRequest.status Read only

回傳一個無符號短整數(unsigned short)表示已發送請求之回應的狀態。

XMLHttpRequest.statusText (en-US) Read only

回傳一個 DOMString 表示 HTTP 伺服器回應之字串。和 XMLHTTPRequest.status 不同的是,XMLHttpRequest.statusText 包含了回應的整個文字訊息(如 "200 OK")。

備註: 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 (en-US)

為一無符號長整數(unsigned long),代表一個請求在逾時而被自動中止前的可等待時間(毫秒)。

XMLHttpRequestEventTarget.ontimeout

為一 event handler 物件,會於請求逾時時被呼叫。

XMLHttpRequest.upload (en-US) Read only

為一 XMLHttpRequestUpload (en-US) 物件,代表上傳的進度。

XMLHttpRequest.withCredentials

布林值 (en-US)。表示是否允許在跨站存取(cross-site Access-Control)之請求當中,發送如 cookies 或 authorization headers 等憑證資訊(credentials)。

非標準屬性

XMLHttpRequest.channel (en-US)Read only

是一個 nsIChannel。當執行要求時,物件使用的頻道(Channel)。

XMLHttpRequest.mozAnon (en-US)Read only

為一個布林值。如果為真,請求就會以沒有 cookie 及 authentication headers 的方式送出。

XMLHttpRequest.mozSystem (en-US)Read only

這是一個布林值。If true, the same origin policy will not be enforced on the request.

XMLHttpRequest.mozBackgroundRequest (en-US)

這是一個布林值。指出該物件是否為一個背景型態的服務要求。

XMLHttpRequest.mozResponseArrayBuffer 已棄用 Read only

Is an ArrayBuffer. The response to the request, as a JavaScript typed array.

XMLHttpRequest.multipart 已棄用

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() (en-US)

中止已發出的請求。

XMLHttpRequest.getAllResponseHeaders() (en-US)

回傳所有的回應標頭(response headers),為一以斷行字元(CRLF (en-US))分行的字串,如未接收到回應則為 null

XMLHttpRequest.getResponseHeader() (en-US)

回傳指定標頭文字之字串,假如回應尚未被接收或是標頭不存在於回應中則為 null

XMLHttpRequest.open() (en-US)

初始化一個請求。此方法用於 JavaScript 中;若要在 native code 中初始化請求,請以 openRequest() 作為替代。

XMLHttpRequest.overrideMimeType() (en-US)

覆寫伺服器回傳的 MIME type。

XMLHttpRequest.send() (en-US)

發送請求。如果為非同步請求(預設值),此方法將在發出請求後便立即回傳(return)。

XMLHttpRequest.setRequestHeader()

設定 HTTP 請求標頭(request header)值。setRequestHeader() 可被呼叫的時間點必須於 open() 之後、在 send() 之前。

非標準方法

XMLHttpRequest.init()

使用 C++ 程式時,用來初始化這個物件。

警告: 請勿在 JavaScript 中呼叫這個方法。

XMLHttpRequest.openRequest()

初始化請求。這方法是用於原生程式,若想在 JavaScript 中初始化一個請求,請使用 open() 這個方法來代替。請參照 open() 的相關文件。

XMLHttpRequest.sendAsBinary() 已棄用

另一種 send() 方法,用來送出二進位資料。

規範

Specification
XMLHttpRequest Standard
# interface-xmlhttprequest

瀏覽器相容性

BCD tables only load in the browser

參見