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 嗎？

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

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 使用指南