Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

XMLHttpRequest


XMLHttpRequest是一個由微軟所設計的Javascript物件,爾後Mozilla, Apple和Google也都相繼採用,直到今日已經變成W3C標準之一。有了XMLHttpRequest,我們可以很容易地從URL取得資料而不用刷新頁面,網頁將能夠在不影響使用者下只進行部分更新;在AJAX應用中XMLHttpRequest佔了相當重要的地位。

不只是名稱前冠上的XML,XMLHttpRequest可以取得XML以外型態的資料,而且也支援file或ftp等其他的協定,不只是HTTP而已。

簡單一行程式碼便可以建立一個XMLHttpRequest物件。

var req = new XMLHttpRequest();

詳細XMLHttpRequest物件的使用說明請參照Using XMLHttpRequest一文。

方法總覽

XMLHttpRequest(JSObject objParameters);
void abort();
DOMString getAllResponseHeaders();
DOMString? getResponseHeader(DOMString header);
void open(DOMString method, DOMString url, optional boolean async, optional DOMString? user, optional DOMString? password);
void overrideMimeType(DOMString mime);
void send();
void send(ArrayBuffer data);
void send(Blob data);
void send(Document data);
void send(DOMString? data);
void send(FormData data);
void setRequestHeader(DOMString header, DOMString value);
非標準方法
[noscript] void init(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow);
[noscript] void openRequest(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password);
void sendAsBinary(in DOMString body);

屬性

屬性 型態 描述

onreadystatechange

Function?

當readyState屬性改變時呼叫的Javascript函數,是從使用者介面的執行緒中呼叫。

警告: 在進行同步請求作業下,不要使用。
readyState unsigned short

請求狀態

Value State Description
0 UNSENT open()方法尚未呼叫
1 OPENED send()方法尚未呼叫
2 HEADERS_RECEIVED send()方法已被呼叫,而且可取得header與狀態
3 LOADING 回應資料下載中,此時responseText會擁有部分資料
4 DONE 作業完成
response varies

依據responseType不同可能會是ArrayBuffer, Blob, Document, Javascript物件或字串;如果請求失敗或尚未完成,則為null。

responseText Read only DOMString 回應請求的字串資料;如果請求失敗或尚未完成,則為null。
responseType XMLHttpRequestResponseType

可設定值有:

資料型態
"" (empty string) 字串(預設值)
"arraybuffer" ArrayBuffer
"blob" Blob
"document" Document
"json" JavaScript object, parsed from a JSON string returned by the server
"text" String
"moz-blob" FireFox專用;允許在請求尚在進行中就開始接收已取得的Blob資料,所以能夠在”progress”事件處理器中就提早開始取得資料進行作業。
"moz-chunked-text" FireFox專用;類似於”text”,但為串流形式,所以只有在”progress”事件觸發時才可以取得資料,而且資料只包含到最後一次”progress”事件觸發時的狀態。當”progress”事件下會回傳字串資料,其餘則會回傳null。
"moz-chunked-arraybuffer" FireFox專用;類似於” arraybuffer”,但為串流形式,所以只有在”progress”事件觸發時才可以取得資料,而且資料只包含到最後一次”progress”事件觸發時的狀態。在非”progress”事件下會回傳null。
Note: 自Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8)和Webkit組建528起,當進行同步請求時,無法使用responseType屬性,任何嘗試會導致NS_ERROR_DOM_INVALID_ACCESS_ERR例外錯誤,目前這項行為定義也已經遞交W3C審核。
responseXML Read only Document?

回應請求的DOM Document物件,如果請求失敗、尚未完成或回傳資料無法解析為XML或HTML檔,則為null。回應會如同text/html一般一樣被解析。當responseType被設為”document”而且請求亦為非同步,回應會如同text/html一般一樣被解析。

Note: 如果伺服器端回傳的header不是text/html的內容型態,我們能夠用overrideMimeType()方法強迫XMLHttpRequest將回應資料視為XML檔解析。
status Read only unsigned short 請求回應狀態,也就是HTTP回傳碼例如,200代表成功。
statusText Read only DOMString HTTP伺服器回傳的狀態字串,跟status比起來,會包完整的回傳訊息,例如”200 OK”。
timeout unsigned long

請求自動終止的倒數時間,單位為毫秒,若為零(預設)代表無倒數。

Note: 不可以在同步請求下進行時間倒數。
upload XMLHttpRequestUpload 上傳過程可以透過upload事件處理器追蹤。
withCredentials boolean

預設為false;指示是否應該使用如cookie或授權標頭檔等憑證進行跨站存取控制(cross-site Access-Control)請求。se.

Note: 這不影響同網站(same-stie)請求。
Note: 從Gecko 11.0開始(Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8),Gecko不再允許在同步請求下使用withCredentials,否則將導致NS_ERROR_DOM_INVALID_ACCESS_ERR例外錯誤。

非標準屬性

屬性 型態 描述
channel Read only nsIChannel 當請求時用的通道,如果沒有建立則為null,多重請求時是初始頻道,而非不同頻道。需要較高的存取權限。
mozAnon Read only boolean

若為true,cookie和驗證標頭檔(authentication headers)不會送出。

mozSystem Read only boolean

若為true,同網域政策(the same origin policy)不會實施。

mozBackgroundRequest boolean

指示是否進行背景服務請求;若為true則不會有任何載入群組連接到該請求,也不會有安全性對話框彈出,需要較高存取權限。

不會有安全性對話框彈出彈出,但當遇到需要安全信對話框的狀況,如驗證或錯誤憑證通知,請求會以失敗結束。

Note: 此屬性需要在呼叫open()前設定好。
mozResponseArrayBuffer 已過時 Gecko 6 Read only ArrayBuffer 請求回應如同Javascript陣列,當請求失敗或尚未送出時為null
multipart boolean

Gecko專屬且自Firefox/Gecko 22已移除,請改使用Server-Sent Events, Web Sockets或從progress 事件處理器中的responseText。

指示請求回應是否可能是一串多個XML文件,如為true,起始請求回應的內容型態必須是multipart/x-mixed-replace否則會引起錯誤,所有的請求必須是非同步。

這項屬性可以開啟伺服器推送支援,每一份回傳的XML文件,都會被解析成XML DOM文件,而且在文件載入之間會觸發onload事件。

Note: 當開啟這項屬性,onload事件處理器以及其他事件處理器在第一次載入XML文件後不會被重設,每次收到回應時都會觸發onload事件。

建構子

XMLHttpRequest()

呼叫任何方法前一定要先呼叫建構子。

Gecko/Fierfox 16 增加一項非標準參數用於建構子,加入這個參數會啟動無名模式(請參照Bug 692677)。設mozAnon屬性為true就如同呼叫AnonXMLHttpRequest()建構子,AnonXMLHttpRequest()建構子雖然屬於XMLHttpRequest規範一部分不過截至2012九月還沒有瀏覽器支援這個建構子。

XMLHttpRequest (
  JSObject objParameters
);
參數(非標準)
objParameters
底下有兩個參數可設定:
anon
Boolean: 當值為true,瀏覽器再抓取資源時將不會暴露來源和使用者安全性資料(user credentials),更重要是這代表除非利用setRequestHeader多加入cookie,不然cookie不會送出。
system
Boolean: 當值為true,允許跨站連結而不需要伺服器方面設定;不允許一起送出cookie和其他使用者安全性資料也就是說mozAnon參數需要設為true;只能在特許應用中使用,無法任意在其他載入firefox的網頁中使用。

方法

abort()

終止送出的請求。

getAllResponseHeaders()

DOMString getAllResponseHeaders();

以字串型態回傳所有回應標頭(headers),如果沒有則回傳null。請注意,對於多重請求,這個方法會回傳目前請求的回應而非最早的回應。

getResponseHeader()

DOMString? getResponseHeader(DOMString header);

以字串型態回傳指定標頭,如果沒有或請求尚未送出則回傳null。

open()

初始化請求。這個方法是給Javascript使用,對於本地端程式碼(native code),請使用openRequest()

Note: 若已經呼叫過open()或openRequest()卻又再重複呼叫,產生的效果等同於呼叫abort()。
void open(
   DOMString method,
   DOMString url,
   optional boolean async,
   optional DOMString user,
   optional DOMString password
);
參數
method
HTTP方法,如"GET", "POST", "PUT", "DELETE"等。
url
請求目的URL
async
預設為true,非必填,代表是否要送出非同步請求。如為false,send()方法於收到回應前不會回傳;如為true,透過事件處理器通知請求完成,當在多重請求下,此值必須為true,否則會導致例外錯誤。
user
預設為空字串,非必填,代表驗證用使用者名稱。
password
預設為空字串,非必填,代表驗證用密碼。

overrideMimeType()

覆寫伺服器回傳的MIME型態。可以利用這個方法強迫回傳資料解析成text/xml,即使伺服器回傳型態不是如此。必須在呼叫send()前呼叫。

void overrideMimeType(DOMString mimetype);

send()

送出請求,對於非同步請求會立即回傳,同步請求則會等到請求完成才回傳。

Note: 必須在呼叫send()前註冊事件處裡器。
void send();
void send(ArrayBuffer data);
void send(Blob data);
void send(Document data);
void send(DOMString? data);
void send(FormData data);
備註

如果資料為Document型態,在送出前會被序列化(serialized);Firefox 3之前的版本統一用UTF-8編碼送出Document型態資料,Firefox 3開始,除非沒有設定,會按照body.xmlEncoding設定進行編碼。

如果是nsIInputStream型態,必須要符合nsIUploadChannel的setUploadStream()方法,請求會加入Content-Length標頭,然後能用nsIUploadChannel的available()方法取得該值。任何包含於串流前端的標頭資訊會被視為訊息內容。串流的MIME型態設定要於呼叫send()前用setRequestHeader()方法設定Content-Type標頭。

傳送binary內容最好的方法是透過ArrayBuffersBlobs,然而,如果要傳送可字串化的原始資料,請使用sendAsBinary()StringView型態陣列的超類別(superclass)。

setRequestHeader()

設定HTTP請求標頭(header),必須要在呼叫open()後、send()前呼叫。

void setRequestHeader(
   DOMString header,
   DOMString value
);
參數
header
標頭名稱
value
標頭值

多次呼叫設定同一個標頭,設定值會接續附加到標頭值之後。

// The codes below would generate the 'Tester-Name' header as:
// Test-Name : mike, peter
var xhr = new XMLHttpRequest();
xhr.open('GET', 'test.html');
xhr.setRequestHeader('Tester-Name', 'mike');
xhr.setRequestHeader('Tester-Name ', 'peter');
xhr.send();

 

非標準方法

init()

C++程式用的物件初始化.

警告: 不可用於Javascript。
[noscript] void init(
   in nsIPrincipal principal,
   in nsIScriptContext scriptContext,
   in nsPIDOMWindow ownerWindow
);
參數
principal
請求使用原則,不可為null。
scriptContext
請求使用腳本內文,不可為null。
ownerWindow
請求相關聯視窗,可為null。

openRequest()

請求初始化,本地端程式碼使用,Javascript程式碼請用open()。

sendAsBinary()

Requires Gecko 1.9 (Firefox 3)

send()方法的分支,用於送出binary資料。

搭配使用FileReader API的readAsBinaryString將能夠做到讀取和上傳任何型態的檔案以及字串化原始資料。

void sendAsBinary(
   in DOMString body
);
參數
body
DOMString型態的請求內容本體,資料會被除去最高有效位元(high-order byte of each character),然後一一轉換成單一位元(byte)字元。

模擬支援(polyfill)

sendAsBinary()方法尚在實驗性質階段,所以並非所有瀏覽器都有支援,下面的程式碼將模擬支援sendAsBinary(),可以讓不支援此方法但支援{型態陣列(typed arrays)}的瀏覽器模擬支援sendAsBinary()。

/*\
|*|
|*|  :: XMLHttpRequest.prototype.sendAsBinary() Polifyll ::
|*|
|*|  https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()
|*|
\*/

if (!XMLHttpRequest.prototype.sendAsBinary) {
  XMLHttpRequest.prototype.sendAsBinary = function (sData) {
    var nBytes = sData.length, ui8Data = new Uint8Array(nBytes);
    for (var nIdx = 0; nIdx < nBytes; nIdx++) {
      ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff;
    }
    /* send as ArrayBufferView...: */
    this.send(ui8Data);
    /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */
  };
}

Note: 在模擬支援程式碼中,我們雖然能傳入ArrayBuffer(如註解掉的ui8Data.buffer)或ArrayBufferView(ui8Data,8-bit unsigned integers型態陣列)作為send()方法使用參數,然而,Google Chrome會丟出” ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead”的警告訊息,另一種可行的做法是以StringViewNon native型態陣列的超類別(superclass) 作為send()方法使用參數。

備註

  • Firefox 3預設允許最多6個XMLHttpRequest同時連到一台伺服器(更之前上限為2),有些互動式網站會一直保持XMLHttpRequest連結開啟,所以開啟多個連線有機會會導致其他新增請求無法連線,瀏覽器因而不再回應使用者或停止刷新畫面等類似當住狀況。如果要更改連線上限可以到about:config修改network.http.max-persistent-connections-per-server設定。
  • Gecko 7.0開始,setRequestHeader()所設定的標頭資訊會隨重新導向一起送出,先前的版本則不會。
  • Gecko的XMLHttpRequest實作了nsIXMLHttpRequest, nsIXMLHttpRequestEventTargetnsIJSXMLHttpRequest介面。

事件

所有的瀏覽器都有支援onreadystatechange屬性。

除了onreadystatechange,各家瀏覽器還都新增了一些事件處理器,例如onload, onerror, onprogress,Firefox也有支援一些新加的事件處理器,請參照nsIXMLHttpRequestEventTargetUsing XMLHttpRequest

較新版的瀏覽器,包括Firefox,都支援除透過on*類別屬性外,也透過addEventListener註冊XMLHttpRequest的事件處理器。

瀏覽器相容性

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (XHR1) 1 1.0 5 (via ActiveXObject)
7 (XMLHttpRequest)
(Yes) 1.2
send(ArrayBuffer) 9 9 ? 11.60 ?
send(Blob) 7 3.6 ? 12 ?
send(FormData) 6 4 ? 12 ?
response 10 6 10 11.60 ?
responseType = 'arraybuffer' 10 6 10 11.60 ?
responseType = 'blob' 19 6 10 12 ?
responseType = 'document' 18 11 10 Not supported Not supported
responseType = 'json' Not supported 10 Not supported 12 Not supported
Progress Events 7 3.5 10 12 ?
withCredentials 3 3.5 10 12 4
timeout Not supported 12.0 8 ? Not supported
responseType = 'moz-blob' Not supported 12.0 Not supported Not supported Not supported
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support ? 0.16 (Yes) ? ? ?

Gecko備註

Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8)停止支援在同步請求下屬用responseType和withCredentials屬性,嘗試使用會導致NS_ERROR_DOM_INVALID_ACCESS_ERR例外錯誤,這項標準也已經送交W3C審核。

Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9)以後支援XMLHttpRequest讀取data:URL

延伸閱讀

文件標籤與貢獻者

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