XMLHttpRequest

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

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

var req = new XMLHttpRequest();

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

方法總覽

屬性

非標準屬性

建構子

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()。

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

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

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內容最好的方法是透過ArrayBuffers或Blobs，然而，如果要傳送可字串化的原始資料，請使用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++程式用的物件初始化.

[noscript] void init(
   in nsIPrincipal principal,
   in nsIScriptContext scriptContext,
   in nsPIDOMWindow ownerWindow
);

參數

principal

請求使用原則，不可為null。

scriptContext

請求使用腳本內文，不可為null。

ownerWindow

請求相關聯視窗，可為null。

openRequest()

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

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); */
  };
}

備註

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

事件

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

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

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

瀏覽器相容性

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。

延伸閱讀

• MDN articles about XMLHttpRequest:
  • AJAX - Getting Started
  • Using XMLHttpRequest
  • HTML in XMLHttpRequest
  • FormData
• XMLHttpRequest references from W3C and browser vendors:
  • W3C: XMLHttpRequest (base features)
  • W3C: XMLHttpRequest (latest editor's draft with extensions to the base functionality, formerly XMLHttpRequest Level 2
  • Microsoft documentation
  • Apple developers' reference
• "Using the XMLHttpRequest Object" (jibbering.com)
• XMLHttpRequest - REST and the Rich User Experience
• HTML5 Rocks - New Tricks in XMLHttpRequest2