XMLHttpRequest · Html5+參考

# [net]() XMLHttpRequest模塊管理網絡請求，與標準HTML中的XMLHttpRequest用途一致，差別在于前者可以進行跨域訪問。通過plus.net可獲取網絡請求管理對象。 ### 對象： - [XMLHttpRequest](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest): 跨域網絡請求對象 ### 回調方法： - [XhrStateChangeCallback](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XhrStateChangeCallback): 網絡請求狀態變化的回調函數 ### 權限： permissions ~~~ "XMLHttpRequest": { "description": "跨域網絡訪問" } ~~~ # [XMLHttpRequest]() 跨域網絡請求對象 ### 構造： - [XMLHttpRequest()](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.XMLHttpRequest()): 創建一個XMLHttpRequest 對象，對象創建時不觸發任何時間和網絡請求，需和open，send方法配合使用。 ### 屬性： - [readyState](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.readyState): HTTP 請求的狀態 - [response](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.response): 請求從服務器接收到的響應數據 - [responseText](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.responseText): 請求從服務器接收到的響應數據（字符串數據） - [responseType](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.responseType): 請求響應數據response的類型 - [responseXML](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.responseXML): 請求響應的Document對象 - [status](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.status): 服務器返回的HTTP狀態代碼 - [statusText](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.statusText): 服務器返回的HTTP狀態描述 - [timeout](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.timeout): 請求服務器的超時時間，單位為毫秒（ms） - [withCredentials](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.withCredentials): 是否支持跨域請求 ### 方法： - [abort](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.abort): 取消當前響應，關閉連接并且結束任何未決的網絡活動 - [getAllResponseHeaders](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.getAllResponseHeaders): 獲取HTTP響應頭部信息 - [getResponseHeader](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.getResponseHeader): 獲取指定的HTTP響應頭部的值 - [open](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.open): 初始化HTTP請求參數，例如URL和HTTP方法，但是并不發送請求 - [send](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.send): 發送一個HTTP請求 - [setRequestHeader](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.setRequestHeader): 指定一個HTTP請求的Header ### 事件： - [onreadystatechange](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.onreadystatechange): 網絡請求狀態發生變化事件 # [XMLHttpRequest()]() 創建一個XMLHttpRequest 對象，對象創建時不觸發任何時間和網絡請求，需和open，send方法配合使用。 ~~~ var xhr = new plus.net.XMLHttpRequest(); ~~~ ### 說明： ### 參數：無 ### 返回值： [XMLHttpRequest](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest) : ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="UTF-8"/> <script type="text/javascript"> document.addEventListener('plusready', function(){ var xhr = new plus.net.XMLHttpRequest(); xhr.onreadystatechange = function () { switch ( xhr.readyState ) { case 0: alert( "xhr請求已初始化" ); break; case 1: alert( "xhr請求已打開" ); break; case 2: alert( "xhr請求已發送" ); break; case 3: alert( "xhr請求已響應"); break; case 4: if ( xhr.status == 200 ) { alert( "xhr請求成功："+xhr.responseText ); } else { alert( "xhr請求失敗："+xhr.readyState ); } break; default : break; } } xhr.open( "GET", "http://www.baidu.com/" ); xhr.send(); }, false ); </script> </head> <body onload="onload();"> </body> </html> ~~~ # [readyState]() HTTP 請求的狀態 ### 說明： Number 類型當一個 XMLHttpRequest 初次創建時，這個屬性的值從 0 開始，直到接收到完整的 HTTP 響應，這個值增加到 4。 5 個狀態中每一個都有一個相關聯的非正式的名稱，下表列出了狀態、名稱和含義： 0 Uninitialized，未初始化狀態。XMLHttpRequest對象已創建或已被abort()方法重置。 1 Open，open()方法已調用，但是send()方法未調用。請求還沒有被發送。 2 Sent，send()方法已調用，HTTP 請求已發送到Web服務器。未接收到響應。 3 Receiving，所有響應頭部都已經接收到。響應體開始接收但未完成。 4 Loaded，HTTP響應已經完全接收。 # [response]() 請求從服務器接收到的響應數據 ### 說明： DOMString 類型只讀屬性如果沒有從服務器接收到數據，則為null；否則根據responseType類型決定：如果responseType設置為空字符串或"text"，則返回空字符串；如果responseType設置為"document"，則返回Document對象；如果responseType設置為"json"，則返回JSON對象；若服務器返回的數據與設置的responseType類型不區配，則返回null。 # [responseText]() 請求從服務器接收到的響應數據（字符串數據） ### 說明： DOMString 類型如果還沒有接收到數據的話，就是空字符串。如果 readyState 小于 3，這個屬性就是一個空字符串。當 readyState 為 3，這個屬性返回目前已經接收的響應部分。如果 readyState 為 4，這個屬性保存了完整的響應體。如果響應包含了為響應體指定字符編碼的頭部，就使用該編碼。否則，假定使用 Unicode UTF-8。 # [responseType]() 請求響應數據response的類型 ### 說明： DOMString 類型默認值為空字符串，即reponse為DOMString，類型可設置："document"表示Document對象，"json"表示JSON對象，"text"表示字符串。 # [responseXML]() 請求響應的Document對象 ### 說明： DOMString 類型對請求的響應，解析為 XML 并作為 Document 對象返回。如果請求未成功，或響應的數據無法被解析為XML，則返回null。 # [status]() 服務器返回的HTTP狀態代碼 ### 說明： Number 類型由服務器返回的 HTTP 狀態代碼，如 200 表示成功，而 404 表示 "Not Found" 錯誤。當 readyState 小于 3 的時候讀取這一屬性會返回0。 # [statusText]() 服務器返回的HTTP狀態描述 ### 說明： DOMString 類型這個屬性用名稱而不是數字指定了請求的 HTTP 的狀態代碼。也就是說，當狀態為200的時候它是"OK"，當狀態為404的時候它是"Not Found"。和status屬性一樣，當readyState小于3的時候讀取這一屬性會返回空。 # [timeout]() 請求服務器的超時時間，單位為毫秒（ms） ### 說明： Number 類型超時時間必須在請求發起前設置，否則當前請求將不生效，在當前請求完成后重新發起新請求時生效。其默認值為120秒。 # [withCredentials]() 是否支持跨域請求 ### 說明： Boolean 類型只讀屬性此對象創建的HTTP請求都支持跨域，所以永遠返回true。 # [abort]() 取消當前響應，關閉連接并且結束任何未決的網絡活動 ~~~ void abort(); ~~~ ### 說明：這個方法把XMLHttpRequest對象重置為readyState為0的狀態，并且取消所有未決的網絡活動。例如，如果請求用了太長時間，而且響應不再必要的時候，可以調用這個方法。 ### 參數：無 ### 返回值： void : 無 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="UTF-8"/> <script type="text/javascript"> var xhr=null; function testXHR(){ if(xhr){ return; } xhr=new plus.net.XMLHttpRequest(); xhr.onreadystatechange=xhrStatechange; xhr.open( "GET", "http://www.baidu.com/" ); xhr.send(); } function xhrStatechange(){ switch( xhr.readyState ) { case 0: console.log( "xhr請求已初始化" ); break; case 1: console.log( "xhr請求已打開" ); break; case 2: console.log( "xhr請求已發送" ); break; case 3: console.log( "xhr請求已響應"); break; case 4: if ( xhr.status == 200 ) { console.log( "xhr請求成功："+xhr.responseText ); } else { console.log( "xhr請求失敗："+xhr.readyState ); } break; default : break; } } function abortXHR(){ if(xhr){ xhr.abort(); xhr=null; } } </script> </head> <body> <button onclick="testXHR()">Test XMLHttpRequest</button><br/> <button onclick="abortXHR()">Abort XMLHttpRequest</button> </body> </html> ~~~ # [getAllResponseHeaders]() 獲取HTTP響應頭部信息 ### 說明：把HTTP響應頭部作為未解析的字符串返回。如果readyState小于3，這個方法返回null。否則，它返回服務器發送的所有 HTTP 響應的頭部。頭部作為單個的字符串返回，一行一個頭部。每行用換行符"\r\n"隔開。 ### 參數：無 ### 返回值： DOMString : HTTP 響應頭 # [getResponseHeader]() 獲取指定的HTTP響應頭部的值 ~~~ void getResponseHeader( headerName ); ~~~ ### 說明：其參數是要返回的 HTTP 響應頭部的名稱。可以使用任何大小寫來制定這個頭部名字，和響應頭部的比較是不區分大小寫的。該方法的返回值是指定的 HTTP 響應頭部的值，如果沒有接收到這個頭部或者readyState小于3則為空字符串。如果接收到多個有指定名稱的頭部，這個頭部的值被連接起來并返回，使用逗號和空格分隔開各個頭部的值。 ### 參數： - headerName: *( DOMString ) 可選 *HTTP響應頭數據名稱 ### 返回值： DOMString : HTTP響應頭數據值 # [open]() 初始化HTTP請求參數，例如URL和HTTP方法，但是并不發送請求 ~~~ void open( method, url, username, password ); ~~~ ### 說明：這個方法初始化請求參數以供 send() 方法稍后使用。它把readyState設置為1，刪除之前指定的所有請求頭部，以及之前接收的所有響應頭部，并且把responseText、responseXML、status 以及 statusText 參數設置為它們的默認值。當readyState為0的時候（當XMLHttpRequest對象剛創建或者abort()方法調用后）以及當readyState為4時（已經接收響應時），調用這個方法是安全的。當針對任何其他狀態調用的時候，open()方法的行為是為指定的。除了保存供send()方法使用的請求參數，以及重置 XMLHttpRequest 對象以便復用，open()方法沒有其他的行為。要特別注意，當這個方法調用的時候，實現通常不會打開一個到Web服務器的網絡連接。 ### 參數： - method: *( DOMString ) 必選 *請求URL的HTTP協議方法值可以為"GET"、"POST"。 - url: *( DOMString ) 必選 *請求URL地址 - username: *( DOMString ) 可選 *請求URL所需的授權提供認證資格用戶名 - password: *( DOMString ) 可選 *請求URL所需的授權提供認證資格密碼 ### 返回值： void : 無 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="UTF-8"/> <script type="text/javascript"> var xhr=null; function testXHR(){ if(xhr){ return; } xhr=new plus.net.XMLHttpRequest(); xhr.onreadystatechange=xhrStatechange; xhr.open( "GET", "http://www.baidu.com/" ); xhr.send(); } function xhrStatechange(){ switch( xhr.readyState ) { case 0: console.log( "xhr請求已初始化" ); break; case 1: console.log( "xhr請求已打開" ); break; case 2: console.log( "xhr請求已發送" ); break; case 3: console.log( "xhr請求已響應"); break; case 4: if ( xhr.status == 200 ) { console.log( "xhr請求成功："+xhr.responseText ); } else { console.log( "xhr請求失敗："+xhr.readyState ); } break; default : break; } } </script> </head> <body> <button onclick="testXHR()">Test XMLHttpRequest</button> </body> </html> ~~~ # [send]() 發送一個HTTP請求 ~~~ void send( body ); ~~~ ### 說明：這個方法導致一個 HTTP 請求發送。如果之前沒有調用 open()，或者更具體地說，如果 readyState 不是 1，send() 拋出一個異常。否則，它發送一個 HTTP 請求，該請求由以下幾部分組成：之前調用 open() 時指定的 HTTP 方法、URL 以及認證資格（如果有的話）。之前調用 setRequestHeader() 時指定的請求頭部（如果有的話）。傳遞給這個方法的 body 參數。一旦請求發布了，send() 把 readyState 設置為 2，并觸發 onreadystatechange 事件句柄。如果服務器響應帶有一個 HTTP 重定向，send() 方法或后臺線程自動遵從重定向。當所有的 HTTP 響應頭部已經接收，send() 或后臺線程把 readyState 設置為 3 并觸發 onreadystatechange 事件句柄。如果響應較長，send() 或后臺線程可能在狀態 3 中觸發 onreadystatechange 事件句柄。最后，當響應完成，send() 或后臺線程把 readyState 設置為 4，并最后一次觸發事件句柄。 ### 參數： - body: *( DOMString ) 可選 *請求HTTP提交的數據內容當參數是open方法的method參數為POST時必選 ### 返回值： void : 無 # [setRequestHeader]() 指定一個HTTP請求的Header ~~~ void setRequestHeader( headerName, headerValue ); ~~~ ### 說明：這個Http Header應該包含在通過后續send()調用而發起的請求中。這個方法只有當readyState為1的時候才能調用，例如，在調用了open()之后，但在調用send()之前。如果帶有指定名稱的頭部已經被指定了，這個頭部的新值就是：之前指定的值，加上逗號、以及這個調用指定的值（形成一個數組）。如果Web服務器已經保存了和傳遞給open()的URL相關聯的cookie，適當的Cookie或Cookie2頭部也自動地包含到請求中，可以通過調用setRequestHeader()來把這些cookie添加到頭部。 ### 參數： - headerName: *( DOMString ) 必選 *HTTP Header名稱 - headerValue: *( DOMString ) 必選 *HTTP Header值 ### 返回值： void : 無 ### 平臺支持： - Android - 2.2+ (支持): 不支持設置“User-Agent”、“Cookie”的值。 - iOS - 5.1+ (支持): 不支持設置“User-Agent”的值。 # [onreadystatechange]() 網絡請求狀態發生變化事件 ~~~ xhr.onreadystatechange = function(){ // 判斷xhr狀態 }; ~~~ ### 說明： [XhrStateChangeCallback](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XhrStateChangeCallback) 類型網絡請求狀態發生變化時觸發，通常在函數中判斷對象的state屬性值來獲取當前請求的狀態。 # [XhrStateChangeCallback]() 網絡請求狀態變化的回調函數 ~~~ void onSuccess() { // State changed code. } ~~~ ### 參數：無 ### 返回值： void : 無