jQuery.ajax() 函數詳解

標籤：back   oca   tle   w3c   power   理解   parser   top   ade   

jQuery.ajax()函數用於通過後台HTTP請求載入遠端資料。

jQuery.ajax()函數是jQuery封裝的AJAX技術實現，通過該函數，我們無需重新整理當前頁面即可擷取遠程伺服器上的資料。

jQuery.ajax()函數是jQuery的底層AJAX實現。jQuery.get()、 jQuery.post()、load()、 jQuery.getJSON()、 jQuery.getScript()等函數都是該函數的簡化形式(都調用該函數，只是參數設定有所不同或有所省略)。

該函數屬於全域jQuery對象(也可理解為靜態函數)。

文法

jQuery 1.0 新增該靜態函數。jQuery.ajax()函數有以下兩種用法：

jQuery.ajax( [ settings ] ] )

jQuery.ajax( url [, settings ] ] )//用法二：jQuery 1.5 新增支援該用法。

參數

請根據前面文法部分所定義的參數名稱尋找對應的參數。

參數settings是一個對象，jQuery.ajax()可以識別該對象的以下屬性(它們都是可選的)：

參數	描述
url	String類型URL請求字串。
settings	可選/Object類型一個Object對象，其中的每個屬性用來指定發送請求所需的額外參數設定。

 

 

 

accepts      Object類型

預設值：取決於dataType屬性。

發送的內容類型要求標頭，用於告訴伺服器——瀏覽器可以接收伺服器返回何種類型的響應。

async　　　　Boolean類型

預設值：true。

指示是否是非同步請求。同步請求將鎖定瀏覽器，直到擷取到遠端資料後才能執行其他動作。

beforeSend　　　　Function類型

指定在請求發送前需要執行的回呼函數。該函數還有兩個參數：其一是jqXHR對象，其二是當前settings對象。這是一個Ajax事件，如果該函數返回false，將取消本次ajax請求。

cache　　　　Boolean類型

預設值：true(dataType為‘script‘或‘jsonp‘時，則預設為false)。

指示是否緩衝URL請求。如果設為false將強制瀏覽器不緩衝當前URL請求。該參數只對HEAD、GET請求有效(POST請求本身就不會緩衝)。

complete　　　　Function/Array類型

指定請求完成(無論成功或失敗)後需要執行的回呼函數。該函數還有兩個參數：一個是jqXHR對象，一個是表示請求狀態的字串(‘success‘、 ‘notmodified‘、 ‘error‘、 ‘timeout‘、 ‘abort‘或‘parsererror‘)。這是一個Ajax事件。

從jQuery 1.5開始，該屬性值可以是數組形式的多個函數，每個函數都將被回調執行。

contents　　　　Object類型1.5 新增

一個以"{字串:Regex}"配對的對象，用來確定jQuery將如何解析響應，給定其內容類型。

contentType　　　　String類型

預設值：‘application/x-www-form-urlencoded; charset=UTF-8‘。

使用指定的內容編碼類別型將資料發送給伺服器。W3C的XMLHttpRequest規範規定charset始終是UTF-8，你如果將其改為其他字元集，也無法強制瀏覽器更改字元編碼。

context　　　　Object類型

用於設定Ajax相關回呼函數的內容物件(也就是函數內的this指標)。

converters　　　　Object類型1.5 新增

預設值：{‘* text‘: window.String, ‘text html‘: true, ‘text json‘: jQuery.parseJSON, ‘text xml‘: jQuery.parseXML}。

一個資料類型轉換器。每個轉換器的值都是一個函數，用於返迴響應轉化後的值。

crossDomain　　　　Boolean類型1.5 新增

預設值：同域請求為false，跨域請求為true。

指示是否是跨域請求。如果你想在同一域中強制跨域請求(如JSONP形式)，請設定為true。例如，這允許伺服器端重新導向到另一個域。

data　　　　任意類型

發送到伺服器的資料，它將被自動轉為字串類型。如果是GET請求，它將被附加到URL後面。

dataFilter　　　　　　Function類型

指定處理響應的未經處理資料的回呼函數。該函數還有兩個參數：其一表示響應的未經處理資料的字串，其二是dataType屬性字串。

dataType　　　　String類型

預設值：jQuery智能猜測，猜測範圍(xml、 json、 script或html)

指定返回的資料類型。該屬性值可以為：

• ‘xml‘ :返回XML文檔，可使用jQuery進行處理。
• ‘html‘: 返回HTML字串。
• ‘script‘: 返回JavaScript代碼。不會自動緩衝結果。除非設定了cache參數。注意：在遠程請求時(不在同一個域下)，所有POST請求都將轉為GET請求。(因為將使用DOM的script標籤來載入)
• ‘json‘: 返回JSON資料。JSON資料將使用嚴格的文法進行解析(屬性名稱必須加雙引號，所有字串也必須用雙引號)，如果解析失敗將拋出一個錯誤。從jQuery 1.9開始，空內容的響應將返回null或{}。
• ‘jsonp‘: JSONP格式。使用JSONP形式調用函數時，如"url?callback=?"，jQuery將自動替換第二個?為正確的函數名，以執行回呼函數。
• ‘text‘: 返回純文字字串。

error　　　　Function/Array類型

指定請求失敗時執行的回呼函數。該函數有3個參數：jqXHR對象、 請求狀態字串(null、 ‘timeout‘、 ‘error‘、 ‘abort‘和‘parsererror‘)、 錯誤資訊字串(響應狀態的文本描述部分，例如‘Not Found‘或‘Internal Server Error‘)。這是一個Ajax事件。跨域指令碼和跨域JSONP請求不會調用該函數。

從jQuery 1.5開始，該屬性值可以是數組形式的多個函數，每個函數都將被回調執行。

global　　　　Boolean類型

預設值：true。

指示是否觸發全域Ajax事件。將該值設為false將阻止全域事件處理函數被觸發，例如ajaxStart()和ajaxStop()。它可以用來控制各種Ajax事件。

headers　　　　Object類型1.5 新增

預設值：{}。

以對象形式指定附加的要求標頭資訊。要求標頭X-Requested-With: XMLHttpRequest將始終被添加，當然你也可以在此處修改預設的XMLHttpRequest值。headers中的值可以覆蓋beforeSend回呼函數中設定的要求標頭(意即beforeSend先被調用)。

$.ajax({
    url: "my.php" ,
    headers: {
        "Referer": "http://www.365mini.com" // 有些瀏覽器不允許修改該要求標頭
        ,"User-Agent": "newLine" // 有些瀏覽器不允許修改該要求標頭
        ,"X-Power": "newLine"
        ,"Accept-Language": "en-US"
    }
});

ifModified　　　　Boolean類型

預設值：false。

允許當前請求僅在伺服器資料改變時擷取新資料(如未更改，瀏覽器從緩衝中擷取資料)。它使用HTTP頭資訊Last-Modified來判斷。從jQuery 1.4開始，他也會檢查伺服器指定的‘etag‘來確定資料是否已被修改。

isLocal　　　　Boolean類型1.5.1 新增

預設值：取決於當前的位置協議。

允許將當前環境視作"本地"，(例如檔案系統)，即使預設情況下jQuery不會如此識別它。目前，以下協議將被視作本地：file、*-extension和widget。

jsonp　　　　String類型

重寫JSONP請求的回呼函數名稱。該值用於替代"url?callback=?"中的"callback"部分。

jsonpCallback　　　　String/Function類型

為JSONP請求指定一個回呼函數名。這個值將用來取代jQuery自動產生的隨機函數名。

從jQuery 1.5開始，你也可以指定一個函數來返回所需的函數名稱。

mimeType　　　　String類型1.5.1 新增

一個mime類型用來覆蓋XHR的mime類型。

password　　　　String類型

用於響應HTTP訪問認證請求的密碼。

processData　　　　Boolean類型

預設值：true。

預設情況下，通過data屬性傳遞進來的資料，如果是一個對象(技術上講，只要不是字串)，都會處理轉化成一個查詢字串，以配合預設內容類型 "application/x-www-form-urlencoded"。如果要發送 DOM樹資訊或其它不希望轉換的資訊，請設定為false。

scriptCharset　　　　String類型

設定該請求載入的指令檔的字元集。只有當請求時dataType為"jsonp"或"script"，並且type是"GET"才會用於強制修改charset。這相當於設定<script>標籤的charset屬性。通常只在當前頁面和遠端資料的內容編碼不同時使用。

statusCode　　　　　　Object類型1.5 新增

預設值: {}。

一組數值的HTTP代碼和函數構成的對象，當響應時調用了相應的代碼。例如：

$.ajax({
    url: a_not_found_url ,
    // 當響應對應的狀態代碼時，執行對應的回呼函數
    statusCode: {
        404: function() {
            alert( "找不到頁面" );
        },
        200: function(){
            alert("請求成功");
        }
    }
});

success　　　　　　Function/Array類型

指定請求成功後執行的回呼函數。該函數有3個參數：請求返回的資料、響應狀態字串、jqXHR對象。

從jQuery 1.5開始，該屬性值可以是數組形式的多個函數，每個函數都將被回調執行。

timeout　　　　Number類型

佈建要求逾時的毫秒值。

traditional　　　　Boolean類型

如果你希望使用傳統方式來序列化參數，將該屬性設為true。

type　　　　String類型

預設值："GET"。

請求類型，可以為‘POST‘或‘GET‘。注意：你也可以在此處使用諸如‘PUT‘、‘DELETE‘等其他請求類型，但它們不被所有瀏覽器支援。

url　　　　String類型

預設值：當前頁面URL。

請求的目標URL。

username　　　　String類型

用於響應HTTP訪問認證請求的使用者名稱。

xhr　　　　Function類型

預設值：在IE下是ActiveXObject(如果可用)，在其他瀏覽器中是XMLHttpRequest。

一個用於建立並返回XMLHttpRequest對象的回呼函數。你可以重寫該屬性以提供自己的XHR實現，或增強其功能。

xhrFields　　　　Object類型1.5.1 新增

一個具有多個"欄位名稱-欄位值"對的對象，用於對本地XHR對象進行設定。一對「檔案名稱-檔案值」在本機設定XHR對象。例如，如果需要，你可以用它來為跨域請求設定XHR對象的withCredentials屬性為true。

$.ajax({
   url: a_cross_domain_url,
   // 將XHR對象的withCredentials設為true
   xhrFields: {
      withCredentials: true
   }
});

注意：
1、如果你的所有AJAX請求都需要設定settings中某些參數，你可以使用jQuery.ajaxSetup()函數進行全域設定，而無需在每次執行jQuery.ajax()時分別設定。
2、在jQuery 1.4(含)之前，選項參數complete、succes、error等Ajax事件的回呼函數的第3個參數不是經過jQuery封裝的jqXHR對象，而是原生的XMLHttpRequest對象。

傳回值

jQuery.ajax()函數的傳回值為jqXHR類型，返回當前該請求的jqXHR對象(jQuery 1.4及以前版本返回的是原生的XMLHttpRequest對象)。

樣本&說明

如果沒有給jQuery.ajax()指定任何參數，則預設請求當前頁面，並且不對返回資料進行處理。

jQuery.ajax()函數的settings對象中，常用的屬性有：url、type、async、data、dataType、success、error、complete、beforeSend、timeout等。

請參考下面這段初始HTML代碼：

<div id="content"></div>

以下是與jQuery.ajax()函數相關的jQuery範例程式碼，以示範jQuery.ajax()函數的具體用法：

$.ajax({     url: "jquery_ajax.php"    , type: "POST"    , data: "name=codeplayer&age=18"    , success: function( data, textStatus, jqXHR ){        // data 是返回的資料        // textStatus 可能為"success"、"notmodified"等        // jqXHR 是經過jQuery封裝的XMLHttpRequest對象        alert("返回的資料" + data);    }});$.ajax({     url: "jquery_ajax.php?page=1&id=3"    , type: "POST"    // jQuery會自動將對象資料轉換為 "name=codeplayer&age=18&uid=1&uid=2&uid=3"    , data: { name:"codeplayer", age:18, uid: [1, 2, 3] }    // 請求成功時執行    , success: function( data, textStatus, jqXHR ){        alert("返回的資料" + data);    }    // 請求失敗時執行    , error: function(jqXHR, textStatus, errorMsg){        // jqXHR 是經過jQuery封裝的XMLHttpRequest對象        // textStatus 可能為： null、"timeout"、"error"、"abort"或"parsererror"        // errorMsg 可能為： "Not Found"、"Internal Server Error"等        alert("請求失敗：" + errorMsg);    }});// 將url單獨提取出來作為第一個參數(jQuery 1.5+才支援)$.ajax("jquery_ajax.php?action=type&id=3", {     dataType: "json" // 返回JSON格式的資料    , success: function( data, textStatus, jqXHR ){        // 假設返回的字串資料為{ "name": "CodePlayer", age: 20 }        // jQuery已幫我們將該JSON字串轉換為對應的JS對象，可以直接使用        alert( data.name ); // CodePlayer    }   });$.ajax( {    // 注意這裡有個參數callback=?     url: "http://cross-domain/jquery_ajax.php?name=Jim&callback=?&age=21"    , async: false // 同步請求，發送請求後瀏覽器將被鎖定，只有等到該請求完成(無論成功或失敗)後，使用者才能操作，js代碼才會繼續執行    , dataType: "jsonp" // 返回JSON格式的資料    , success: function( data, textStatus, jqXHR ){        // 假設返回的字串資料為{ "site_name": "CodePlayer", "site_desc": "專註於編程開發技術分享" }        // jQuery已幫我們將該JSON字串轉換為對應的JS對象，可以直接使用        alert( data.site_desc ); // 專註於編程開發技術分享    }   });$.ajax( {    // 載入指定的js檔案到當前文檔中     url: "http://code.jquery.com/jquery-1.8.3.min.js"    , dataType: "script"});

 

jQuery.ajax() 函數詳解