XMLHTTPRequest屬性、方法、事件大全&詳解。

XMLHTTPRequest屬性、方法、事件整理大全。

xhr 對象的方法

• open(method:string, url:string, async?:boolean=true, username?:string, password: string)

  • 用於建立 HTTP 請求，但請求並未發送。
  • method, 請求類型，如 GET 、POST 等，大小寫不敏感。
  • url, URL 地址

  • async, 是否異步，默認 true。
    若爲同步請求時

    • xhr.timeout值必須爲 0。
    • xhr.withCredentials值必須爲 false。
    • xhr.responseType值必須爲"",(text 也不容許)。
  • username, 用戶名，通常不用。
  • password, 密碼，通常不用。

• send(body?:Object=null)

  • 定義 HTTP 請求的數據（ body ），當 method 爲 GET、HEAD 時，該參數忽略。body 可爲 ArrayBuffer、Blob、Document(相似 XML 格式數據)、DOMString（字符串）、FormData（表單）。
    ArrayBuffer、Blob、Document、DOMString、Formdata 詳細參考。
    注意：body 參數會影響請求頭部的 content-type 默認值。

    • 若是 data 是 Document 類型，同時也是 HTML Document 類型，則 content-type 默認值爲 text/html;charset=UTF-8 ;不然爲 application/xml;charset=UTF-8；
    • 若是 data 是 DOMString 類型，content-type 默認值爲 text/plain;charset=UTF-8 ；
    • 若是 data 是 FormData 類型，content-type 默認值爲 multipart/form-data; boundary=[xxx]

    • 若是 data 是其餘類型，則不會設置 content-type 的默認值

      若是用 xhr.setRequestHeader()手動設置了中 content-type 的值，以上默認值就會被覆蓋。
      若在斷網狀態下調用 xhr.send(data)方法，則會拋錯：Uncaught NetworkError: Failed to execute 'send' on 'XMLHttpRequest'。一旦程序拋出錯誤，若是不 catch 就沒法繼續執行後面的代碼，因此調用 xhr.send(data)方法時，應該用 try-catch 捕捉錯誤。

    try{
        xhr.send(data)
    }catch(e) {
        //doSomething...
    };

• abort()

  • 若請求已發出，則會終止請求，並將 readyState 置爲 0.
  • 調用後，應將 xhr 對象置爲 null 以促進垃圾回收。因爲內存緣由，不建議重用 xhr 對象。
    擴展閱讀：和瀏覽器異步請求取消相關的那些事
• overrideMimeType(type:string)
  重寫 response 的 content-type。功能如同 xhr.responseType,已能夠摒棄。

• setRequestHeader(header:string, value:string)

  • 設置請求 HTTP 請求頭信息。如content-type、cookie、accept-xxx等。
  • header 參數大小寫不敏感。
  • 必須在open()方法後，send()方法前調用，不然會拋錯。
  • 可調用屢次，最終值不會覆蓋，而是採用追加append方式。

  • 禁止設置如下請求頭，不然會拋錯。

    • Accept-Charset
    • Accept-Encoding
    • Access-Control-Request-Headers
    • Access-Control-Request-Method
    • Connection
    • Content-Length
    • Cookie
    • Cookie2
    • Date
    • DNT
    • Expect
    • Host
    • Keep-Alive
    • Origin
    • Referer
    • TE
    • Trailer
    • Transfer-Encoding
    • Upgrade
    • User-Agent
    • Via

• getResponseHeader(header:string)

  • 獲取某個指定 header 字段的值。
  • header 字段不區分大小寫。
  • 有嚴格安全限制，詳見getAllResponseHeaders方法。

• getAllResponseHeaders()

  • 獲取 response 中全部 header 字段。

  • 有嚴格安全限制。以下：

    • 不管跨域或同域請求，沒法獲取Set-Cookie、Set-Cookie2字段值。

    • 跨域請求，只可獲取simple response header和Access-Control-Expose-Headers（名詞解釋見下方），不然會報錯：Refused to get unsafe header。故若想訪問其餘字段，需後端添加到 Access-Control-Expose-Headers 中。

      simple response header 包括的 header 字段有： Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma。

> `Access-Control-Expose-Headers`：跨域請求獨有，同域請求無。該字段中列舉的 `header` 字段爲服務器容許暴露給客戶端訪問的字段。
> 句法：```Access-Control-Expose-Headers: <header-name>, <header-name>, ...```

---

xhr 的屬性

• readyState
  [只讀屬性]用於追蹤 xhr 當前的狀態，共有 5 種可能的值，分別對應 xhr不一樣的階段。
  每次 readyState 值變化時，都會觸發 xhr.onreadystatechange 事件。

  值	狀態	描述
  0	UNSENT (初始狀態，未打開)	此時 xhr 對象被成功構造， open() 方法還未被調用
  1	OPENED (已打開，未發送)	open() 方法已被成功調用，send() 方法還未被調用。注意：只有 xhr 處於 OPENED 狀態，才能調用 xhr.setRequestHeader()和 xhr.send() ,不然會報錯
  2	HEADERS_RECEIVED (已獲取響應頭)	send() 方法已經被調用, 響應頭和響應狀態已經返回
  3	LOADING (正在下載響應體)	響應體( response entity body )正在下載中，此狀態下 xhr.response 可能已經有了響應數據
  4	DONE (整個數據傳輸過程結束)	整個數據傳輸過程結束，無論本次請求是成功仍是失敗

• status 和 statusText
status 屬性表示 HTTP 響應狀態碼，如 200、302、400等。
  statusText 屬性表示 HTTP響應狀態的描述文本，如 OK、Not Found等。
  注意，在 xhr.onload 事件中，不能簡單的判斷 xhr.status === 200，由於 20x、304等 HTTP 狀態碼也被認爲是請求成功。
  參考如下代碼：

  xhr.onload = function () {
    //若是請求成功
    if((xhr.status >= 200 && xhr.status < 300) || xhr.status == 304){
      //do successCallback
    }
  }

• responseType 和 response
  可在 xhr.send() 前設置 responseType ，用於指定返回的響應數據類型。和 xhr.overrideMimeType() 方法效果相同，推薦使用 responseType。

  • IE10/IE11 不支持 xhr.responseType 爲 json。

  • 部分瀏覽器不支持 xhr.responseType 爲 blob。

    值	描述
    ""	將 responseType 設爲空字符串與設置爲 text 相同， 是默認類型 （其實是 DOMString ）。
    arraybuffer	response 是一個包含二進制數據的 JavaScript ArrayBuffer 。
    blob	response 是一個包含二進制數據的 Blob 對象 。
    document	response 是一個 HTML Document 或 XML XMLDocument ，這取決於接收到的數據的 MIME 類型。使用 XHR 獲取 HTML 請參閱 HTML in XMLHttpRequest 。
    json	response 是一個 JavaScript 對象。這個對象是經過將接收到的數據類型視爲 JSON 解析獲得的。
    text	response 是包含在 DOMString 對象中的文本。
    moz-chunked-arraybuffer	與 arraybuffer 類似，可是數據會被接收到一個流中。使用此響應類型時，響應中的值僅在 progress 事件的處理程序中可用，而且只包含上一次響應 progress 事件之後收到的數據，而不是自請求發送以來收到的全部數據。在 progress 事件處理時訪問 response 將返回到目前爲止收到的數據。在 progress 事件處理程序以外訪問， response 的值會始終爲 null 。
    ms-stream	response 是下載流的一部分；此響應類型僅容許下載請求，僅 IE 支持。

• responseText

  • 默認值爲空字符串 ""
  • 只有當 responseType 爲 text、""時，xhr 對象上纔有此屬性，此時才能調用 xhr.responseText ，不然拋錯。
  • 只有當請求成功時，才能拿到正確值。如下 2 種狀況下值都爲空字符串 ""：請求未完成、請求失敗。

• responseXML

  • 默認值爲 null
  • 只有當 responseType 爲 text、""、document時，xhr 對象上纔有此屬性，此時才能調用 xhr.responseXML，不然拋錯。
  • 只有當請求成功且返回數據被正確解析時，才能拿到正確值。如下 3 種狀況下值都爲 null ：請求未完成、請求失敗、請求成功但返回數據沒法被正確解析時。

• upload

  • 是一個XMLHttpRequestUpload對象，用於收集傳輸信息。支持事件：

    • onloadstart
    • onprogress
    • onabort
    • ontimeout
    • onerror
    • onload
    • onloadend
      具體觸發順序及條件，參考事件章節。
      其中，xhr.upload.onprogress在上傳階段(即xhr.send()以後，xhr.readystate=2以前)觸發，每 50ms 觸發一次。可得到上傳信息、進度等。
      上述事件回調的參數爲 XMLHttpRequestEventTarget 對象，詳見 事件補充。

• timeout

  • 單位毫秒，默認值 0 ，即不設置超時。
  • 計時從onloadstart 事件觸發開始（即xhr.send()開始）,以onloadend 事件觸發爲結束。
  • 在 IE 中，只能在調用open()方法後send()方法前設置。其餘瀏覽器無此限制，但仍然從xhr.send()方法調用計時。
  • 不能爲同步請求設置 timeout ,不然會報錯。
  • 早期較多瀏覽器不支持，可經過 setTImeOut 實現。

• withCredentials
boolean 類型，默認值 false， 用於跨域請求時將 cookie 加入到 request header。

  xhr.withCredentials 與 CORS 什麼關係
  咱們都知道，在發同域請求時，瀏覽器會將 cookie 自動加在 request header 中。但在發送跨域請求時， cookie 並不會自動加在 request header 中。
  形成這個問題的緣由：在 CORS 標準有以下規定，默認狀況下，瀏覽器在發送跨域請求時，不能發送任何認證信息（ credentials）如 cookies 和 HTTP authentication schemes 。除非 xhr.withCredentials 爲 true。
  cookies 也是一種認證信息，在跨域請求中， client 端必須手動設置 xhr.withCredentials=true ，且 server 端也必須容許 request 能攜帶認證信息（即 response header 中包含 Access-Control-Allow-Credentials:true），這樣瀏覽器纔會自動將 cookie 加在 request header 中。
  注意，一旦跨域 request 可以攜帶認證信息， server 端必定不能將 Access-Control-Allow-Origin 設置爲 *，而必須設置爲請求頁面的域名。

xhr 的事件回調

xhr 共有 8 個事件，分別以下：

• onloadstart
• onprogress
• onabort
• ontimeout
• onerror
• onload
• onloadend
• onreadystatechange

事件觸發條件

引用自 你真的會使用 XMLHttpRequest 嗎？

事件	觸發條件
onreadystatechange	每當xhr.readyState改變時觸發；但xhr.readyState由非 0 值變爲 0 時不觸發。
onloadstart	調用xhr.send()方法後當即觸發，若xhr.send()未被調用則不會觸發此事件。
onprogress	xhr.upload.onprogress在上傳階段(即xhr.send()以後，xhr.readystate=2以前)觸發，每 50ms 觸發一次；xhr.onprogress在下載階段（即xhr.readystate=3時）觸發，每 50ms 觸發一次。
onload	當請求成功完成時觸發，此時xhr.readystate=4
onloadend	當請求結束（包括請求成功和請求失敗）時觸發
onabort	當調用xhr.abort()後觸發
ontimeout	xhr.timeout不等於 0 ，由請求開始即 onloadstart 開始算起，當到達xhr.timeout 所設置時間請求還未結束即 onloadend ，則觸發此事件。
onerror	在請求過程當中，若發生 Network error 則會觸發此事件（若發生 Network error 時，上傳尚未結束，則會先觸發 xhr.upload.onerror，再觸發 xhr.onerror ；若發生 Network error 時，上傳已經結束，則只會觸發xhr.onerror ）。注意，只有發生了網絡層級別的異常纔會觸發此事件，對於應用層級別的異常，如響應返回的xhr.statusCode是 4xx 時，並不屬於 Network error ，因此不會觸發 onerror 事件，而是會觸發 onload 事件。

請求正常時，事件觸發順序

1. 觸發 xhr.onreadystatechange (以後每次 readyState 變化時，都會觸發一次)
2. 觸發 xhr.onloadstart //上傳階段開始：
3. 觸發 xhr.upload.onloadstart
4. 觸發 xhr.upload.onprogress
5. 觸發 xhr.upload.onload
6. 觸發 xhr.upload.onloadend //上傳結束，下載階段開始：
7. 觸發 xhr.onprogress
8. 觸發 xhr.onload
9. 觸發 xhr.onloadend

發生 abort / timeout / error 時事件觸發順序

1. 觸發 xhr.onreadystatechange 事件，此時 readystate 爲 4

2. 若是上傳階段尚未結束，則依次觸發如下事件：

   • xhr.upload.onprogress
   • xhr.upload.[onabort或ontimeout或onerror]
   • xhr.upload.onloadend
3. 觸發 xhr.onprogress 事件
4. 觸發 xhr.[onabort或ontimeout或onerror] 事件
5. 觸發 xhr.onloadend 事件

事件補充

xhr.upload.onprogress 和 xhr.onprogress 的回調參數爲 XMLHttpRequestEventTarget 對象。屬性以下：

• lengthComputable
  【只讀】，爲 boolean值，表示資源是否有可計算的長度。
• loaded
  已接收或已上傳的字節數。
• total
  文件總字節數。
• xhr.upload.onprogress 事件觸發於上傳階段，可用於獲取上傳進度。
• xhr.onprogress 事件觸發於下載階段，可用於獲取下載進度。

後續補充計劃

• fetchAPI 整理。
• jQuery.ajax 的實現詳解。
• axios 的實現詳解。

參考資料

• DOMString、Document、FormData、Blob、File、ArrayBuffer 數據類型介紹
• 你真的會使用 XMLHttpRequest 嗎？
• XMLHttpRequest Level 2 使用指南